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.
Add the Event API
Make sure you can log in to Rokt's my.rokt.com and obtain your Account ID. If you don't have an account, reach out to your account manager.
Get your App ID and App Secret from my.rokt.com. You need this information in order to authenticate the Event API. View steps to retrieve your credentials.
Assemble your payload for the Event API. You can use the
POST /v1/eventsendpoint to send any type of conversion event to Rokt.For this use case, always set
eventTypetoconversionso that Rokt knows to trigger the conversion attribution process.Include relevant key-value pairs in the
objectData. Providing relevant contextual data helps Rokt better optimize your campaigns in the future.Rokt requires at least one of email (
email), SHA-256 hashed email (emailsha256), or Rokt ID (passbackconversiontrackingid) so that Rokt can identify the customer. SuggestedobjectDatafields are available in the table below.
Full endpoint referenceView full reference details for the Event API.
Sample
POST /v1/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.