Roku Ads

Roku Ads Manager is self-serve. It supports a JavaScript Pixel and server-to-server CAPI for web, app, and offline events. Roku Ads Manager overview

Use ad-conversion-hub for the canonical event envelope, consent gate, identity rules, retries, and adapter contract. Pair this skill with ad-experiments for audience tests, seed sizing, and PII-export authorization.

Account and access

Roku documents self-serve signup at ads.roku.com. The signup flow collects organization details, email, agency status, consent to the Ads Manager terms, and the B2B privacy notice. Roku sends an activation link. Create the ad account with business details. Create an account

An organization or account admin generates the CAPI credential in Ads Manager: open Events, select CAPI, then select Generate an API key. Roku says the key does not expire and can be revoked if compromised. CAPI authentication

These local adapter names are not Roku-defined environment variables:

ROKU_PIXEL_ID       public Pixel ID from the Ads Manager event setup
ROKU_EVENT_GROUP_ID event group ID for the website, app, or channel
ROKU_CAPI_API_KEY   server-only key generated in Ads Manager

The fetched Roku CAPI reference documents event and test submission only. It does not document campaign CRUD or a reporting API. Use Ads Manager for setup. Do not invent a campaign-management endpoint. CAPI reference

Client-side JavaScript Pixel

Find the Pixel in Events → Set up events with Roku. Install the generated base code in the website header. Roku says events cannot fire without the base Pixel, and the base Pixel automatically includes PAGE_VIEW. Pixel setup

Roku’s published example loads its CDN script and initializes the Pixel:

<script>
  !function(e,r){if(!e.rkp){var t=e.rkp=function(){
    var e=Array.prototype.slice.call(arguments);
    e.push(Date.now()),t.eventProcessor?t.eventProcessor.apply(t,e):t.queue.push(e)
  };t.initiatorVersion="1.0",t.queue=[],t.load=function(e){
    var t=r.createElement("script");t.async=!0,t.src=e;
    var n=r.getElementsByTagName("script")[0];
    (n?n.parentNode:r.body).insertBefore(t,n)
  },rkp.load("https://cdn.ravm.tv/ust/dist/rkp.loader.js")}
  }(window,document);
  rkp("init", "<ROKU_PIXEL_ID>");
</script>

Add selected events after the base code, close to the action that occurred:

rkp("event", "SIGN_UP", { event_id: canonicalEvent.event_id });
rkp("event", "PURCHASE", {
  event_id: canonicalEvent.event_id,
  value: canonicalEvent.value,
  currency: canonicalEvent.currency,
  order_id: canonicalEvent.order_id,
});

Rule setup and event mapping

Roku Ads Manager lets an advertiser choose which events to implement and which events to use as conversions for reporting and optimization. The documented standard event names include the following mappings. Event types

SUBSCRIPTION_CANCELLATION and SUBSCRIPTION_RENEWAL are also documented event names. Use them only for those lifecycle events. CAPI event names

Server-side Conversions API

Roku documents this CAPI endpoint:

POST https://events.ads.rokuapi.net/v1/events

Use HTTPS and JSON. Roku documents these headers:

Accept: application/json
Content-Type: application/json
Authorization: Bearer <ROKU_CAPI_API_KEY>

The body requires event_group_id and events. Roku accepts up to 1,000 events in one array and validates each event independently. CAPI body

{
  "event_group_id": "<ROKU_EVENT_GROUP_ID>",
  "events": [
    {
      "event_id": "<CANONICAL_EVENT_ID>",
      "event_name": "PURCHASE",
      "event_type": "conversion",
      "event_time": 1730017211,
      "event_source": "website",
      "event_source_url": "<EVENT_SOURCE_URL>",
      "user_data": {
        "is_hashed": true,
        "em": "<SHA256_EMAIL_HEX>"
      },
      "custom_data": {
        "value": 25.00,
        "currency": "USD",
        "order_id": "<ORDER_ID>"
      },
      "opt_out": "false"
    }
 ]
}

Roku documents value, currency, and order_id in optional custom_data; include them for purchase revenue reporting. Custom data parameters

For CAPI, event_name, event_time, event_type, and user_data are required event fields. event_time is a UNIX timestamp in epoch seconds; set event_type to conversion. Event object parameters

Roku documents 200 for success and 210 for partial success. A response can include failed_events with an error for each invalid event. Record that response in the hub dispatch log and retry only under the hub policy. CAPI responses

Identity and consent

Roku requires user_data and at least one supported identifier. Its CAPI reference lists IP address, em, ph, aGA, AID, aDX, aGI, and aRI as accepted identifier options. User data requirements

For email and phone, Roku requires normalization before SHA-256 hashing:

• Lowercase and trim email.
• Remove the alias between + and @ in an email address.
• Format a phone number as E.164 with its leading + and country code.
• Remove phone formatting characters and local leading zeros.
• Send a 64-character lowercase hexadecimal hash, not Base64.

These rules come from Roku’s CAPI reference. Do not double-hash an existing digest. Normalization and hashing and hub identity rules

Apply the hub consent gate before hashing or dispatch. Require measurement consent before any Roku event. Require ad-user-data consent before sending hashed email, phone, or external identifiers. Keep raw identifiers inside the server boundary. Hub consent contract

Roku documents opt_out as an optional LDU field. The string value "true" triggers the LDU flag. Map the approved consent decision to this field only when the event is otherwise allowed to dispatch. Roku LDU field

Click ID and first-party cookie

The fetched Roku CAPI schema documents referrer_url, but it does not define a Roku-owned click-ID query parameter. Do not invent a click parameter or treat aRI as one. Roku does document utm_source, utm_medium, utm_campaign, utm_term, and utm_content as optional custom-data fields. CAPI fields

Roku documents a first-party cookie created by the Pixel and limited to the advertiser’s web domain. The CAPI user-data field for that value is aFC, and Roku says it should not be hashed. Capture it only with consent and pass it through the adapter when available. First-party cookie matching and CAPI user data

In Ads Manager, first-party cookies are enabled by default. Advanced alias matching requires manual enablement. These controls are under Events → event group → Settings → Data collection options. Data collection options

Deduplication

Roku deduplicates a Pixel event and a CAPI event when both carry the same event_id and fire within 10 minutes. Generate one hub ID, pass it to both paths, and do not create a second browser ID. Roku deduplication rule

Use the payment transaction ID as the canonical purchase ID when the hub can provide it. Do not require a click ID before sending a confirmed purchase. The hub owns that event-ID and no-click-ID behavior. Hub event contract

Ads Manager settings that override code

• The event group binds Pixel, CAPI, and partner connections to a property. Keep ROKU_EVENT_GROUP_ID aligned with Ads Manager. Event groups
• The campaign goal controls optimization. Confirm the event fires before selecting it as the goal. Campaign goals and events
• Ads Manager can report events beyond the selected goal. Event reporting
• Custom Audiences can use Pixel or CAPI event data. Customer-list audiences require at least 1,000 matched Roku households. Custom Audiences
• Roku’s FAQ documents a 14-day view-through attribution window. Treat that as the current documented view-through rule, not as a universal click window. Attribution window

Verification

Test the payload with the documented endpoint:

POST https://events.ads.rokuapi.net/v1/test_events

Use the same JSON body and authorization headers as production. Roku says this endpoint validates the payload without processing or ingesting the events. Test CAPI endpoint

Verify in three layers:

1. Request proof: record the redacted CAPI response. Check code, events_received, and failed_events. A 200 proves request acceptance. It does not prove attribution. CAPI response fields
2. Platform proof: inspect the Ads Manager Events page, Pixel diagnostics, and campaign reporting. Roku says event data can take up to four hours to arrive. Event troubleshooting
3. Business proof: reconcile attributed purchases and subscriptions with payment-provider truth. The dashboard is an attribution view, not the payment ledger. Hub verification

Common pitfalls and security

• Use event_time in epoch seconds. Do not send milliseconds. CAPI event fields
• Use event_source_url in CAPI. The Pixel metadata spelling is event_source_URL; do not mix the two payloads. CAPI fields and Pixel fields
• Keep the event group ID and API key exact. Roku says event group IDs are case sensitive. CAPI troubleshooting
• Do not treat a CAPI 200, a Pixel request, or a live campaign as attributed conversion proof. Check Events and reporting, then reconcile business truth. Roku event reporting FAQ
• Keep ROKU_CAPI_API_KEY in the server secret store. Never put it in a browser bundle, URL, log, screenshot, or commit.
• Load the Pixel only from the official HTTPS origin shown in Roku’s setup example. Pixel loader
• Hash identifiers only after consent permits ad-user data. Delete temporary normalized identifiers after dispatch. Hub security rules
• A missing key or event group must return a logged skipped result. It must not fail a successful payment webhook. Hub adapter contract

Official sources checked (2026-08-31)

• Creating an account
• Setting up JavaScript Pixels and Events
• Conversions API
• Event Types
• Advanced Alias Matching and First-Party Cookies
• Event Tracking and Reporting FAQ
• Custom Audiences
• Event Implementation Troubleshooting