Sending events

Synerise uses two APIs to send events, depending on the event type:

• the v4/events API is used to send most events, including custom ones.
  This API offers multiple endpoints specific to a particular event type. In this article, we will take a closer look at using the “Send custom event” endpoint and at the “Batch send events” endpoint.
• the /events/v1 API is used to the following events:
  • recommendation.view
  • recommendation.click
  • item.search.click
    This API offers endpoints to send a single event or multiple events at once. In this article, we will focus on sending a single event.

“Send custom event” endpoint

API reference available here.

This endpoint can be used to send custom events required by your integration.

When you use this endpoint to send an event whose definition doesn’t exist in the system, a definition is created automatically.

The request body must contain the following properties:

• action is the type of event, for example page.visit (default event), dog.bark (custom event).
  When you use a dedicated endpoint for an event type, this parameter is not used.
• client is an object with profile identifiers. It must contain at least one of the following identifiers:
  • id
  • customId
  • uuid
  • email
• label must be a non-empty string. It is a legacy property, currently not used by Synerise and not saved in persistent storage.

The following properties are optional:

• params is an object with additional event parameters that you want to add to the request. Some names are reserved for system use (see API reference for details).

• time is the time when the event occurred (for example, the time when a customer clicked a button), formatted according to ISO 8601. Example:
  If your timezone is UTC-4 and your local time is 09:00:00, May 23, 2022:

  • You can send the time as UTC: 2022-05-23T13:00:00Z
  • You can send the same time with your timezone: 2022-05-23T09:00:00-04:00
  • You can send the same time with a different timezone, if necessary: 2022-05-23T07:00:00-06:00

  All the above examples indicate the same date and time, written in different ways.
  You can include milliseconds, for example 2022-05-23T13:00:00.176Z
  The time sent in this parameter is not affected by the time zone of your workspace. You can use any timezone or the UTC standard.
  When you retrieve an event later, the time is always returned as UTC.

  Important:

  • If no time is provided, the time when the event was received by Synerise is saved as the occurrence time.
  • If the provided time is in the future, it is rejected and the time when the event was received by Synerise is saved as the occurrence time. In the above example, future times would be:
    • later than 2022-05-23T13:00:00Z
    • later than 2022-05-23T09:00:00-04:00
    • later than 2022-05-23T07:00:00-06:00

• eventSalt is a special parameter. Its usage is described in Overwriting events.

The request can be authorized with a JWT of a profile (formerly called a client) or a workspace (formerly called a business profile).

Example

The following cURL request is an example of a custom dog.bark event with a few custom properties: loudness, mood, and mailmanScared:

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer ey...RtH_g' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "dog.bark",
    "client": {
        "id": 5092159999
    },
    "time": "2022-11-28T12:18:27Z",
    "params": {
        "loudness": 3,
        "mood": "happy",
        "mailmanScared": true
    },
    "label": "bark"
}'

Sending a batch of events

You can also send a number of events at once. A batch can include different event types saved to different profiles.

The request body is an array of events similar to when sending a single events, with the following modification:

• if the event is custom, add the "type": "custom" parameter
• if the event has a dedicated endpoint:
  • add the type parameter with the value that corresponds to the name of the dedicated endpoint. For example, if the endpoint of the event is /v4/events/shared, the type is shared.
  • remove the action parameter.

Example

The following cURL request is a batch of two events:

• the same dog.bark event from the previous example
• a client.hitTimer event (the dedicated endpoint is /v4/events/hit-timer), sent to a different profile

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer ey...RtH_g' \
--data-raw '[
    {
        "action": "dog.bark",
        "type": "custom",
        "client": {
            "id": 5092159999
        },
        "time": "2022-11-28T12:18:27Z",
        "params": {
            "loudness": 3,
            "mood": "happy",
            "mailmanScared": true
        },
        "label": "bark"
    },
    {
        "type": "hit-timer",
        "time": "2022-11-26T13:13:48Z",
        "client": {
            "id": 267498412
        },
        "label": "string"
    }
]'

Sending recommendation events

These three types of events should be sent with a different API:

• recommendation.view
• recommendation.click
• item.search.click

They can be sent as single events or as a batch.

The AI events endpoints may use two authorization methods:

• A JWT, same as in other endpoints
• A tracker key sent as the token parameter of the query - this may be the same key included in the tracking code of your website or a separate one. The API reference is available here.

The request body must contain the following properties:

• correlationId is the ID of the recommendation frame where the event occurred. It is included in the extras object of a recommendation request.
• clientUUID is the UUID of the profile which made the request.
• items is an array of item IDs (as strings) that were included in the recommendation frame. It can be empty.

The following properties are optional:

• eventTimestamp is the Unix time of the occurrence, in milliseconds.
  • If no time is provided, the time when the event was received by Synerise is saved as the occurrence time.
  • If a future time is provided, the event is saved with an occurrence time in the future.
• campaignId is the ID of recommendation campaign.

Example: one event

The following cURL request is an example of sending a recommendation.view event. The viewed recommendation included one item.

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/events/v1/single/recommendation.view?token=56ba9d02-aaaa-aaaa-aaaa-018564059ea3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "correlationId": "5b0a0fcd-e76b-425c-b9e8-7d6d7bd4a79b",
    "clientUUID": "e0097757-d1e2-44ac-ba3c-d97979a354c1",
    "items": [
        "89435879453"
    ],
    "eventTimestamp": "2022-12-08T13:23:22Z"
}'

Example: batch of events

All events in a batch must be of the same type. They can use different clientUUIDs.

The following cURL request is an example of sending two recommendation.view events to the same profile (a customer saw two different recommendation frames, so the correlationId is different)

curl --location --request POST 'https://api.synerise.com/events/v1/batch?token=56ba9d02-aaaa-aaaa-aaaa-018564059ea3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "eventType": "recommendation.view",
    "items": [
        {
            "correlationId": "5b0a0fcd-e76b-425c-b9e8-7d6d7bd4a79b",
            "clientUUID": "e0097757-d1e2-44ac-ba3c-d97979a354c1",
            "items": [
                "89435879453"
            ],
            "eventTimestamp": "2022-12-08T13:49:00Z"
        },
        {
            "correlationId": "2232d7f8-611b-451b-a1f1-8134f73a04f0",
            "clientUUID": "e0097757-d1e2-44ac-ba3c-d97979a354c1",
            "items": [
                "475677345"
            ],
            "eventTimestamp": "2022-12-08T13:51:00Z"
        }
    ]
}'