BRNDTS Partner Docs

Everything you need to integrate BRNDTS and start monetising your video inventory.

BRNDTS turns video moments into ad inventory - without touching your video stream.

An AI engine analyses your videos to find the right moments and on-screen positions for ads. A lightweight JavaScript SDK runs alongside your existing player and renders ads as HTML overlays at those moments. Optional realistic ads composite directly into the scene (e.g. a billboard on a football pitch) for content types that support scene calibration.

BRNDTS handles the demand stack - Prebid, Google Ad Manager, SSP integrations, identity partners - so you don't need to.

Ad formats & UX

BRNDTS supports multiple in-video ad formats, configured per publisher during onboarding. All formats are rendered as HTML elements positioned within or around the video scene - the video stream is never modified.

Banner overlay

A banner ad appears directly within the video frame at a contextually appropriate position identified by the AI placement engine (e.g. a clear area of pitch, a low-motion background region). The video keeps playing normally underneath.

Visible for the configured duration (typically 5–15 seconds)
A cooldown period follows before the next opportunity is evaluated
The video is never paused, interrupted, or re-encoded

Squeeze back

The video is temporarily scaled down within the player to make room for an ad panel alongside or below it. The video continues playing at reduced size for the ad duration, then returns to full size. This format delivers higher visibility than an overlay without interrupting playback.

Realistic ads

Ads are composited directly into the video scene to appear as natural elements of the environment - for example, a branded panel rendered on a football pitch touchline billboard, geometrically aligned to the ground plane and correctly occluded by players. Unlike overlays, realistic ads are indistinguishable from physical advertising in the venue.

How it differs from overlay/squeeze-back: overlay and squeeze-back are HTML elements layered on top of the video; realistic ads are AI-generated pixels rendered into the video frame itself.

Eligibility: requires AI-based scene geometry calibration. Available for supported content types - currently optimised for football, with more sports and content categories in active rollout. Contact BRNDTS to assess eligibility for your inventory.

Setup: no SDK changes required. Calibration is performed offline by BRNDTS using the same video source you provide for placement analysis (see Video source access).

Ad sizing

Each placement is filled automatically at the best-fitting IAB size for the detected region and the viewer's viewport - neither publishers nor demand partners specify a size per slot. Programmatic demand competes across the full set of supported sizes.

Supported standard IAB display sizes:

Size	Name
Rectangles & squares
300×250	Medium Rectangle
250×250	Square
200×200	Small Square
180×150	Small Rectangle
150×150	Small Square
Leaderboards & horizontal banners
970×250	Billboard
970×90	Large Leaderboard
728×90	Leaderboard
468×60	Full Banner
234×60	Half Banner
Mobile banners
320×100	Large Mobile Banner
320×50	Mobile Banner
300×50	Mobile Banner
Skyscrapers
300×600	Half Page / Large Skyscraper
160×600	Wide Skyscraper
120×600	Skyscraper

Static regions

In addition to in-video placements, you can define fixed banner slots on the page (right rail, above/below player). These are configured via the staticRegionsSelector SDK option - see Step 4.

Demand

BRNDTS comes with a fully managed programmatic demand stack built on Prebid.js and Google Ad Manager (GAM). Every ad placement triggers a client-side header bidding auction where multiple SSPs compete simultaneously. The highest-value ad wins and is rendered in the video scene.

BRNDTS-managed demand

Out of the box, BRNDTS provides:

Pre-configured SSP connections and yield optimisation
Google Ad Manager setup, ad units, and line items
Prebid.js bundled inside the SDK - nothing to install or maintain

Bring your own demand

If you have existing SSP relationships or direct sponsor campaigns, these can be added to the BRNDTS header-bidding auction alongside BRNDTS-managed demand. Every source competes in the same auction - the highest-value ad always wins. Raise this during onboarding and BRNDTS will work with your team on the setup.

Bring your own GAM network

If you run your own Google Ad Manager network, BRNDTS can serve your demand on your placements by calling your network directly on a dedicated ad unit. Two GAM networks cannot share a single auction, so this is a direct call into your network rather than header-bidding competition. See Bring Your Demand for how it works and what BRNDTS needs from you.

How it works

Every ad placement goes through the same six-step flow, from video playback to ad render:

🎬

Video plays

Your player, unchanged - BRNDTS does not modify the video stream.

⚡

SDK initialises

Validates the API key and fetches AI-computed placement data and publisher config from the BRNDTS backend.

🎯

Placement opportunity detected

As the video plays, the SDK tracks position against the placement metadata. When an AI-identified moment is reached, an auction is triggered.

🏷️

Prebid auction runs

Multiple SSPs receive simultaneous bid requests client-side.

📋

GAM decides

Google Ad Manager compares the winning programmatic bid against any active direct sponsor campaigns. The highest-value ad wins.

🖼️

Ad appears

The winning creative is rendered as an HTML element positioned within the video scene - supports overlay, squeeze-back, and realistic ad formats.

Key clarification

Ads are rendered client-side as HTML elements positioned within the video scene at AI-detected locations. The video stream is never intercepted, re-encoded, or modified. Your player keeps playing normally.

The AI placement step

BRNDTS uses computer vision to analyse your video content and identify the best moments and positions for ad placement - regions where an ad can appear without obscuring important visual elements, such as a clear section of pitch, a static background area, or a moment of low motion. This analysis produces placement metadata that the SDK uses at runtime to know exactly when and where to trigger an auction.

This is why BRNDTS needs access to your video source during onboarding - see Video source access.

What to send BRNDTS

Share these with your BRNDTS contact during onboarding. You can send everything in a single message.

Domains

Pages to monetise

For allowlisting your origins in our services

Player(s)

Which player you use

e.g. Video.js, JW Player, Brightcove, in-house

CMP

IAB TCF 2.3 and/or GPP

Must already be on your site. See CMP & consent

Ad timing

Show + cooldown duration

How long each ad is shown, and the minimum gap before the next one. BRNDTS will suggest defaults based on your content type.

Logo assets

SVG or transparent PNG

Used to brand sponsor ad placements on your inventory. See Your brand assets → Logo

Legal pages

Terms & Conditions + Privacy Policy

Publicly accessible, linked in site footer. See Legal pages

Dev / staging access Optional

URL + credentials

Basic auth, VPN, or allowlisted IP so BRNDTS can validate end-to-end before go-live

Blocked categories Optional

IAB category exclusions + blocked domains

Competitors, sensitive topics, or any categories you don't want to appear on your content

What BRNDTS handles

Once onboarded, BRNDTS manages the full ad infrastructure. You do not need accounts or configuration for any of the following:

Prebid.js configuration and updates
Google Ad Manager setup and line items
SSP connections and yield optimisation
Ad creative rendering and sizing
Placement metadata and AI analysis
Consent signal reading and compliance
API key and auth host provisioning

SDK setup

The BRNDTS SDK connects your player(s) to our placement engine - it reads consent signals, evaluates live playback context, triggers ad requests, and renders creatives as overlays.

1

Include the SDK

Import the BRNDTS module in your <body> (or your app's entry point):

// selector = CSS selector targeting your video element(s)
// Replace "#my-player" with your actual selector  -  see Step 2
<script type="module">
  import BrndtsAds from "https://solutions.brndts.com/stable/index.mjs";

  const ads = new BrndtsAds("#my-player", {
    key:  "your-api-key",           // provided by BRNDTS
    auth: { host: "your-auth-host" }, // provided by BRNDTS
  });
</script>

ℹ CDN only

The SDK is currently distributed via CDN only. Use the URL above directly - no npm package is available at this time. Contact BRNDTS if you need bundler integration.

2

Choose your selector

selector is a CSS selector targeting the video elements (or the closest containing element) where ads will be evaluated and rendered.

Prefer unique IDs for a single video: #my-player
Use classes for multiple videos: .video-player
Avoid overly broad selectors like video if you have many videos on the page
Target as close to the <video> / <iframe> element as possible to prevent accidental bindings

3

First-party data Optional

You can provide an optional userInfoProvider() function in the SDK config. BRNDTS calls it to read user signals for identity matching and yield improvement.

Consent gating: BRNDTS only invokes userInfoProvider() when consent allows identity/personalised advertising. If consent is not granted, the function is never called and BRNDTS proceeds without first-party signals.

When it runs: BRNDTS invokes userInfoProvider() lazily, each time an ad is requested - not at new BrndtsAds(...) construction time. You can wire the callback on the very first SDK init even if no user is logged in yet - return null in that case. As soon as the user authenticates, the next ad call picks up the fresh data automatically. There is no need to re-initialise the SDK on login or logout.

const ads = new BrndtsAds("#my-player", {
  key:  "your-api-key",
  auth: { host: "your-auth-host" },

  // Called at each ad request, only when consent allows  -  must return synchronously
  userInfoProvider: () => {
    if (!user) return null; // return null when logged out
    return {
      userId: user.id,    // sent as-is (opaque identifier)
      email:  user.email, // raw, or SHA-256 hex of the ID5-normalised value
      phone:  user.phone, // raw, or SHA-256 hex of the ID5-normalised value
    };
  },
});

Requirements

The callback must return synchronously - do not return a Promise. BRNDTS wraps the invocation in an async budget of 500ms; if it doesn't return within that window, BRNDTS proceeds without signals.
Return null if no user data is available (e.g. logged out)
email and phone are normalised and SHA-256 hashed in-memory by BRNDTS before transmission - never sent in plain text. userId is forwarded as-is (opaque identifier, no hashing).
If you would rather not expose the raw value to the browser, pass the SHA-256 hex digest (64 hex characters) instead. BRNDTS detects it and forwards it as-is, so normalise the value yourself before hashing, following the ID5 partner data requirements for email and phone.
Normalisation and hashing follow the ID5 partner data specification.

Supported fields

All three fields independently contribute to match rate. Pass every value you have available - there is no "primary" field, and partial objects are accepted (missing fields are simply skipped).

userId (string) - your stable internal user identifier; sent as-is
email (string) - user email, or its SHA-256 hex digest; raw values are normalised and hashed in-memory
phone (string) - user phone number, or its SHA-256 hex digest; raw values are normalised and hashed in-memory

4

Static regions Optional

Static regions are fixed ad containers you define in your layout (e.g. right-rail rectangle, top leaderboard). You own the HTML and CSS; BRNDTS routes demand to each region and serves an allowed size based on viewport, availability, and policies.

Enable static regions by passing staticRegionsSelector:

const ads = new BrndtsAds("#my-player", {
  key:                   "your-api-key",
  auth:                  { host: "your-auth-host" },
  staticRegionsSelector: ".brndts-static",
});

Add containers to your markup:

<div
  class="brndts-static"
  data-b-t="medium-rectangle"
  data-b-n="right_rail_rectangle_1"
  style="position: relative; width: 300px; height: 250px;"
></div>

data-b-t - region type (controls allowed sizes)
data-b-n - stable, unique region identifier used in reporting

Supported region types

data-b-t value	Allowed sizes
`medium-rectangle`	300×250, 250×250, 200×200, 180×150, 150×150
`large-rectangle`	300×600, 160×600, 120×600
`billboard`	970×250, 970×90, 728×90, 468×60
`leaderboard`	728×90, 468×60, 320×50, 300×50, 234×60
`smartphone-banner`	320×50, 300×50, 320×100

SPA note

BRNDTS detects added/removed containers via MutationObserver. You typically don't need to re-initialise. Ensure newly inserted nodes have the correct data-b-t and a unique, stable data-b-n.

5

Verify the integration

Open DevTools → Network and reload the page. Look for a request to:

https://<auth-host>/authority/tenant/setting

The request sends your API key and origin as headers (x-api-key, x-tenant) rather than in the path.

A 200 OK means config loaded and the integration is wired up. Open the Console tab; a successful start shows:

// DevTools Console (info-level messages)
[BRNDTS][INFO] BRNDTS Ads Presenter started
[BRNDTS][INFO] connecting...
[BRNDTS][INFO] connected to service

If the request fails, or you see warnings instead of the messages above, see Troubleshooting.

Video source access

BRNDTS needs access to the video source to run offline AI analysis and generate ad placement metadata. The right approach depends on how your video is served.

Option A - Public CDN

If your video manifests (HLS .m3u8 or DASH .mpd) are publicly accessible, share the URL pattern with BRNDTS during onboarding. No further setup required.

Option B - DRM-protected content

If your video is DRM-protected (Widevine, PlayReady, FairPlay), BRNDTS cannot fetch the stream directly. The right workaround depends on your stack:

Pre-packaged source files (preferred) - provide BRNDTS with access to the unencrypted origin asset (MP4/MXF) before it goes through your DRM packager. DRM applies to end-user delivery; BRNDTS only needs the source for offline analysis.
Server-side license token - most DRM licenses explicitly permit server-side processing. BRNDTS can be provisioned as a licensed processing endpoint; the content owner issues a token for BRNDTS's backend. Contact BRNDTS to set this up.
Unprotected preview stream - if your platform exposes a low-res or watermarked preview variant without DRM, share that URL with BRNDTS during onboarding.

Mapping video elements to source URLs

Regardless of which option applies, BRNDTS needs to associate each video element on the page with its source URL so the correct pre-analysed placement data is loaded at runtime. In many cases this can be resolved automatically - the SDK can read the resolved source from the player element or its API. Where that isn't possible (for example, when the source URL is constructed dynamically or differs from what the player exposes), an alignment will be needed to agree on how the mapping is provided.

The exact logic depends on the video player in use and the specific way it is set up on the publisher's pages - see Supported players for the list of player integrations the SDK recognizes automatically. BRNDTS will validate the approach with each publisher's team.

During onboarding

Contact BRNDTS to agree on the right approach for your setup. Every publisher stack is different and we'll work with your team on a secure, production-friendly solution.

ads.txt

Publishers must expose an ads.txt file at the root of their domain: https://<your-domain>/ads.txt

Your BRNDTS lines live in a single BRNDTS-hosted file. Every option below uses it as the source - fetch it and implement however you like:

https://s3.eu-west-2.amazonaws.com/brndts-ads.txt/your-slug.txt

Option 1 - 301 redirect delegation Recommended

Permanent redirect from your /ads.txt to a BRNDTS-hosted file. Keep it to one external redirect hop - crawlers do not follow more than one cross-domain redirect.

# nginx
location = /ads.txt {
    return 301 https://s3.eu-west-2.amazonaws.com/brndts-ads.txt/your-slug.txt;
}

# Apache
RedirectPermanent /ads.txt https://s3.eu-west-2.amazonaws.com/brndts-ads.txt/your-slug.txt

Option 2 - CDN rewrite / proxy

Configure a CDN rule so requests to /ads.txt are served from the BRNDTS-hosted origin. This keeps the canonical URL stable and allows BRNDTS to update entries without you redeploying.

# CloudFront  -  create a behaviour for path /ads.txt
Origin domain: s3.eu-west-2.amazonaws.com
Origin path:   /brndts-ads.txt/your-slug.txt
Viewer path:   /ads.txt

Option 3 - Manage your own file

If you already manage your own ads.txt, merge the BRNDTS lines into it. Either fetch the hosted file on a schedule to keep them in sync automatically, or append them by hand - in which case you are responsible for updating the file when demand partners change.

Verify

curl -sSIL https://<your-domain>/ads.txt

Expected: final 200, Content-Type: text/plain, and at most one cross-domain redirect (the 301 delegation in Option 1; none for Options 2 and 3).

CMP & consent

A Consent Management Platform (CMP) is required for privacy compliance and to ensure BRNDTS can read consent signals correctly.

Requirements

Your CMP must support (depending on the regions you operate in):

IAB TCF 2.3 - for GDPR (EU/EEA)
GPP - for US state laws and other regional frameworks

No CMP yet?

If you don't have a CMP in place, BRNDTS can integrate Google's Privacy & messaging solution (accessed through Google Ad Manager) on your behalf. This is the simplest path to compliance if you're starting from scratch. Raise this during onboarding and BRNDTS will handle the setup.

Vendor configuration

All relevant ad providers and partners must be listed as CMP vendors. Two options:

Grant BRNDTS access to manage vendor configuration directly - share access to tech@brndts.com in your CMP
Manage vendors yourself using the BRNDTS vendor list, updating it as partners change

Identity Solutions

BRNDTS integrates with identity providers to improve addressability and monetisation in cookieless environments. Identity solutions are always subject to your consent configurations and are enabled per publisher during onboarding. ID5 is currently the only identity solution shipped with the BRNDTS SDK; additional providers may be added in future releases.

ID5

ID5 is an independent, neutral and privacy-compliant identity provider (GDPR, IAB vendor 131). It acts as a universal identifier shared between publishers and buyers: when a user visits the site, ID5 assigns them an encrypted ID that DSPs recognise and use to match against their audience segments. The practical outcome: more bids, higher CPMs and better fill rates.

ID5 is always subject to your consent configurations. If consent is not granted, ID5 is not called and no signals are sent.

What BRNDTS handles

The ID5 integration is built into the BRNDTS SDK. With no work on your side:

BRNDTS calls ID5 as partner 1907 on every page where the SDK runs
Consent gating, signature verification and transport-level concerns are managed by BRNDTS

What the publisher provides

ID5's match rate is driven by the user signals the publisher provides at call-time. Without those signals, ID5 only has context (URL, host, IP, user-agent) to work with, which limits identity resolution for logged-in audiences.

To enable identity-grade matching on authenticated sessions, wire the userInfoProvider callback in the SDK config. You pass userId as-is and email/phone either raw or already SHA-256 hashed (hex); raw values are normalised and hashed in-memory by BRNDTS before they leave the page, following the ID5 partner data specification.

Configuration details, code snippet and supported fields: SDK setup → First-party data.

ID5 TrueLink Optional

TrueLink is an optional ID5 enhancement that improves user recognition across a publisher's owned-and-operated domains, especially where third-party cookies are limited. It uses a redirect-based flow to establish a durable first-party signal.

How it works

The browser is redirected through an ID5-operated endpoint
The user is redirected back to your domain
A first-party identifier signal is established on your domain, improving cross-domain continuity for ID5 identifiers in programmatic bidding

Publisher requirement

TrueLink requires serving an ID5 "bootstrap" script from a first-party URL on your domain (e.g. https://<your-domain>/id5-bootstrap.js). Implementation options:

CDN rewrite/proxy (recommended) - requests to /id5-bootstrap.js are proxied to a BRNDTS/ID5-hosted origin
Direct hosting - publisher hosts the bootstrap file as a static asset

BRNDTS provides the bootstrap asset and the recommended path during onboarding.

Notes

TrueLink is not required for BRNDTS Ads to function - it is an optional performance enhancement
TrueLink only activates when consent allows identity/personalised advertising (per your consent configurations)

Legal pages

Publishers must have publicly accessible legal pages, typically linked in the site footer:

Terms & Conditions
Privacy Policy - must clearly describe data collection, usage, and sharing, and reference your consent mechanisms (CMP / IAB TCF compliance)

These pages are generally required for BRNDTS and demand partner eligibility.

Your brand assets

The publisher's brand identity used by BRNDTS to brand sponsor ad placements on your inventory (logo lockups, background panels). Provide once during onboarding.

Logo

Please send:

1 horizontal logo (preferred)
1 vertical or stacked logo (if available)

Accepted formats

Preferred: SVG
Alternative: PNG with transparent background, highest resolution available

Requirements

Transparent background
Clean, high-quality file with no blur, pixelation, or visible compression
No small taglines or fine details that become unreadable at reduced sizes

Avoid sending

Logos with solid, non-transparent backgrounds
Low-resolution files
Logos with promotional or extra marketing text

Background

Our preferred format is a gradient based on your brand's primary colours. This ensures a lighter, cleaner, and more consistent experience across devices.

To create it, we need:

Your brand's primary colours
Brand guidelines or visual identity manual (if available)

Alternative

If your brand uses an approved background style and a gradient is not suitable, we can work with a background artwork file:

High-resolution asset, minimum 1920×1080 px

Additional brand materials

If available, you may also share:

Brand guidelines or brand book
A link to your brand assets page
Approved references for logo or background usage

Assets will be reviewed and applied according to placement requirements.

Troubleshooting

Symptoms and likely causes for the most common SDK integration issues. If your case isn't here, contact your BRNDTS integration lead.

Config request returns 403

Symptom: The request to /authority/tenant/setting returns 403. Console shows:

[BRNDTS][WARN] BRNDTS config fetch failed; bailing out.

Cause: The origin you are calling from is not allowlisted.

Fix: Send the exact origin (scheme + host + port) you are testing from to your BRNDTS contact. Includes localhost ports and staging subdomains.

SDK loads but no ads appear

Symptom: Console shows [BRNDTS][INFO] BRNDTS Ads Presenter started and [BRNDTS][INFO] connected to service, but no ad ever renders during playback.

Possible causes:

CMP / consent not ready - the SDK waits up to 10 seconds for window.__tcfapi or window.__gpp. If neither is available in time, it falls back to default consent values and ads may not be requested. Confirm your CMP loads before the SDK initialises.
Disabled by config - if the console shows [BRNDTS][ERROR] Setup failed: disabled by config, ads are turned off server-side. Contact your BRNDTS integration lead.
Device excluded - if the console shows [BRNDTS][INFO] Device <brand> <model> is excluded from using BRNDTS Ads as per configuration, the device is blocklisted. Contact BRNDTS to review device exclusions.

CSP blocks the SDK

Symptom: Browser console reports a Content Security Policy violation.

Context: The SDK loads resources from multiple external domains at runtime (ad serving, header bidding, fonts, etc.). The exact list depends on which SSPs and partners are enabled for your inventory.

Fix: Contact your BRNDTS integration lead for the full CSP allowlist for your configuration. At a minimum, you will need to allow:

script-src: https://solutions.brndts.com, your BRNDTS auth host
connect-src: your BRNDTS auth host

BRNDTS will provide the complete list of domains for script-src, style-src, connect-src, frame-src, and img-src based on your ad partner setup.

Selector matches no elements

Symptom: Console shows:

[BRNDTS][WARN] No valid target elements found for BRNDTS Ads initialization.

Cause: SDK initialised before your video player mounted in the DOM (common in SPAs and frameworks that hydrate after first paint).

Fix: Initialise BRNDTS only after the player element exists. For React, do it in useEffect after the player ref is set. For Vue, in mounted(). For vanilla SPAs, after your router commits the route.

Unsupported browser environment

Symptom: Console shows:

[BRNDTS][WARN] brndts-ads: unsupported environment - missing: <list>

Cause: The browser is missing required APIs (WebSocket, ResizeObserver, etc.). See Browser & Device Support for the full requirements list.

Fix: This is expected on older browsers. The SDK will not initialise and will not affect page performance.

ads.txt returns 404 or wrong content type

Symptom: Demand partner reports your /ads.txt is not reachable or has the wrong content type.

Fix: Run curl -sSIL https://<your-domain>/ads.txt - confirm a single 200 response with Content-Type: text/plain. If you delegate via 301, ensure only one cross-domain hop. See ads.txt setup.

Still stuck?

Capture: a HAR file of the failing page load, the BRNDTS console output (enable DevTools verbose logging), your CMP framework + version, and your browser + version. Send to your BRNDTS integration lead.