# Trillboards Partner Integration Guide — Native IMA SDK (Android) **Status:** Production-verified. First successful integration: Take 10 Media, April 2026. **Fill rate achieved:** 61% (Adipolo). Completion rate: 79% of fills. Effective: 48% of all ad requests. This guide documents the exact integration that works for native Android IMA SDK on Rockchip-class devices. Follow it literally — every point here was discovered the hard way through a week of debugging. --- ## 0. Integration requirements — read this before you write any code Every line below is a hard requirement, not a suggestion. Each one exists because a partner shipped without it and lost revenue or went black on-screen. If you only read one section of this guide, read this one. **R1 — The waterfall is a LOOP, not a single tag.** `/ads` returns `header_bidding_settings.vast_waterfall.sources[]` — an **array**. You must iterate **every** source, in `priority` **ascending** order, and skip any source with `enabled: false`. Reading `sources[0].vast_url` and stopping is the single most common integration bug we see. Response shape: [§4](#4-the-ad-request--get-v1partnerdevicedeviceidads). Loop contract + pseudocode: [§4.1](#41-the-waterfall-loop-contract). **R2 — Advance on EVERY failure, not just "no ad".** Move to the next source on no-fill, empty/zero-`` VAST, HTTP error, per-source timeout, IMA **load** error, *and* IMA **playback** error. Named VAST codes you must treat as "try the next source", never as "stop": **303** (no ads VAST response after wrapper), **300** (wrapper URI unparseable/timeout), **301** (wrapper timeout / unresolvable), **1009** (empty VAST response). See [§4.1](#41-the-waterfall-loop-contract). **R3 — Budget both clocks.** Each source has its own `timeout_ms` — apply it per source. The whole loop is capped by `vast_waterfall.total_timeout_ms` — when that budget is spent, stop trying sources and return to content. Never let one slow source eat the whole break. **R4 — ALWAYS handle player error. Never leave the surface black.** Register `Player.Listener.onPlayerError` (Media3) or `AdErrorEvent.AdErrorListener` + your own content-playback error path (raw IMA). On any error you must fall back to your own content or a house creative. A black screen is worse than no ad — the venue sees it, and so does the earner. The exact ExoPlayer footgun that produced a fleet of black screens is worked through in [§6.1](#61-pitfall-the-uriempty-content-resume-black-screen-media3--ima). **R5 — Fire the `` beacon.** Every VAST we serve — the programmatic wrap path *and* the first-party `trillboards_direct` rail — carries an `` element with the `[ERRORCODE]` macro. On any ad failure, substitute the numeric IMA/VAST error code for `[ERRORCODE]` and fire that URL. On the first-party rail this beacon is the **only** ad-failure signal that exists: we ship no agent to your player, so if you do not fire it we are structurally blind to your failures and cannot tell "nothing broke" from "everything broke". See [§7.1](#71-the-error-beacon--mandatory). **R6 — Report `programmatic-event`.** `ad_started` / `ad_ended` / `no_fill` / `error`, each with `request_id` + `variant_name` from the source you actually used. See [§7](#7-reporting-events-back--post-v1partnerdevicedeviceidprogrammatic-event). ### Reference implementation and self-verification - **Reference implementation:** [`trillboard-screen/public/partner-sdk/trillboards-lite.src.js`](https://github.com/trillboards/packages/blob/production/trillboard-screen/public/partner-sdk/trillboards-lite.src.js) — the Trillboards Lite SDK. Its `onAdError` handler is the canonical shape of R2 + R5: it classifies 303/1009 as no-fill, fires the `` pixel with `[ERRORCODE]` substituted, records the VAST request outcome, reports the `programmatic-event`, and **only** resolves the caller once the pending waterfall sources are exhausted. When in doubt about ordering or classification, copy what it does. - **Self-verification:** append **`?test=1`** to your `/ads` call. That forces a guaranteed-fill test source (public alias `src_test`, a direct MP4 with no wrapper chain) into that one response — no allowlist enrollment, no revenue impact, real devices polling without the flag are unaffected. If `src_test` plays end-to-end but real sources don't, your VAST handling is fine and the problem is in the partner-response path. If `src_test` *doesn't* play, the bug is in your player. --- ## 1. What this guide is for You are integrating the Trillboards `/ads` endpoint into a native Android player that uses Google IMA SDK (not WebView). Your devices are digital signage — kiosks, TVs, menu boards, ATM toppers — running a custom Android app with Media3 + ImaAdsLoader or raw IMA SDK. This path is the highest-performing integration for partner devices. It gives you server-side wrapper chain resolution, device-specific demand targeting, and full impression attribution. --- ## 2. Required endpoints (five of them) All base URLs: `https://api.trillboards.com`. Partner API key auth on registration only. | # | Method | Path | Purpose | |---|---|---|---| | 1 | POST | `/v1/partner/device/{deviceId}/heartbeat` | Every 60s. Reports device identity. | | 2 | GET | `/v1/partner/device/{deviceId}/ads` | Request waterfall of VAST sources. | | 3 | GET | `/openrtb/v1/vast-wrap/{provider}/{screenId}?url=...&req=...&var=...&pt=partner_api` | Fetch resolved VAST XML for a waterfall source. | | 4 | POST | `/v1/partner/device/{deviceId}/programmatic-event` | Report ad_started / ad_ended / no_fill / error. | | 5 | (automatic) | Tracking pixels embedded in the VAST | IMA SDK fires these when the ad plays. | --- ## 3. The heartbeat — player identity **Endpoint:** `POST /v1/partner/device/{deviceId}/heartbeat` (every 60 seconds) For a user-agent update, the supported body is `{"device":{"ua":""}}`. The empty body remains a liveness heartbeat but provides no player UA. The following example includes optional hardware facts: ```json { "device": { "make": "Rockchip", "model": "rk3568_r", "os": "Android", "osv": "11", "android_api_level": 30, "ua": "Mozilla/5.0 (Linux; Android 11; rk3568_r Build/RD2A.211001.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/105.0.5195.136 Safari/537.36" }, "application": { "agentVersion": "2.0.18" } } ``` ### Field-by-field rules **`device.make`** — The actual manufacturer reported by the device; use a known hardware value, not a guessed vendor. **`device.model`** — The actual hardware model. Keep internal serial numbers and asset IDs in their identifier fields. **`device.os`** — `Android`; report the release version separately in `device.osv`. **`device.osv`** — The Android release version, for example `"11"` or `"13"`, from [`Build.VERSION.RELEASE`](https://developer.android.com/reference/android/os/Build.VERSION#RELEASE). Send `Build.VERSION.SDK_INT` separately as the integer `device.android_api_level`, for example `30` or `33`. This matches [OpenRTB's OS-version field](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3218---object-device). **`device.ua`** — **The single most important field.** Read it directly from the device at app startup: ```kotlin val webView = WebView(context) val realUA = webView.settings.userAgentString webView.destroy() ``` Or if WebView can't be instantiated (non-certified devices may restrict it): ```kotlin val realUA = WebSettings.getDefaultUserAgent(context) ``` Send the exact UA returned by the installed WebView. Do not append serial numbers or manufacture unique strings, Build fingerprints, or `wv` tokens. Devices with the same software and hardware can legitimately share a UA. [`WebSettings.getDefaultUserAgent`](https://developer.android.com/reference/android/webkit/WebSettings#getDefaultUserAgent(android.content.Context)) returns the platform default. **`application.agentVersion`** — Your SDK/app version. Helps us correlate issues to specific rollouts. ### Hardware model and asset identifiers Keep serial numbers and asset-tracking IDs in the partner device identifier. If a device's model property has been repurposed as a serial number, use a verified hardware model or omit the optional model field. Preserve the UA returned by WebView. --- ## 4. The ad request — GET /v1/partner/device/{deviceId}/ads **Endpoint:** `GET /v1/partner/device/{deviceId}/ads` **Optional query params** (player truth — send whatever you know): - `slot_w`, `slot_h` — Actual video container dimensions in pixels - `orientation` — `portrait` or `landscape` - `muted` — `1` or `0` - `autoplay` — `1` or `0` - `ua` — The real WebView UA (same as heartbeat), URL-encoded once by your URL builder - `lang` — `en-US` etc. - `screen_w`, `screen_h` — Physical screen dimensions in pixels - `sdk_type` — `google-ima` - `sdk_version` — IMA SDK version you're linking against - Hardware and dimension fields are optional. Send actual pixel dimensions; omit unknown values. Start the UA update on a few identified devices and verify their outgoing requests before a fleet rollout. - `ipd` — Inventory Partner Domain root domain, for example `trillboards.com`. Only send this when Trillboards tells you to; it must match an `inventorypartnerdomain=` declaration in the relevant ads.txt/app-ads.txt inventory-sharing setup, and it must not include a scheme, path, query, or port. **Response shape:** ```json { "success": true, "data": { "header_bidding_settings": { "enabled": true, "vast_waterfall": { "enabled": true, "total_timeout_ms": 15000, "sources": [ { "name": "adipolo", "vast_url": "https://api.trillboards.com/openrtb/v1/vast-wrap/adipolo/{screenId}?url=...&req=req_...&var=adipolo&pt=partner_api", "timeout_ms": 10000, "priority": 1, "enabled": true, "cpm": 5.0, "degraded": false, "request_id": "req_1775716769503_eb810d042466" }, { "name": "vidverto", "vast_url": "https://api.trillboards.com/openrtb/v1/vast-wrap/vidverto/{screenId}?url=...&req=req_...&var=vidverto&pt=partner_api", "timeout_ms": 10000, "priority": 2, "enabled": true, "cpm": 0.8, "degraded": false, "request_id": "req_1775716769503_8a85f754fd8a" }, { "name": "trillboards_direct", "vast_url": "https://api.trillboards.com/openrtb/v1/vast?screenId=...&adId=...", "timeout_ms": 8000, "priority": 5, "enabled": true, "duration_seconds": 15, "request_id": "req_1775716769503_c31f0a9be7d2" } ] } }, "screen_id": "69cce...", "dooh_signals": { ... } } } ``` The `vast_url` values already point to our vast-wrap endpoint with `pt=partner_api`. **Do not rewrite them.** Use them exactly as given. Each source carries its own `request_id` and `name` — save these. You'll need them for the `programmatic-event` report later (`variant_name` on the event is the source's `name`). #### `duration_seconds` — for continuous loop playback The first-party `trillboards_direct` source carries **`duration_seconds`**: the whole-second length of the creative that source will serve. It is there so you can schedule a continuous loop **without** fetching the VAST and probing the MP4 first. - It is the **same number** as the `` in the VAST that `vast_url` returns — the two are computed by one function server-side and cannot disagree. Use whichever is convenient. - It is **scheduling metadata, not a playback control.** IMA takes its real timing from the media itself, so keep honouring the actual quartile and `complete` events rather than assuming the ad ended after `duration_seconds` elapsed. If the two ever disagree on your device, the *events* are right and that is a bug worth telling us about. - Programmatic sources do **not** carry it — a DSP's creative length is unknown until its own VAST is fetched. Read it only off `trillboards_direct`, and treat it as absent everywhere else. - A creative longer than your ad slot will still be cut off by the next `/ads` poll. We warn the advertiser at upload time when their creative exceeds the slot, so this should be rare — but do not assume `duration_seconds` fits your slot without checking. Programmatic `/ads` responses are intentionally not HTTP-cacheable. Treat each call as a fresh ad opportunity because the VAST URLs include per-request IDs, correlators, and yield-routing metadata. Static direct-ad responses may still use short private ETag caching. ### 4.1 The waterfall loop contract **`sources` is an ordered array and you must walk all of it.** This is not optional and it is not an optimization — it is how a Trillboards ad request is defined. We return the array already in the order we want it tried, and `priority` ascends with array position. Sort by `priority` ascending anyway: it costs you three lines and it makes your player correct if the transport, a cache, or a JSON library ever reorders the array. **Treat `priority` as an opaque ascending sort key — not an index.** Do not assume it starts at 1, and do not assume the values are contiguous: - **`priority: 0` is real and valid.** A source we want to win outright is stamped `priority: 0` — that includes the `?test=1` source, an injected first-party bid, and an auction winner. A player that treats `0` as "unset" and skips it, or that starts its loop at 1, will drop exactly the source we most wanted served. - **Gaps are normal.** Some paths renumber the surviving sources `1..N`; others leave the original catalog values, so `11` and `13` with nothing in between is a perfectly ordinary response. Only the relative order carries meaning. `sortBy(priority)` handles all of this; arithmetic on the values does not. ``` sources ← response.data.header_bidding_settings.vast_waterfall.sources sources ← sources.filter(s -> s.enabled != false).sortBy(s -> s.priority) // ascending deadline ← now() + vast_waterfall.total_timeout_ms for (source in sources): if now() >= deadline: break // R3 — whole-loop budget spent vast ← GET source.vast_url with timeout = source.timeout_ms if (transport failed) or (timed out) or (vast is empty) or (vast has zero ): lastTried ← source; continue // R2 — advance outcome ← handToIma(vast) if outcome is AD_LOAD_ERROR or AD_PLAY_ERROR: fire beacon with [ERRORCODE] // R5 — always lastTried ← source; continue // R2 — advance report ad_started / ad_ended for this source // §7 return PLAYED // stop at the FIRST source that plays // every source exhausted, or budget spent report no_fill for lastTried // §7 resumeOwnContent() // R4 — never leave the surface black ``` **Rules the pseudocode encodes:** - **Iterate all sources by `priority` ascending.** Stop only on the first source that *actually plays*. - **Skip `enabled: false`.** A source can be present-but-disabled in the array; treat it as if it weren't there. - **Advance on every failure class**, not just "no ad": no-fill, empty VAST, zero-`` VAST, HTTP/transport error, per-source timeout, IMA **load** error, and IMA **playback** error. A creative that loads and then fails mid-roll still means "this source did not deliver" — go to the next one. - **VAST error codes that mean "advance", never "stop":** | Code | Meaning | What you do | |---|---|---| | **303** | No ads VAST response after one or more wrappers | Next source | | **300** | Wrapper URI unparseable, unsupported, or wouldn't load | Next source | | **301** | Timeout / unresolvable URI in the wrapper chain | Next source | | **1009** | Empty VAST response | Next source | - **Two clocks.** `source.timeout_ms` bounds one source's fetch+load. `vast_waterfall.total_timeout_ms` bounds the whole loop. Honour both; when the total budget is gone, stop and return to content. - **`degraded: true`** means we've measured a high recent error rate for that source. We already push degraded sources to the tail of the array for you — you don't need to act on the flag, and you must **not** skip a source just because it's degraded. - **Report against the source you actually used.** `request_id` and `variant_name` come from *that* source's entry, not from `sources[0]`. The `` beacon (R5) fires per failed source, always. The `programmatic-event` minimum is unchanged — the source that played, plus one `no_fill` for the last source tried if none did ([§7](#7-reporting-events-back--post-v1partnerdevicedeviceidprogrammatic-event)) — but a per-source `error` report is accepted and makes your waterfall legible to us end to end. > **This is the exact bug that cost a partner a full production forensics session.** Their player read `sources[0].vast_url` only. Indexes 0–3 were programmatic DSPs that returned no-fill for their geo; the `trillboards_direct` house creative sat at index 4. Their player got VAST **303** on source 0 and stopped — one index before the ad it was looking for. Every request looked like "Trillboards has no demand". The demand was there the whole time, one loop iteration away. --- ## 5. Fetching VAST — the critical part For **each** source in the waterfall — all of them, in `priority` ascending order, per the loop contract in [§4.1](#41-the-waterfall-loop-contract): ``` GET {source.vast_url} # with a per-request timeout of source.timeout_ms ``` **Response:** Full VAST XML (Content-Type: application/xml), 15-25 KB, containing wrapper chains resolved server-side. Our server: 1. Fetches the upstream partner VAST (Adipolo, VidVerto, etc.) using your device's IP via `X-Forwarded-For` for geo-targeting 2. Follows `` wrapper chains up to 5 hops to resolve to inline creative 3. Injects Trillboards tracking pixels at the wrapper/inline level 4. Returns the final VAST XML ready for IMA SDK to play **Do NOT:** - Parse the XML and extract only `` - Strip `` elements - Check for VPAID and skip (let IMA SDK handle it) - Modify the XML in any way before passing to IMA **Why:** Our tracking pixels (`` and ``) are embedded at the wrapper level. If you strip them, IMA SDK never fires them, and we have no record of the impression → no revenue attribution → no earnings. --- ## 5b. If you're NOT using Google IMA SDK (raw VAST player) IMA SDK automatically fires every embedded `` and `` URL as the ad plays. Custom VAST players do **not**. If you are rolling your own — raw HTML5 `