Skip to main content

Ads

Add your ad tags to a project, then pick one for a video or live stream, and its player plays your ads wherever you embed it on your site. An ad tag is a VAST or VMAP URL from your ad server (Google Ad Manager, SpringServe, FreeWheel, or any other that serves VAST), with a name. Crumbcast plays what it returns with Google's IMA SDK; which ads play, their tracking and what they earn stay with your ad server.

TagPlays
VASTOne ad (or a pod) before the video
VMAPThe breaks it schedules: before, during, and after the video
Either, on a live streamIts pre-roll, before the viewer joins the broadcast

Adding ad tags​

A project admin adds them in the project's Settings → Ad tags, or from code with Create Ad Tag:

curl -X POST https://crumbcast.example/api/v1/projects/$PROJECT_ID/ad-tags/ \
-H "Authorization: Bearer $CC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Pre-roll", "url": "https://ads.example.com/vast?sz=640x480&cb=[CACHEBUSTING]&url=[PAGEURL]"}'

The URL must be http or https, up to 4096 characters. Changing a tag's URL changes the ads of every video that picked it; deleting it leaves them without ads.

Picking one​

In the dashboard: a video's Settings tab, under Ads, or a live stream's Playback → Ads.

From your code, ad_tag_id on Update Video or Update Live Stream, one of the project's (List Ad Tags); null for no ads:

curl -X PATCH https://crumbcast.example/api/v1/videos/$VIDEO_ID/ \
-H "Authorization: Bearer $CC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ad_tag_id": "'$AD_TAG_ID'"}'

A clip cut from a video keeps its ad tag. Players get the picked tag's URL as the playback's vast_tag_url.

Macros​

The player fills in these IAB macros before it asks your ad server, URL-encoded:

MacroBecomes
[CACHEBUSTING]A random 8-digit number, new for each viewing
[TIMESTAMP]The time of the request, e.g. 2026-10-28T09:30:15.250+00:00
[PAGEURL]The page the video is on: for an embed, the page that embeds it
[DOMAIN]That page's host name
[PLAYERSIZE]The player's width and height in pixels, e.g. 640,360
[GDPRCONSENT]The viewer's IAB TCF consent string, from the page's consent platform; empty without one (see Privacy and consent)

Anything else in the tag (your ad server's own macros, such as %%SITE%%) is sent as it is.

What viewers see​

  • The ad plays when the viewer first presses play, or when the video autoplays (muted autoplay plays the ad muted). The video waits, paused, and starts once the ad is over or skipped; a live stream starts at its live edge.
  • The ad's own controls (countdown, skip, "Learn more") are drawn by IMA.
  • Only linear (video) ads play. Non-linear overlays and companion banners don't.
  • If no ad comes back, the tag is broken, an ad blocker stops it, or the ads take more than a few seconds after the viewer pressed play, the video plays without them.
  • Ads play only in the player embedded on your site. They never play on Crumbcast's own pages: the watch page, the live watch page, an embed URL opened on its own, or the dashboard. Those pages set no advertising cookies, so viewers there never see a consent banner.

IMA is Google's, and it uses Google's cookies; your ad server may track viewers too. If your viewers are in the EU, you need their consent for that.

Put an IAB TCF v2 consent platform (CMP) on the page that embeds the player, as you would for any ads on it. The embedded player finds it through the CMP's standard __tcfapiLocator frame, so the viewer's choice reaches the ads:

  • IMA reads it, and sends it with Google Ad Manager tags on its own.
  • [GDPRCONSENT] in your tag is filled with the viewer's consent string, for other ad servers: …&gdpr=1&gdpr_consent=[GDPRCONSENT], as your ad server names them.
  • The ads wait up to 2 seconds for the viewer to choose in your consent banner; after that they're asked for without consent.

Without a CMP on the page, ads are asked for without a consent signal. Ask your ad server how it treats those (Google Ad Manager, for one, can serve non-personalised ads). US state privacy signals (GPP) aren't passed into the embed.