Skip to content
adscapi
← Platforms
Real Conversions API

Roku setup

Set Roku’s tokens once. Then every ads.conversions.track() call fans the event out to Roku server-side — no per-platform code.

Setup guide

Overview

adscapi sends server-side events to the Roku Ads Conversions API (POST https://events.ads.rokuapi.net/v1/events). Email and phone are SHA-256 hashed before they leave your server (is_hashed: true); IP and your own external_id are forwarded raw under ad-user-data consent. Each call is a one-event batch (Roku accepts up to 1000 events per request).

Prerequisites

  • A Roku Ads Manager account with an Organization or Account Admin role (only admins can mint a CAPI key).
  • An Event Group for the property (website or app) you send events for.

1. Create an account

  1. Go to advertising.roku.com and open Roku Ads Manager.
  2. Set up your organization and ad account, then invite yourself as an Admin if needed.
  3. Under Events → Event Groups, create an event group for your website or app.

2. Get your credentials

Secret Where to get it
ROKU_EVENT_GROUP_ID Ads Manager → Events → Event Groups. The Event Group ID identifies the online property you report against.
ROKU_ADS_TOKEN Ads Manager → Events → Conversions API (CAPI) → Generate API key. This is a JWT. Copy it once. Keys do not expire but can be revoked. Admin-only.

3. Configure adscapi

export ROKU_EVENT_GROUP_ID="example_website_123"
export ROKU_ADS_TOKEN="eyJhbGciOi…"   # JWT from the CAPI tab

4. Verify

adscapi verify --platform roku

Expected: [OK ] roku — …. A 401/403 means the JWT is invalid or revoked — see Troubleshooting.

5. Event mapping

Roku requires an uppercase predefined event_name. adscapi maps its canonical events:

Canonical Roku
page_view PAGE_VIEW
lead LEAD
signup SIGN_UP
checkout_created INITIATE_CHECKOUT
purchase PURCHASE

Every event also carries event_type: "conversion" and a UNIX-epoch-seconds event_time. event_id (from your event or transaction id) deduplicates repeats within a 10-minute window.

Troubleshooting

  • HTTP 401 / 403 — the JWT is invalid or was revoked. Mint a new key under Events → Conversions API (Admin only).
  • HTTP 400 — an event was missing a user_data identifier. Roku needs at least one of email, phone, IP, or external_id; pass more of user.*.
  • Low match rate — send raw user.email / user.phone; adscapi normalizes and hashes them (and strips +tags from the email, as Roku does), so never pre-hash.

1. Install adscapi

shell
npm install adscapi
# or run without installing:
npx adscapi platforms

2. Get Roku's tokens

Roku activates once all of these are set. Run npx adscapi platforms to see them, then get each value from Roku’s ads or events dashboard.

ROKU_ADS_TOKENROKU_EVENT_GROUP_ID

3. Set them for adscapi

Export the tokens in the environment that runs your server or the adscapi CLI.

shell
export ROKU_ADS_TOKEN="…"
export ROKU_EVENT_GROUP_ID="…"

4. Verify

check confirms the secrets are present; verify calls Roku’s API to confirm they are valid.

shell
npx adscapi check
npx adscapi verify --platform roku

5. Track a conversion

One call, sent to Roku and every other configured platform. Pass raw email — adscapi hashes per platform. Consent is required.

ts
import { createAdscapi } from 'adscapi';

const ads = createAdscapi();

const results = await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: { email: 'buyer@example.com' },
  consent: { adUserData: true, adPersonalization: true },
});

See the exact request on the Roku payload preview.