NextGen Live API: Server-Side Ad Insertion (SSAI) - Macro Variables

Introduction

Server-Side Ad Insertion (SSAI) in NextGen Live API allows you to dynamically insert ads into your live streams. Macro variables are placeholders that get replaced with actual values at runtime, enabling precise ad targeting and tracking.

Macro variables can be used in:

• Ad server URLs - for sending contextual information to your ad server
• Custom beacon URLs - for tracking ad playback and engagement

This guide covers all supported macro variables, how to use them, and provides complete working examples.

Overview

NextGen Live supports all macro variables from Live 1.0, plus additional tracking and SCTE-35 macros. The workflow remains the same:

1. Create an SSAI ad configuration with macro placeholders in the ad server URL
2. Create a live job with SSAI enabled
3. Insert cuepoints via the API or use SCTE-35 markers
4. Macros are automatically replaced with actual values when ads are requested

Macro Syntax

Macros use double curly brace syntax:

{{macro.name}}

Example in an ad server URL:

https://ads.example.com/ad?session={{session.session_id}}&ip={{client.ipaddress}}&dur={{live.adbreakdurationms}}

Supported Macro Variables

Session & Job Macros

These macros provide information about the current streaming session and job.

Random Value Macros

These macros generate random values, useful for cache-busting and unique identifiers. Random values are generated fresh for each ad request.

Server & Timestamp Macros

These macros provide timing information for the ad break and request.

Client Context Macros

These macros provide information about the viewer's context. All client context values are automatically URL-encoded.

Ad Break Duration Macros

These macros provide the duration of the ad break in various formats.

SCTE-35 Macros (RTP/SRT Inputs Only)

These macros are populated from SCTE-35 markers in the live stream. They are only available with RTP and SRT input protocols, not with RTMP.

Tracking Macros

These macros are useful for advanced tracking and analytics.

Custom URL Macros

NextGen Live SSAI supports custom ad targeting parameters via the {{url.*}} macro pattern. Any parameter passed by the client during session initialization is available as {{url.<key>}} in the ad tag URL.

How to Use

1. In your ad configuration, reference custom parameters using the {{url.*}} syntax:

{
  "ad_server": {
    "url": "https://ads.example.com/ad?csid={{url.csid}}&prof={{url.prof}}&cb={{random.uint32}}&session={{session.session_id}}"
  }
}

2. From the client, pass matching parameter values. There are two ways to do this:

Option A: Via the Brightcove Player or Native SDKs

The Brightcove Player and Native SDKs send custom parameters as adsParams in the session initialization POST request. For implementation details, see Ad Targeting with Custom Parameters.

Option B: Via query parameters on the playback URL

You can also pass custom parameters directly as query parameters on the playback URL, using the ads. prefix. For example, to pass csid and prof:

https://ssai.live.brightcove.com/.../playlist-hls.m3u8?ads.csid=mysite-section&ads.prof=123456

The corresponding {{url.csid}} and {{url.prof}} macros in the ad tag URL will be replaced with the values provided. This approach is useful for third-party players, FAST channel integrations, or any scenario where you don't control the player SDK initialization.

How to Use Macro Variables

Step 1: Create an Ad Configuration

Create an SSAI ad configuration with macro placeholders in the ad server URL.

Request

POST https://api.live.brightcove.com/v2/accounts/{account_id}/ssai/ad-configs

Request Body

{
  "description": "Sports Ad Configuration",
  "ad_server": {
    "url": "https://ads.example.com/ad?sid={{session.session_id}}&ip={{client.ipaddress}}&dur={{live.adbreakdurationms}}&category={{url.givn}}",
    "response_type": "VAST",
    "headers": {
      "X-Api-Key": "your-api-key"
    }
  },
  "custom_beacons": [
    {
      "event": "start",
      "url": "https://tracking.example.com?event=start&session={{session.session_id}}&ad={{tracking.ad_id}}"
    },
    {
      "event": "complete",
      "url": "https://tracking.example.com?event=complete&session={{session.session_id}}&ad={{tracking.ad_id}}"
    }
  ]
}

In this example:

• {{session.session_id}}, {{client.ipaddress}}, and {{live.adbreakdurationms}} are built-in macros that are automatically populated
• {{url.givn}} is a custom URL macro — the value is passed by the client during session initialization

Step 2: Create an SSAI-Enabled Job

Create a live job with SSAI enabled and select the ad configuration you created in Step 1. For more details, see the NextGen Live: Implementing Server-Side Ad Insertion document.

Step 3: Insert a Cuepoint

Insert a cuepoint to trigger an ad break in your live stream.

Request

POST https://api.live.brightcove.com/v2/accounts/{account_id}/jobs/{job_id}/cuepoint

Request Body

{
  "duration_in_seconds": 60
}

To pass custom targeting parameters, add them to the playback URL query string:

https://playback.live.brightcove.com/v1/accounts/{account_id}/jobs/{job_id}/playlist.m3u8?givn=sports

Custom Beacons

Custom beacons allow you to track ad playback events. In NextGen Live, you configure custom beacons within the ad configuration using the custom_beacons field.

Supported Beacon Event Types

Core Linear Video Events

• start - Ad started
• firstQuartile - 25% complete
• midpoint - 50% complete
• thirdQuartile - 75% complete
• complete - 100% complete

Additional Engagement Events

• mute, unmute
• pause, resume
• rewind, skip
• progress (with offset)

Non-linear & Companion Events

• creativeView
• closeLinear, close
• acceptInvitation, acceptInvitationLinear
• expand, collapse

Example with Custom Beacons

{
  "description": "Ad Config with Custom Beacons",
  "ad_server": {
    "url": "https://ads.example.com/ad",
    "response_type": "VAST"
  },
  "custom_beacons": [
    {
      "event": "start",
      "url": "https://tracking.example.com?event=start&session={{session.session_id}}&ad={{tracking.ad_id}}"
    },
    {
      "event": "firstQuartile",
      "url": "https://tracking.example.com?event=firstQuartile&session={{session.session_id}}&ad={{tracking.ad_id}}"
    },
    {
      "event": "midpoint",
      "url": "https://tracking.example.com?event=midpoint&session={{session.session_id}}&ad={{tracking.ad_id}}"
    },
    {
      "event": "thirdQuartile",
      "url": "https://tracking.example.com?event=thirdQuartile&session={{session.session_id}}&ad={{tracking.ad_id}}"
    },
    {
      "event": "complete",
      "url": "https://tracking.example.com?event=complete&session={{session.session_id}}&ad={{tracking.ad_id}}"
    }
  ]
}

SCTE-35 Support

The Society of Cable Telecommunications Engineers (SCTE) defines a standard for dynamic ad insertion for live streams. An SCTE-35 ad marker defines the timestamp and duration where an ad can be inserted into the stream.

SCTE-35 parameters are automatically extracted from the live stream when using RTP or SRT input protocols and SCTE-35 has been enabled for the job.

Using SCTE-35 Macros

When your encoder sends SCTE-35 markers in the stream, the following macros are automatically populated:

{
  "description": "Ad Config with SCTE-35 Macros",
  "ad_server": {
    "url": "https://ads.example.com/ad?event={{scte.event_id}}&avail={{scte.avail_num}}&archive={{scte.archive_allowed_flag}}",
    "response_type": "VAST"
  }
}

No additional API calls are needed - values are automatically extracted from the SCTE-35 binary data in the stream.

API Scope Requirements

To use the SSAI and cuepoint APIs, you need appropriate API credentials with the following scopes:

For information on creating API credentials, see Managing API Authentication Credentials.