Skip to main content

Using gRPC

Introduction​

Some of Kevel Audience API's are available through a gRPC interface. In particular, both the Event Storage and User Profile Storage modules provide gRPC interfaces, giving you access to the systems' captured user events and user attributes.

Available Endpoints​

In order to access Kevel Audience API's through gRPC you need to be aware of the available endpoints:

Modulesubdomainporte.g. endpoint
Event-Storageevents8888events.cdp.yourdomain.com:8888
User-Profile-Storageups8888ups.cdp.yourdomain.com:8888
Attributionattribution8888attribution.cdp.yourdomain.com:8888

Note that gRPC endpoints are mostly built for internal consumption, so their APIs are not stable and can change over time.

caution

These endpoints might not be accessible publicly. To request access, please contact your customer support manager.

Tooling​

To quickly experiment with the gRPC APIs from Kevel Audience, the grpc_cli utility can be installed, which provides a terminal utility to call methods from any gRPC server.

info

Contact your customer support manager if you want access to the .proto files for automatic generation of client code.

In MacOS X this can be installed with:

brew tap grpc/grpc
brew install grpc

With this utility, one is fully capable of interacting with any standard gRPC server. For example, to list all the available services and methods on a given events.example.com endpoint: $ grpc_cli ls events.example.com:8888

$ grpc_cli ls events.example.com:8888
com.velocidi.adstax.events.api.grpc.service.EventStorage
grpc.reflection.v1alpha.ServerReflection

$ grpc_cli ls events.example.com:8888 com.velocidi.adstax.events.api.grpc.service.EventStorage
matchEventsSource
matchExtendedEventsSource
matchQuerySource
matchInsertSink
activationEventsSource
activationExtendedEventsSource
activationQuerySource
activationInsertSink
trackingEventsSource
trackingExtendedEventsSource
trackingQuerySource
trackingInsertSink

Using gRPC to Query the Event Storage​

We can use gRPC to query the storage of events. Below, we use the trackingEventsSource method to retrieve a list of user events within a given time range:

$ grpc_cli call events.example.com:8888 trackingEventsSource 'startTime: 1622046484870, endTime: 1622049700000' --json_output
connecting to events.example.com:8888
Received initial metadata from server:
date : Wed, 26 May 2021 00:09:44 GMT
server : akka-http/10.2.4
{
 "method": "GET",
 "uri": {
  "path": "/events",
  "full": "http://tr.example.com/events?cookieCheck=true&_gid=250692547&_v=1.1.0&_cb=1424594661&clientId=example&siteId=example.com&type=pageView&location=https://www.example.com/",
  "fragment": null,
  "query": {
   "_cb": "1424594661",
   "location": "https://www.example.com/",
   "clientId": "example",
   "_gid": "250692547",
   "cookieCheck": "true",
   "_v": "1.1.0",
   "siteId": "example.com",
   "type": "pageView"
  },
  "scheme": "http",
  "authority": {
   "host": "tr.example.com",
   "port": 0,
   "userinfo": ""
  }
 },
 "entity": null,
 "headers": {
  "Upgrade-Insecure-Requests": "1",
  "Referer": "https://www.example.com/",
  "Sec-Fetch-Dest": "iframe",
  "Sec-Fetch-Site": "same-site",
  "Connection": "keep-alive",
...
...
...

Some of the gRPC methods provided by the Event Storage module accept a single string parameter named query. This parameter represents a query string in AOQL language. AOQL tries to abstract some of the differences between the storage infrastructure of different events types while providing a common set of operations that can be used to query all different events.

For example, here is the previous trackingEventsSource query now executed using an AOQL query string:

$ grpc_cli call events.example.com:8888 trackingQuerySource 'query: "SELECT * FROM TrackingEvents where meta.timestamp >= 1622046484870 AND meta.timestamp < 1622049700000"' --json_output

Please refer to the AOQL documentation for details on its usage.

Using gRPC to Query the User Profile Storage​

We can use gRPC to query the storage of user profiles. Below, we use the get method to fetch information about a particular user:

$ grpc_cli call ups.example.com:8888 get "userId: { id: 'e7f0d3ddd1e007d161b494b63cda7893', idType: '1pCookie' }, filters: { includeUserId: { allUserIds: {} }, includeBaseAttributes: { allAttributes: {} }, includeComputedAttributes: { allAttributes: {} } }" --json_output
connecting to ups.example.com:8888
Received initial metadata from server:
date : Tue, 25 May 2021 14:07:08 GMT
server : akka-http/10.2.4
{
 "userExists": true,
 "reliableUserIds": [
  {
   "idType": "1pCookie",
   "id": "e7f0d3ddd1e007d161b494b63cda7893"
  }
 ],
 "baseAttributes": {
  "attributes": {
   "geo.city.latest": "Porto",
   "geo.latlong.list": [
    [
     -23.4167,
     -51.9167
    ]
   ],
   "predictions.likelihoodToBuy.all.2days": 0.41987584144849815,
   "devices.userAgent.list": [
    "Chrome"
   ],
   "devices.type.list": [
    "pc"
   ]
  }
 },
 "computedAttributes": {
  "attributes": {
   "likely_to_purchase": true,
   "afternoon_email": false,
   "retargeting_optimized": true,
   "l2b": true,
   "social_network": false,
   "morning_email_segment": false
  }
 }
}

We can also query for a bulk of users, for example, using a sample of 50%:

$ grpc_cli call ups.example.com:8888 userSource 'sample: 0.5, filters: { includeUserId: { allUserIds: {} }, includeBaseAttributes: { allAttributes: {} }, includeComputedAttributes: { allAttributes: {} } }' --json_output

Or filter by specific user attributes. For example, users who had at least one orderPlace event:

$ grpc_cli call ups.example.com:8888 userSource 'sample: 1.0, filters: { includeUserId: { allUserIds: {} }, includeBaseAttributes: { allAttributes: {} }, includeComputedAttributes: { allAttributes: {} } }, query: { value: "events.orderPlace.count > 0" }' --json_output
Last updated on