How to track program changes on a live stream?

Live streams often carry more than one piece of content. A 24/7 channel moves from one EPG program to the next, a linear feed switches from a show to the news, or your app switches channels inside the same manifest. In all of these cases the stream keeps running, but from an analytics point of view the content is no longer the same.

The programChange API lets you tell the Bitmovin Analytics collector about exactly that: the content changed logically, while the underlying stream and the player attachment stay untouched.

Calling it closes the current analytics session and starts a new one — with a new impression ID and the metadata of the new program — without interrupting playback.

Availability

What happens when you call programChange

When a session is already running (playback has started):

1. The current impression is closed. A final sample is sent with the metadata of the old program and the playback time accumulated so far. This sample carries the isProgramChange flag.
2. A new impression ID is generated and the sequence number is reset.
3. The new metadata is applied and a startup sample with the state programchange is sent for the new session. It reports a synthetic videoStartupTime of 1 ms, because no actual loading happened — the stream was already playing.
4. Playback continues uninterrupted, and every following sample belongs to the new impression.

When the call happens before or during startup (no session has been established yet):

• No sample is sent and no new impression is created. The metadata is simply applied, and the upcoming natural startup is tracked with the new values. This makes the call safe to use in racy situations such as a channel switch right after loading a source.

Metadata handling

The metadata you pass to programChange replaces the metadata of the currently active source. Fields you do not set are not carried over from the previous program, so always pass the complete set of source-level fields for the new program.

Metadata configured on a session-independent level (DefaultMetadata on Android/iOS, the analytics config on Web/Roku) keeps applying as usual, and customData set on the new program takes precedence over the default values.

SourceMetadata accepts the following fields:

Web

Bitmovin Player v8

With the Bitmovin Player Web SDK, the analytics API is available on the player instance:

const player = new bitmovin.player.Player(container, {
  key: '<YOUR PLAYER KEY>',
  analytics: {
    key: '<YOUR ANALYTICS KEY>',
    videoId: 'channel-1',
    title: 'Channel 1',
    isLive: true,
  },
});

// Later, when the next program starts on the same stream
player.analytics.programChange({
  title: 'Evening News',
  videoId: 'program-news-2100',
  cdnProvider: 'akamai',
  path: '/live/channel-1',
  isLive: true,
  customData: {
    customData1: 'news',
    experimentName: 'epg-tracking',
  },
});

Other players

For all other web players, call programChange on the analytics adapter instance you created for the player. The following example uses HLS.js — the same applies to ShakaAdapter, VideojsAdapter, HTMLVideoElementAdapter, THEOplayerAdapter and CAFv3Adapter:

const analyticsConfig = {
  key: '<YOUR ANALYTICS KEY>',
  videoId: 'channel-1',
  title: 'Channel 1',
  isLive: true,
};

const player = new Hls();
const analytics = new bitmovin.analytics.HlsAdapter(analyticsConfig, player);

// Later, when the next program starts on the same stream
analytics.programChange({
  title: 'Evening News',
  videoId: 'program-news-2100',
  isLive: true,
  customData: {
    customData1: 'news',
  },
});

Android

Standalone collector

val analyticsConfig = AnalyticsConfig(licenseKey = "<YOUR ANALYTICS KEY>")
val collector = IBitmovinPlayerCollector.create(context, analyticsConfig)

collector.setSourceMetadata(source, SourceMetadata(videoId = "channel-1", title = "Channel 1", isLive = true))
collector.attachPlayer(player)
player.load(source)

// Later, when the next program starts on the same stream
collector.programChange(
    SourceMetadata(
        title = "Evening News",
        videoId = "program-news-2100",
        cdnProvider = "akamai",
        isLive = true,
        customData = CustomData(customData1 = "news"),
    ),
)

Bundled Analytics in the Bitmovin Player

When you use the Analytics that ships with the Bitmovin Player for Android, the collector is available through the player:

player.analytics?.programChange(
    SourceMetadata(
        title = "Evening News",
        videoId = "program-news-2100",
        isLive = true,
        customData = CustomData(customData1 = "news"),
    ),
)

Java

SourceMetadata sourceMetadata = new SourceMetadata.Builder()
    .setTitle("Evening News")
    .setVideoId("program-news-2100")
    .setIsLive(true)
    .setCustomData(new CustomData.Builder().setCustomData1("news").build())
    .build();

collector.programChange(sourceMetadata);

iOS, tvOS and visionOS

Standalone collector

programChange(newSourceMetadata:) is part of the shared collector API, so it is available on every collector — BitmovinPlayerCollector, AVPlayerCollector and THEOplayerCollector. The following example uses AVPlayer:

let analyticsConfig = AnalyticsConfig(licenseKey: "<YOUR ANALYTICS KEY>")
let collector = AVPlayerCollectorFactory.create(config: analyticsConfig)

collector.sourceMetadata = SourceMetadata(videoId: "channel-1", title: "Channel 1", isLive: true)
collector.attach(to: player)

// Later, when the next program starts on the same stream
collector.programChange(
  newSourceMetadata: SourceMetadata(
    videoId: "program-news-2100",
    title: "Evening News",
    isLive: true,
    cdnProvider: "akamai",
    customData: CustomData(customData1: "news")
  )
)

Bundled Analytics in the Bitmovin Player

When you use the Analytics that ships with the Bitmovin Player for iOS, tvOS and visionOS, the analytics API is available on the player instance:

let player = PlayerFactory.createPlayer(
  playerConfig: playerConfig,
  analytics: .enabled(analyticsConfig: AnalyticsConfig(licenseKey: "<YOUR ANALYTICS KEY>"))
)

// Later, when the next program starts on the same stream
player.analytics?.programChange(
  newSourceMetadata: SourceMetadata(
    videoId: "program-news-2100",
    title: "Evening News",
    isLive: true,
    customData: CustomData(customData1: "news")
  )
)

Objective-C

BMASourceMetadata *sourceMetadata = [[[[BMASourceMetadataBuilder new]
    withVideoId:@"program-news-2100"]
    withTitle:@"Evening News"]
    build];

[collector programChangeWithNewSourceMetadata:sourceMetadata];

Roku

On Roku, programChange is available on the THEOplayer collector and is called through the collector node's function interface. In addition to the standard metadata fields it accepts the stream URL of the new program, which is used to report the stream format:

m.collector.callFunc("programChange", {
  title: "Evening News",
  videoId: "program-news-2100",
  isLive: true,
  customData1: "news",
  m3u8Url: "https://example.com/news.m3u8",
})

Verifying the result in the dashboard

After a program change you will see two separate sessions in the Analytics dashboard:

• the session of the previous program, ending at the moment of the call, and
• the session of the new program, starting with a programchange state instead of the usual startup state.

Both sessions have their own impression ID, so all metrics — playtime, rebuffering, quality changes, errors — are attributed to the program they happened in.

Choosing the right API

Use programChange when the content changes but the stream does not. If you load a new source into the player, use the regular source change flow instead. If you only want to correct or enrich the metadata of the current session, use the custom data APIs.