Event API
The Event API offers another option for advertisers looking to integrate conversion data with Rokt. Using the Event API, your backend server can securely connect to Rokt's, transmitting conversion data in real time.
Using the Event API as a standalone integration for conversion data provides multiple benefits:
- Speed: Enables a fully automated, near-real time data exchange, maximizing the potential of Rokt’s automated optimization tools.
- Coverage: Permits integration of events across all channels and devices, resulting in coverage for conversions across web, mobile, and in-store.
- Reliability: As a server-to-server integration, the Event API is not susceptible to any interference by web technologies such as browser or ad blocking. It also supports error handling, ensuring that data is never lost.
Authentication
Reach out to your Rokt account manager to create a public and secret key pair for the accounts for which you would like to
submit conversion events. These keys take the form of rpub- and rsec- respectively.
Build your request headers
| Name | Value | Required | Description |
|---|---|---|---|
Content-Type | application/json | Yes | N/A |
Charset | utf-8 | Yes | N/A |
Rokt-Version | 2020-05-21 | Yes | API version for Rokt. Currently latest version is 2020-05-21. Note: Leaving this header empty applies the latest version, which could potentially be backward incompatible. Invalid value would yield 400 bad request. |
Authorization | Basic base64(rpub-...:rsec-...) | Yes | Standard basic authentication header, with the credential value being a base64 encoding of rpub- and rsec- joined by a colon. |
View full reference details for the Event API.
Sample
POST /v2/events
{
"accountId": "12345",
"events": [
{
"clientEventId": "ff3bd69c-ca74-4337-af91-4d5d0bd00e38",
"eventTime": "2020-05-22T10:21:29.339Z",
"eventType": "conversion",
"objectData": [
{
"name": "email",
"value": "email123@emailserver.com"
},
{
"name": "transactionid",
"value": "123456789"
},
{
"name": "amount",
"value": "99.80"
},
{
"name": "currency",
"value": "USD"
},
{
"name": "quantity",
"value": "2"
},
{
"name": "conversiontype",
"value": "hotel_booking"
},
{
"name": "margin",
"value": "10"
},
]
}
]
Suggested objectData fields
The objectData object is made up of key-value pairs that contain metadata about the event. In order to properly attribute conversions, you must include one of email (email), SHA-256 hashed email (emailsha256), or Rokt ID (passbackconversiontrackingid) in objectData so that Rokt can identify the customer.
For the conversion reporting use case, we recommend you include the following attributes.
| Field name | Description | Example |
|---|---|---|
email | Email passed as plain text, lowercase and without trailing spaces | john@email.com |
emailsha256 | SHA256 hash of email address. Prior to hashing, lowercase and without trailing spaces. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
passbackconversiontrackingid | Also known as Rokt ID. A Rokt-generated ID used to match conversion events to the originating click. Requires a separate integration. | 1bc29b36f623ba82aaf6724fd3b16718 |
amount | Value of the transaction (allows decimal points) | 100.25 |
currency | Currency code | USD |
quantity | The quantity (integer) of item within the specific conversion | 4 |
conversiontype | Used to differentiate between different conversion events. Note: Only applicable if the default conversion event type is provided. | ticketpurchase, seatupgrade signup |
productname | The name of the product(s) purchased. You can separate multiple items with a comma. | Maroon 5 t-shirt, Warriors vs. Raptors |
sku | The identifier of the product purchased (Note: Only accepts one SKU) | 230847, tshirt-blue-39487, 398fhdnff |
paymenttype | The payment method used during the transaction | VISA, American Express |
margin | Profit margin of conversion | 10 |
transactionid | Transaction ID, used to identify a unique transaction. Note: If provided, Rokt uses this identifier to deduplicate conversion events across channels. | ABC789 |
confirmationref | Confirmation reference ID. Alternate identifier that may be used to identify a unique transaction and/or track order confirmations. Note: If provided, Rokt uses this identifier to deduplicate conversion events and transactionid is unavailable. | XYZ123 |
firstname | Customer's first name | John |
lastname | Customer's last name | Smith |
mobile | Mobile phone number of converting customer | 3053211654, +1 (323) 867-5309 |
ipaddress | Customer's IP address | 172.3.51.182 |
Custom attributes
Rokt has a data mapping system that allows us to map provided field names to our internal data fields, however we have some recommended field names and formatting requirements later in this article. If you would like to use alternate field names, let us know, and we will ensure your fields are managed accordingly. Additionally, we can accept any additional fields if you would like to provide them for reporting purposes.
Premium integration: Combining the Web SDK and Event API
If possible, we recommend setting up conversion reporting through both the Web SDK and Event API. This helps identify any anomalies and provides redundancy if there are any issues on the frontend or backend.
If you choose to set up both integrations, ensure you populate one of transactionid or confirmationref in both the Web SDK and Event API integrations. Rokt can then deduplicate incoming your conversion events using these variables, ensuring that your reporting is accurate.