ℹ️

All code in this page is pseudo-code, loosely based on the SmartLib Android SDK. Similar functionality is available for other versions of the SmartLib.

SmartLib setup

Initialization

For full details on how to configure SmartLib for your specific player, please use the SmartLib SDK documentation. The information below reflects a configuration that should provide a baseline that works in most DAI scenarios.

Session creation

// create a SmartLib session
session = SmartLib.getInstance().createStreamingSession();

// attach the player
session.attachPlayer(player)

// activate advertising to receive ad tracking information (required for ad-aware UI/UX features)
// activating this flag also automatically enables client-side ad tracking (CSAT)
session.activateAdvertising();

// listen to ad data from the start of the session; 
// required to ensure ad-aware UI/UX features are usable from the start of the session, in particular bookmarking features. This is critical for VOD
session.setAdDataListener( ... )

// listen to ad events for ad-aware UI/UX functionality, such as banner displays over ads
session.setAdEventsListener( ... )

Notice that the setAdDataListener() is crucial for VOD workflows. It can be used with Live streams as well without adverse effects, but is not necessary.

Thereafter, you can start playback, in the player-specific way described in the SmartLib documentation

Using Ad tracking

When advertising is activated in the SmartLib configuration (with activateAdvertising()), SmartLib will trigger events. These will be the main way of controlling ad-aware UI/UX logic in the application. By registering a listener with the session, the application can react in real-time to ad lifecycle events and adapt the UI accordingly.

These events expose all necessary information about the ad breaks and ads through its data objects, allowing for precise control over the user experience. 

Below is a table summarizing these events and their practical implications for UI/UX.

Reference: Ad options

Use case: Message overlay

The display of a banner during ad playback can therefore simply be implemented by listening to onAdBreakBegin() and onAdBreakEnd() and showing/hiding the appropriate UI component.

Use case: Ad counter overlay

To display an ad counter (instead or in addition to the previous overlay) can be done by using the event data on the ad break and ad start events

Use case: Skippable ads

If the ad server response indicates that an ad is skippable after a particular initial duration, SmartLib will expose this information to the application, through an onAdSkippable event.

To implement the ability of the user to skip this ad, the following workflow is recommended.

1. The application listens to the onAdSkippable event
2. At the start of a skippable ad, in addition to an onAdBegin, SmartLib fires an onAdSkippable event, which carries 3 key data fields:
   1. adSkippablePosition
   2. adEndPosition
   3. adBreakEndPosition
3. The application displays a "Skip Ad" button overlay in a disabled state. 
4. The application monitors the current playback position. When the player's position passes the adSkippablePosition, the skip button is enabled. 
5. If the user clicks the enabled button, the application must make a decision:
   1. to skip only the current ad, it should seek the player's position to adEndPosition
   2. to skip the entire remaining ad break, it should seek to the adBreakEndPosition

A possible enhancement can be to add a countdown timer in the overlay. The same data can be used together with player position monitoring to enable this use case.

Using Ad Data

SmartLib can also expose data about ad breaks and ads. With VOD, this enables a number of other UX/UI scenarios

❗️

These features will be mostly functional if the session.setAdDataListener() has been configured in the SmartLib session before the call to session.getURL()

Use case: Bookmarking (for VOD)

“Bookmarking” refers to functionality allowing the application to keep track of the play position a user has reached in a particular asset, so that if the user stops watching, she can resumes playback from the same point in the content.

A simple time-based bookmark does not work because the duration and position of ads is likely to change in each playback session, which would cause the time bookmark to point to an incorrect place in the content.

SmartLib provides a way to implement such a feature, through a conversion mechanism between the content timeline and an individual session’s stream timeline (after ads are inserted).

Reference: Ad options - bookmarks

Sample code: Ad bookmarks

Saving a Bookmark

When the user pauses the video or exits the application, the application must bot not save the current player position. Instead, it uses the SmartLib’s session.getPositionForBookmark() API. This method returns a time position that represents the user's location within the content timeline, removing the duration of all ads that have played before that point.

// on pause, stop, and/or regularly
const contentOnlyPosition = session.getPositionForBookmark(); 

// save bookmark to the CMS
cms.endpointToStoreUserBookmarkForContent(contentId, position);

Restoring a Bookmark

When the user returns to resume playback, the application should start a new SmartLib session as usual. Once the saved content bookmark is retrieved, the application must call the SmartLib’s session.getPositionForPlayback(savedBookmarkPosition). This method takes the “clean” content position and translates it into a valid time position within the session’s ad-stitched timeline, taking into account the duration and position of the new ads that have been inserted.

The returned value is the exact position to which the player should be instructed to seek. 

// recover stored position from CMS 
const savedBookmarkPosition = cms.endpointToRetrieveUserBookmarkForContent(contentId) 

// Create a new session and start it... 
const session = smartlib.createStreamingSession(); 
//... configure parameters, etc. as above 

// Ensure that the ad data is available before stream start
session.setAdDataListener({ 
    onAdData: (adList) => { 
        // Only attempt to restore once we have the ad list 
        if (savedBookmarkPosition &&!bookmarkRestored) { 
            const playbackPosition = session.getPositionForPlayback(savedBookmarkPosition); 
        } 
    } 
}); 

// Start the session 
session.getURL(contentUrl); 

// Seek to the correct position
player.seek(playbackPosition); 

Use case: Determining the content duration (for VOD)

To display accurate information in the user interface, such as the total duration of the content without ads, the application must be able to reconcile the content timeline with the timeline of a particular streaming session (with its inserted ads). 

The video player is will only report the total duration of the stream itself (which may contain ads).

Calculating the duration of the “pure” content (if it cannot be provided by the application) requires

1. subscribing to the onAdData event
2. on reception of the event, retrieving the list of ad breaks (session.getAdList())
3. iterating through the ad breaks in the list, and retrieving the duration for each (adBreakData.getDuration())
4. substracting the sum of all durations from the stream duration reported by the player