The Events API provides advertisers with a reliable server-to-server connection between Roku Ads Manager and an advertiser's marketing data (e.g., website, app, and offline events), while giving you the ability to customize the information that you share with Roku.
This article describes how to use the Events API, and why.
Consider these articles for more information on events:
General Events API Information
What is it?
The Events API is a server-to-server integration that allows you to share data directly with Roku for measurement, campaign optimization, and custom audience targeting (coming soon).
The Events API enables:
Server-side tracking: Avoid cookie-dependency for more accurate and reliable data.
Consolidated insights: Measure conversions across multiple channels with a single API.
Better control: Easily customize what data you share and when.
Why is it Important?
The Events API can drive unique advantages for your business:
Improved performance: Leverage more complete data for better campaign optimization and conversion attribution.
Robust targeting: Create event-based custom audiences in real time to re-engage your existing customers.
Competitive advantage: Gain deeper insights than pixel-reliant competitors.
Sustainable solutions: The Events API, along with an existing Pixel, offers a more durable measurement solution amidst changes in the advertising ecosystem.
What is the difference between Roku’s Events API and Roku’s Pixel tracking solutions?
Both Roku Pixel tracking and Roku Events API allow you to share event data with Roku. However, the Events API sends data directly from your servers to Roku’s servers, rather than through your customer’s browser, and thus doesn’t rely on browser-based cookies like the pixels (which can be limited by browser restrictions, ad blockers, and user cookie preferences).
When to use Pixels vs Events API?
Choosing between the Events API and pixel tracking depends on your business’s specific needs, goals, and resources. Where feasible, we recommend using both tools together to provide you with the most accurate and complete tracking data and insights.
Pixels are ideal for: Beginners, businesses with basic tracking needs, and quick, user-friendly implementations.
Events API is ideal for: Complex tracking requirements and advanced marketers seeking deeper insights.
Below we will compare the pros and cons of Pixels and Events API:
| Pros | Cons |
Pixels |
|
|
Events API |
|
|
Events API setup
Authentication
An API key is needed in the Authorization header of your HTTP request to send data.
To generate an API key, visit the Settings page within the Events tab of Ads Manager.
Next, click “Generate new API key.” This action can only be taken by Organization or Account Admins.
API keys do not expire. However, if you believe your API key has been compromised, you can revoke an existing API key and create a new one.
Make sure to pass the generated API key in the authorization header in the Events API requests.
Events API reference
The following table summarizes the basic information for the Events API:
Item | Description |
Endpoint | |
Protocol | Event API calls may only be sent using HTTPS. |
Methods | The Events APIs support the following REST methods for onboarding event data:
|
Format | The Events API supports JSON-formatted data. |
Header | Requests to the Events API require the following headers:
|
Response Codes | The Event APIs return one of the following response codes:
|
Available Endpoints
Endpoint | Method | Description |
| POST | Submit conversion events |
| POST | Test event submission without processing |
JSON body
You can include the following parameters in the JSON body of a POST request to the Events API:
Parameter | Type | Required/Optional | Description |
event_group_id | string | Required | The ID that all these events belong to. An event group is used to represent one online property such as a website or app/channel. |
events | array of objects | Required | Events you wish to pass to Roku through the Events API. See the below table for details on fields that make up a single event object.
|
Event Object Parameters
You can include the following parameters in the event object:
Parameter | Type | Required/Optional | Description |
event_id | string | Optional | The unique string generated by the site. Used for deduplication: If you install the Roku Pixel (client-side) on your website and are sending events using the Events API (server side), then make sure to pass this field from both client and server side to eliminate duplicate fires from client-side and server-side. |
event_name | string | Required |
|
event_source | string | Optional | Sources of conversion events include, but are not limited to, the following:
|
event_source_url | string | Optional | The web page URL where the event originated. The protocol may be HTTP or HTTPS. |
event_time | integer | Required | A UNIX timestamp in epoch seconds when the event occurred. |
event_type | string | Required | Set this to "conversion". This field may support other event types (for example, "clicks", "impressions", and so on) in the future. |
referrer_url | string | Optional | The web page URL where the user was directly before landing on the subject URL. |
user_data | object | Required | A map containing customer information data. One of the following values must be provided or the request will be rejected: email, aGA, AID, aDX, aGI, or aRI. |
custom_data | object | Optional | A map that includes additional business data about the event such as revenue, SKU, order ID, and other identification data. |
opt_out | string | Optional | Limited Data Use (LDU) is a data processing option that lets you limit how your event data is used in Roku's systems and helps to better support your compliance efforts with various US state privacy laws. A value of "true" triggers the LDU flag. See the LDU article for more detailed implementation instructions. |
partner_name | String | Optional | Name of the partner, in cases where a 3rd party is sending events on behalf of an advertiser |
User Data Object Parameters
The user_data object may include the following parameters:
Values requiring hashing (SHA-256)
Parameter | Description |
em | Hashed email address (must be normalized prior to hashing) |
ph | Hashed phone number (must be normalized prior to hashing) |
fn | First name |
ln | Last name |
ge | Gender (should be one of male, female, unknown) |
db | Date of birth (only accepted format yyyy-mm-dd) |
Normalizing Raw Data Before Hashing
Raw email addresses and phone numbers must be normalized before being hashed. To normalize, follow these rules:
Email addresses:
Lowercase the email address.
Trim all leading and trailing whitespaces.
Remove all characters after "+" and before "@" (for example, normalize myname+alias@isp.com to myname@isp.com).
Phone numbers:
Remove all special characters including "+" or "-".
Remove all zeros at the beginning of the number.
Trim all whitespaces.
Values that should not be hashed
Parameter | Description |
ct | City (please provide complete name) |
st | State (please provide complete name) |
zp | Zip code |
country | Country |
external_id | External ID |
client_ip_address | Client IP address |
client_user_agent | Client user agent |
subscription_id | Subscription ID |
aGA | Google or Android mobile ad ID |
aID | Apple mobile ad ID (IDFA) |
aGI | Generic IFA |
aRI | Roku identified for advertising (RIDA) |
aFC | Your first-party cookie |
Custom Data Object Parameters
The custom_data object is optional and may include the following parameters:
Field | Type | Description |
content_category | string | The category of the page/product. |
content_ids | array of integers or strings | The product IDs associated with the event such as SKUs (for example, ['ABC123', 'XYZ789']). |
content_name | string | The name of the page/product. |
content_type | string | Either the product or product_group based on the content_ids or contents being passed. |
contents | array of objects | An array of JSON objects that contains the quantity and the International Article Number (EAN) when applicable, or other product or content identifier(s).
|
currency | string | The currency for the value specified.
|
num_items | integer | The number of items when checkout was initiated. |
predicted_ltv | integer, float | The predicted lifetime value of a subscriber, as defined by the advertiser and expressed as an exact value. |
search_string | string | The string entered by the user for the search. |
status | string | Indicates the status of an order or service. |
value | integer or float | The total amount of the value of all products being purchased.
|
order_id | string | The order ID for this transaction (for example, 'order1234'). |
purchase_type | string | This is to indicate one of the following types of purchase: |
delivery_category | string | The type of delivery for a purchase event. This may be one of the following values:
|
utm_source | string | Source from where the user arrived to the site |
utm_medium | string | Medium from where the user arrived to the site |
utm_campaign | string | Campaign from where the user arrived to the site |
utm_term | string | Keyword terms from where the user arrived to the site |
utm_content | string | Content from where the user arrived to the site |
Response
The following parameters will be included in the response:
Parameter | Description |
code | HTTP response code
|
description | It can be one of the following:
|
events_received | The total event sent in the payload |
failed_events | Contains the raw request body for only invalid events.
|
API Endpoint Details
1. Events API
POST /v1/events
Submit conversion events to be processed by the Roku Ads Manager.
Example Request:
{
"event_group_id": "example_website_123",
"events": [
{
"event_id": "unique_event_id_123",
"event_name": "PURCHASE",
"event_type": "conversion",
"event_time": 1621436800,
"event_source": "website",
"event_source_url": "https://example.com/checkout/confirmation",
"referrer_url": "https://example.com/product/123",
"user_data": {
"is_hashed": true,
"em": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a",
"ph": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
"client_ip_address": "192.168.1.1",
"client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
},
"custom_data": {
"value": 99.99,
"currency": "USD",
"content_type": "product",
"order_id": "order_12345",
"contents": [
{
"id": "product_123",
"quantity": "1",
"price": 99.99,
"delivery_category": "home_delivery"
}
]
},
"opt_out": "false"
}
]
}
Example Response:
{
"code": 200,
"description": "all events were processed",
"events_received": 1,
"failed_events": []
}
2. Test Events API
POST /v1/test_events
Test your event submission without actually processing the events. This is useful for validating your payload format.
Example Request:
{
"event_group_id": "example_website_123",
"events": [
{
"event_id": "test_event_id_456",
"event_name": "ADD_TO_CART",
"event_type": "conversion",
"event_time": 1621436800,
"event_source": "website",
"event_source_url": "https://example.com/cart",
"user_data": {
"is_hashed": true,
"em": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a",
"aGA": "5e2d9c1a-9e9c-4d5b-9c1a-9e9c4d5b9c1a"
},
"custom_data": {
"value": 24.99,
"currency": "USD",
"contents": [
{
"id": "product_456",
"quantity": "1",
"price": 24.99
}
]
}
}
]
}
Example Response:
{
"code": 200,
"description": "all events were processed",
"events_received": 1,
"failed_events": []
}
Error Handling
Common Error Scenarios
1. Missing Required Fields: When mandatory fields like event_name, event_type, or user_data identifiers are missing
{
"code": 400,
"description": "all events failed",
"events_received": 1,
"failed_events": [
{
"event_id": "error_event_id",
"errors": {
"event_name": "event_name is required",
"user_data": "At least one user identifier is required"
}
}
]
}
2. Invalid Enum Values: When a field contains an unrecognized value
{
"code": 400,
"description": "all events failed",
"events_received": 1,
"failed_events": [
{
"event_name": "INVALID_EVENT",
"errors": {
"event_name": "Invalid event name: INVALID_EVENT. Event name must be one of the supported values."
}
}
]
}
Testing and Debugging
The following resources can be used to test and debug your Event API integration.
Resource | URL | Description |
Test Events API Endpoint | A POST method that enables you to send a test request using the same JSON body as the Events API.
|