Preplay

This article explains how to leverage the Verizon Media Preplay API through THEOplayer. This API allows developers to pre-integrate with Verizon's Preplay service.

Table of Contents

• SDKs
• Stream Configuration (without ads)
• Stream Configuration (with ads)
• Preplay Response
• Using Tokens

SDKs

Web SDK	Android SDK	iOS SDK	tvOS SDK	Android TV SDK	Chromecast SDK
Yes (2.63.0)	Yes (2.66.0)	Yes (2.65.0)	No	Yes (2.66.0)	No

Verizon Media users can use an API (i.e. Preplay) to generate a streaming playlist given 1 or more assets or advertisements. The back-end of Verizon Media stitches the content together and allows for server-side ad-insertion (SSAI) when applicable. This document describes how THEOplayer users should configure their source to leverage this Preplay service.

Assumptions:

• THEOplayer assumes the availability of the Preplay API and Verizon content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
• THEOplayer assumes that developers who are interested in this feature have a basic understanding of the Preplay API. Verizon Media documents this service at https://docs.vdms.com/video/Content/Develop/Preplayv2.htm
• THEOplayer assumes that developers provide correct asset identifiers, as well as the proper content protection level.

Stream Configuration (without ads)

The examples below demonstrate how to configure a stream through the Verizon Media pre-integration.

Web SDK

player.source = {
    sources: [{
        integration: 'verizon-media',
        id: 'verizon-media_content_id',
        preplayParameters: {}, // Optional, defaults to an empty object. These will be added as query parameters to the Preplay API call.
        assetType: 'asset', // Optional, defaults to 'asset'. Can also be 'channel' or 'event', following the Verizon Media semantics, where 'asset' is On-demand content.
        contentProtected: false // Optional, defaults to false.
    }]
}
    
// Source example for an external id (with optional properties omitted)
player.source = {
    sources: [{
        integration: 'verizon-media',
        id: {
            userId: 'verizon-media_user_id',
            externalId: 'verizon-media_external_content_id'
        },
    }]
}
    
// Source example for a regular asset id with e.g. 'delay' parameter and 'sig' token parameter.
player.source = {
    sources: [{
        integration: 'verizon-media',
        id: 'verizon-media_content_id',
        preplayParameters: {
            delay: '7200',
            rays: 'dcba',
            sig: '2ff94739b021912712adafeccd6fa291f11eef0648c3b18b30224b84e0590b4f'
        }, // Optional, defaults to an empty object. These will be added as query parameters to the Preplay API call.
        assetType: 'asset', // Optional, defaults to 'asset'. Can also be 'channel' or 'event', following the Verizon Media semantics, where 'asset' is On-demand content.
        contentProtected: false // Optional, defaults to false.
    }]
}

The snippet above gives a quick overview of the structure of a Verizon Media-specific source, also known as a VerizonMediaSource. More information on certain properties:

• id: The ID field identifies the asset. Instead of a single string, developres can also specify an array of asset IDs as strings, which will be stitched into a continuous stream. The same goes for the externalId property in case an external ID is used in the source.
• preplayParameters: The preplayParameters object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.
• contentProtected: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.
• A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source. This request must also include adigital signatureif the 'Require a token for playback'option is enabled in the back-end on the corresponding live channel. (See also : Basic Setup > Playback URL's > Signing a Playback URL Tutorial)
• Verizon Media specific documentation on the available playback URL query parameters can be found on the Verizon Media documentation site under Basic Setup > Playback URL's > Customizing Playback via Parameters
• Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

Android (TV) SDK

// Java examples

// Single asset
Map<String, String> preplayParameters = new HashMap<>(); 
VerizonMediaSource verizonMediaSource = new VerizonMediaSource.Builder("assetID")
                .parameters(preplayParameters)
                .assetType(VerizonMediaAssetType.ASSET)
                .contentProtected(false)
                .build();

// Multiple assets
VerizonMediaSource verizonMediaSource = new VerizonMediaSource.Builder(new String[]{"firstAsset", "secondAsset", "thirdAsset"}).build();

// External id single asset
VerizonMediaExternalId externalId = new VerizonMediaExternalId("userID", "externalAssetID");

// External id multiple assets
VerizonMediaExternalId externalId = new VerizonMediaExternalId("userID", new String[]{"firstExternalAsset", "secondExternalAsset", "thirdExternalAsset"});

// Source example for a regular asset id with e.g. 'delay' parameter and 'sig' token parameter.
Map<String, String> preplayParameters = new HashMap<>();
        preplayParameters.put("delay", "7200");
        preplayParameters.put("rays", "dcba");
        preplayParameters.put("sig", "2ff94739b021912712adafeccd6fa291f11eef0648c3b18b30224b84e0590b4f");
        
VerizonMediaSource verizonMediaSource = new VerizonMediaSource.Builder("assetID")
        .parameters(preplayParameters)
        .assetType(VerizonMediaAssetType.ASSET)
        .contentProtected(false)
        .build();

SourceDescription mySourceDescription = SourceDescription.Builder.sourceDescription(verizonMediaSource).build();
this.tpv.getPlayer().setSource(mySourceDescription);

The snippet above gives a quick overview of the structure of a Verizon Media-specific source, also known as a VerizonMediaSource.

iOS (/tvOS) SDK

// Swift examples
    
let verizonMediaSource = VerizonMediaSource(
    assetId: "verizonMedia_content_id",
    preplayParameters: [:], // Optional, defaults to an empty object. These will be added as query parameters to the Preplay API call.
    assetType: .ASSET, // Optional, defaults to ".ASSET". Can also be ".CHANNEL" or ".EVENT", following the Verizon Media semantics, where 'asset' is On-demand content.
    contentProtected: false // Optional, defaults to false.
)
    
// Source example for an external id (with optional properties omitted)
let externalId = VerizonMediaExternalId(
    userId: "verizonMedia_user_id",
    externalId: "verizonMedia_external_content_id"
)
let VerizonMediaSource = VerizonMediaSource(externalId: externalId)
    
// Source example for a regular asset id with e.g. 'delay' parameter and 'sig' token parameter.
let VerizonMediaSource = VerizonMediaSource(
    assetId: "verizonMedia_content_id",
    preplayParameters: [
        "delay":"7200",
        "rays":"dcba",
        "sig":"2ff94739b021912712adafeccd6fa291f11eef0648c3b18b30224b84e0590b4f"
    ], // Optional, defaults to an empty object. These will be added as query parameters to the Preplay API call.
    assetType: .ASSET, // Optional, defaults to ".ASSET". Can also be ".CHANNEL" or ".EVENT", following the Verizon Mediasemantics, where 'asset' is On-demand content.
    contentProtected: false // Optional, defaults to false.
)
    
let sourceDescription = SourceDescription(VerizonMediaSource: verizonMediaSource)
self.theoplayer.source = sourceDescription

The snippets above gives a quick overview of the structure of the Verizon Media-specific source, also known as a VerizonMediaSource. More information on certain properties:

• id: The ID field can instead of an asset id as a single string also specify an array of asset ids as strings, which will be stitched into a continuous stream. The same goes for theexternalIdproperty in case an external ID is used in the source.
• parameters: Optional, defaults to an empty object. The parameters specified here will be added as query parameters to the Preplay API call.
• preplayParameters: The preplayParameters object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.
• contentProtected: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.
• A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source. This request must also include adigital signatureif the 'Require a token for playback'option is enabled in the back-end on the corresponding live channel. (See also : Basic Setup > Playback URL's > Signing a Playback URL Tutorial)
• Verizon Mediaspecific documentation on the available playback URL query parameters can be found on the Verizon Mediadocumentation site under Basic Setup > Playback URL's > Customizing Playback via Parameters
• Some parameters can be  excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would, for this reason, be excluded from the digital signature.

Stream Configuration (with ads)

The examples below demonstrate how to configure a stream with server-side ads through a VerizonMediaSource.

Web SDK

player.source = {
    sources: [{
        integration: 'verizon-media',
        id: ['verizonMedia_content_first', 'verizonMedia_ad_break_1', 'verizonMedia_content_middle', 'verizonMedia_ad_break_2', 'verizonMedia_content_last'],
        preplayParameters: {
            // Parameters here should specify the necessary ad parameters for the Preplay API
            ad.param1: 'param_val1',
            ad.param2: 'param_val2'
        },
    }]
}

• preplayParameters: The preplayParameters object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.
• A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source. This request must also include adigital signatureif the 'Require a token for playback'option is enabled in the back-end on the corresponding live channel. (See also : Basic Setup > Playback URL's > Signing a Playback URL Tutorial)
• Verizon Media specific documentation on the available playback URL query parameters can be found on the Verizon Media documentation site under Basic Setup > Playback URL's > Customizing Playback via Parameters
• Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

Android (TV) SDK

Map<String, String> preplayParameters = new HashMap<>();
        preplayParameters.put("ad", "exampleadserver");

VerizonMediaSource verizonMediaSource = new VerizonMediaSource.Builder(new String[]{"verizonMedia_content_first", "verizonMedia_ad_break_1", "verizonMedia_content_middle", "verizonMedia_ad_break_2", "verizonMedia_content_last"})
                .parameters(preplayParameters)
                .build();

iOS (/tvOS) SDK

let verizonMediaSource = VerizonMediaSource(assetIds: ["verizonMedia_content_first", "verizonMedia_ad_break_1", "verizonMedia_content_middle", "verizonMedia_ad_break_2", "verizonMedia_content_last"], parameters: ["ad": "exampleadserver"])

Preplay Response

THEOplayer automatically interprets the response returned by the Preplay service. However, if a developer wants to perform their own logic with the Preplay API response, then they can intercept the preplayresponse event.

Web SDK

const listener = (event) => {
    console.log('Do something with the raw response of the Preplay API call', event.response);
}
    
player.verizonMedia.addEventListener('preplayresponse', listener);

Android (TV) SDK

EventListener<VerizonMediaPreplayResponseEvent> myListener = (VerizonMediaPreplayResponseEvent event) -> {
            // Do something with the preplay response
            event.getResponse();
        };
        
this.tpv.getPlayer().getVerizonMedia().addEventListener(VerizonMediaEventTypes.PREPLAYRESPONSE, myListener);

iOS (/tvOS) SDK

let eventListener = self.theoplayer.verizonMedia.addEventListener(type: VerizonMediaEventTypes.VerizonMedia_PREPLAY_RESPONSE) { event in
    // do something with the preplay response           
}

Using Tokens

Verizon Media users often leverage URL signatures (i.e. tokens) to further secure their content -- on top of AES-128 encryption or studio DRM. A token is (typically) generated on back-end using an API key and a set of parameters. (The documentation at Basic Setup > Playback URL's > Signing a Playback URL Tutorial describes this process.) This set of parameters should also be passed along to the preplayParameters in a VerizonMediaSource. If you do not configure the preplayParameters correctly in relation to your signature parameters, then the Preplay request made by THEOplayer will most likely return an invalid Preplay response, preventing THEOplayer from setting up your stream.

Let's consider a set-up where a Verizon Media customer uses both URL signatures and multi-DRM. When you do DRM, you must specify the rmt and manifest parameter. Thus, on your back-end, you must correctly calculate the value for rmt and manifest for the user-agent of your viewer. Then, you want to send all parameters which were used to generate your signature, including the generated signature, to your client-side where you set the VerizonMediaSource.

So, let's say that you use the following parameters on your back-end to generate the signature when you detect that the viewer is on Chrome and requires Widevine DRM with MPEG-DASH.

let params = {
    'v': '2',
    'tc': '1',
    'exp': 36000,
    'rn': 12345,
    'ct': 'a',
    'cid': '<CENSORED>',
    "rmt": "wv",
    "manifest": "mpd"
};
let query = Object.keys(params).map(key => key + '=' + params[key]).join('&');
let sig = CryptoJS.HmacSHA256(query, "<API_SECRET>").toString();
params['sig'] = sig;

Now you want to communicate this entire params object to your client-side, and set it as the value for preplayParameters:

player.source = {
    sources : {
        integration: 'verizon-media',
        id: '<CENSORED>',
        preplayParameters: params,
        assetType: 'asset',
        contentProtected: true
    }
}

When there's a mismatch between signature parameters and Preplay parameters, the Preplay response usually returns Invalid token signature and playback is not possible.

Related articles

• Verizon Media - Ads
• Verizon Media - Ping