Event API Requests
The Personalization Event API uses standard HTTP methods and returns JSON-formatted responses to requests generated by the Sitemap and other Personalization event sources. The following sections describe the various Event API endpoints that enable you to interact with the Personalization platform.
Send event data to the Personalization dataset specified in the request.
POST /api2/event/<dataset>
https://<accountName>.<instance>.evergage.com/api2/event/<dataset>
| URL Parameter | Required? | Description |
|---|---|---|
accountName | Yes | The Personalization account name. You can find the accountName by accessing Gears from the Personalization UI and reviewing the URL. For example, if the Gears URL is https://demo.us-1.evergage.com/, then the account name is demo. |
instance | Yes | The Personalization instance identifier. You can find this value by accessing Gears from the Personalization UI and reviewing the URL. For example, if the Gears URL is https://demo.us-1.evergage.com/, then the instance identifier is us-1. |
dataset | Yes | Name or identifier of the Personalization dataset you're sending data to. |
application/jsonapplication/x-www-form-urlencoded
Consider the following as sample event data that you would like to send to Personalization.
You can send this event data to Personalization as a JSON payload by minifying the event data to remove whitespaces, including it in the body of your API request, and setting the Content-Type to application/json.
Don’t make POST requests with Content-Type: application/json from an environment that checks for Cross-Origin Resource Sharing (CORS), such as a web browser.
When using Content-Type: application/x-www-form-urlencoded, the event data must be minified and then base64-encoded. Minifying the preceding example event data JSON gives you the following single-line JSON string.
Base64-encoding the above JSON string gives you the value eyJhY3Rpb24iOiJoZWxsbyB3b3JsZCIsInVzZXIiOnsiaWQiOiJ0ZXN0dXNlciJ9fQ==. You can then pass this value via the event key, as shown in the following example request.
Send event data to the Personalization dataset specified in the request.
GET /api2/event/<dataset>
The event data you send in GET requests must be minified, base64-encoded, and passed via the event query parameter in the request URL.
https://<accountName>.<instance>.evergage.com/api2/event/<dataset>?event=<base64-encoded-minified-event>
| URL Parameter | Required? | Description |
|---|---|---|
accountName | Yes | The Personalization account name. You can find the accountName by accessing Gears from the Personalization UI and reviewing the URL. For example, if the Gears URL is https://demo.us-1.evergage.com/, then the account name is demo. |
instance | Yes | The Personalization instance identifier. You can find this value by accessing Gears from the Personalization UI and reviewing the URL. For example, if the Gears URL is https://demo.us-1.evergage.com/, then the instance identifier is us-1. |
dataset | Yes | Name or identifier of the Personalization dataset you're sending data to. |
base64-encoded-minified-event | Yes | The minified and base64-encoded event data string. |
Consider the following as sample event data that you would like to send to Personalization.
To send this event, minify the JSON event data, base64-encode the resulting string, and include it in the event parameter of a GET request, as shown in the following example.
You can also send the GET request via a web browser by accessing the request URL directly in your browser.
You can use GET requests as an alternative to using POST requests for sending event data to your Personalization datasets, if necessary.
The Personalization Event API provides a dedicated endpoint sending events that use trusted Server channels. The API call must be authenticated with a valid API token that is permitted to send events. The API token must be provided via the Authorization header according to the HTTP basic authentication scheme. For more information about creating and configuring an API token in Personalization, see Personalization API Tokens.
- For datasets created after January 28, 2021, the campaign targeting rule is set to
channel: Serverby default. To return server-side campaigns using the Event API, events must be sent via a trusted server channel. For more information on the implications of using or removing thechannel: Serverrule, refer to the Server-Side Templates documentation. - To add authentication to server-side campaigns for datasets created before January 28, 2021, Create a Support Case.
application/json
POST /api2/authevent/<dataset>
https://<accountName>.<instance>.evergage.com/api2/authevent/<dataset>
| URL Parameter | Required? | Description |
|---|---|---|
accountName | Yes | The Personalization account name. You can find the accountName by accessing Gears from the Personalization UI and reviewing the URL. For example, if the Gears URL is https://demo.us-1.evergage.com/, then the account name is demo. |
instance | Yes | The Personalization instance identifier. You can find this value by accessing Gears from the Personalization UI and reviewing the URL. For example, if the Gears URL is https://demo.us-1.evergage.com/, then the instance identifier is us-1. |
dataset | Yes | Name or identifier of the Personalization dataset you're sending data to. |
application/json
Authorization: Basic <base64-encoded-API-token>
The Event API uses API tokens to authenticate requests. Your API token must be a strict Base64 encoding of your API Key ID and its API Secret Key, separated by a colon. You can use an existing API token with required permissions or request an administrator to create one via the Personalization UI at Security > API Tokens > Create Token. For more information about API tokens, see Personalization API Tokens.
Alternatively, if you use cURL to interact with the API, you can send your API Key ID and its API Key Secret using the -u "apiKeyId:apiKeySecret" command-line option. cURL automatically converts the apiKeyId:apiKeySecret pair into a Base64-encoded string and adds Authorization: Basic <base64-encoded-API-token> to the request header.
Consider the following as sample event data that you would like to send to Personalization.
You can send this event data via the trusted channel via a POST request to the dedicated endpoint, as shown in the following example request. Ensure that you minify the event JSON data into a single line by removing all whitespaces before sending it via the POST request.