Conviva

The fl-conviva library integrates with conviva platform to provide a single source of identity and insights for everything streaming.

Setup

1. Obtain your customerKey from Conviva. Two customer keys will be provided, one for TEST and the other for a PRODUCTION environment.
2. Have access to Touchstone for debugging. The TEST customer key will be used for debugging.

Load conviva core-sdk library

<script type="text/javascript" src="../js/conviva-core-sdk.js"></script>

Create Conviva Session

Create a new Conviva session by providing proper initialization data including your keys and your device information.

var flConvivaSession = flConviva.createConvivaSession(
    initializationData,
    deviceMetadata,
    adPlayerInfo,
    logger
);

initializationData

It is an object containing your customer key. Optionally you can indicate whether your session is a production session or a debug session. Default is production. Make sure to provide the proper customer key.

note

In case you're setting up a debug session you must provide the gatewayUrl from Touchstone and enable debug. For Production, Conviva library will use the automatically assigned gatewayUrl

Example

var initializationData = {
    customerKey: <customerKey>,
    debug: true,
    gatewayUrl: https://<customerKey>.testonly.conviva.com,
}

deviceMetadata

Information of the device on which content being played.

Name	Type	Required	Description	Example
BRAND	string	false	Brand of the device	"Apple", "Samsung", "Huawei", "Google"
MODEL	string	false	Model of the device	"iPhone 6 Plus", "HTC One", "Roku 3"
MANUFACTURER	string	false	Manufacturer of the device	"Samsung", "Apple", "HTC", "Sony"
TYPE	string	false	Type of the device. Only allows the DeviceType values and discards any other string values	Conviva.Constants.DeviceType.DESKTOP Conviva.Constants.DeviceType.CONSOLE_LOG Conviva.Constants.DeviceType.MOBILE
OS_NAME	string	false	Name of the operating system used by the device in uppercase	"WINDOWS", "LINUX", "IOS", "MAC", ANDROID", "FIREOS", "ROKU", "PLAYSTATION", "CHROMEOS"
OS_VERSION	string	false	Version of the operating system used by the device	"10.10.1", "8.1", "T-INFOLINK2012-1012", "Fire OS 5"
CATEGORY	string	false	Device Category to which the used device belongs to. Only allows the Constants.DeviceCategory values and discards any other string value	Conviva.Constants.DeviceCategory.WEB Conviva.Constants.DeviceCategory.ANDROID Conviva.Constants.DeviceCategory.PLAYSTATION
SCREEN_RESOLUTION_WIDTH	number	false	Width of the current display in pixels. Note: Autocollected using window.screen.width API for most of the web-based platforms	1280, 1440, 1366, 1920
SCREEN_RESOLUTION_HEIGHT	number	false	Height of the current display in pixels. Note: Autocollected using window.screen.height API for most of the web-based platforms	720, 900, 768, 1080
SCREEN_RESOLUTION_SCALE_FACTOR	number	false	The ratio of the current displayhardware-based pixels to the device-independent pixels. Note: Autocollected as 1, if the value not set by application and autocollected using window.screen.devicePixelRatio API for most of the web-based platforms	1.5, 2, 1

Example

var deviceMetadata = {};

deviceMetadata[Conviva.Constants.DeviceMetadata.BRAND] = 'Apple';
deviceMetadata[Conviva.Constants.DeviceMetadata.MANUFACTURER] = 'Apple';
deviceMetadata[Conviva.Constants.DeviceMetadata.MODEL] = 'Macbook Pro';
deviceMetadata[Conviva.Constants.DeviceMetadata.TYPE] = Conviva.Constants.DeviceType.DESKTOP;
deviceMetadata[Conviva.Constants.DeviceMetadata.OS_NAME] = 'bigSur';
deviceMetadata[Conviva.Constants.DeviceMetadata.OS_VERSION] = '11.6.2';
deviceMetadata[Conviva.Constants.DeviceMetadata.CATEGORY] = Conviva.Constants.DeviceCategory.WEB;

adPlayerInfo

Player information on which the ads being played.

Example

var adPlayerInfo = {};

adPlayerInfo[Conviva.Constants.FRAMEWORK_NAME] = 'FlPlayer';
adPlayerInfo[Conviva.Constants.FRAMEWORK_VERSION] = flPlayer.version;

Initialize Session

ConvivaSession should be created once per app session and the same session instance can be used to report multiple video playback sessions.

flConvivaSession.initialize();

Active or Inactive Session

To check whether a previous session is still active or not. It has to be checked before initialize or destory session.

flConvivaSession.isInitialized();

Report Playback Request

To initiate a Video Playback session, this API must be called in following use-cases:

• User clicks play button
• Video starts in autoplay mode
• User replays video again
• A new video starts in playlist

flConvivaSession.reportPlaybackRequested(metadata, adMetadata)

Configure Metadata

Information about the video and content metadata.

Video metadata

Name	Required	Description
STREAM_URL	true	URL of the video being Played
ASSET_NAME	true	Name of the content being played
IS_LIVE	false	Type of the content whether LIVE or VOD
PLAYER_NAME	true	Name of the player
VIEWER_ID	true	Unique identifier of the user
ENCODED_FRAMERATE	false	Frame rate of the content
DURATION	false	Total Duration of the content
FRAMEWORK_NAME	false	Player framework name on which video is being played
FRAMEWORK_VERSION	false	Player framework version on which video is being played
APPLICATION_VERSION	false	App version where the video is being played

Content metadata

Name	Required	Description	Example
c3.cm.contentType	false	Advanced content delivery methods along with Live and VOD. Acceptable values: "Live", "Live-Linear", "DVR", "Catchup", "VOD".	"Live", "Live-Linear", "DVR", "Catchup", "VOD"
c3.cm.channel	false	The channel on which the content is consumed.	"Sony Six"
c3.cm.brand	false	The name of the brand to which the content belongs.	"SonyLiv"
c3.cm.affiliate	false	Affiliate or MVPD name for TV Everywhere authenticated services.	"Xfinity", "Comcast"
c3.cm.categoryType	false	Content business categories of interest.	"Episodic", "Movies", "News", "Sports"
c3.cm.name	false	Name of CMS Provider.	"CMS", "ROVI", "TMS"
c3.cm.id	false	Unique asset identifier to query CMS system to gather additional asset metadata information for a specific asset.	"003b094d-fc5c-3d5a-8ed0-301bf848291e"
c3.cm.seriesName	false	The name of Series. Set the value only if the metadata cannot be gathered from CMS System. Null if not applicable.	"Friends", "Null"
c3.cm.seasonNumber	false	The Season number. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable.	"1", "Null"
c3.cm.showTitle	false	The name of the Episode or Show Title. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable.	"The One with All the Cheesecakes", "Null"
c3.cm.episodeNumber	false	The Episode number. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable.	"3", "Null"
c3.cm.genre	false	The Primary content genre. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable	"Drama", "Null"
c3.cm.genreList	false	The list of the applicable content genre. Set the values in a comma separated list only if the details cannot be inferred from Asset Provider Server. Null if not applicable.	"Drama, Crime, Political, Violence", "Null"
c3.cm.utmTrackingUrl	false	Provide the UTM parameters in the URL to track the effectiveness of the online marketing campaign across traffic sources and publishing media. Conviva uses CONTAINS logic to parse the individual UTM parameters from the URL provided, so either the full URL or just the UTM parameters is acceptable. Note: This tag is only applicable for web and mobile devices.	Example values: http://www.example.com/?utm_source=newsletter1&utm_medium=email&utm_campaign=summer-sale&utm_content=toplink or utm_source=newsletter1&utm_medium=email&utm_campaign=summer-sale&utm_content=toplink

Example

var metadata = {};

// video metadata
metadata[Conviva.Constants.STREAM_URL] = 'your main content stream url';
metadata[Conviva.Constants.ASSET_NAME] = 'your main content asset name';
metadata[Conviva.Constants.VIEWER_ID] = 'your viewer unique identifier'; // do not send for anonymous user
metadata[Conviva.Constants.PLAYER_NAME] = 'your player name';
metadata[Conviva.Constants.APPLICATION_VERSION] = 'your application version';

// content metadata
metadata['c3.cm.contentType'] = 'VOD';
metadata['c3.cm.categoryType'] = 'Sports';
metadata['c3.cm.id'] = 'your asset unique identifier';
metadata['c3.cm.showTitle'] = 'WWE Extreme Rules 2016';
metadata['c3.cm.genre'] = 'Sports';
metadata['c3.cm.genreList'] = 'Sports, News';

// custom metadata
metadata.tag1 = 'your custom value for tag1';
metadata.tag2 = 'your custom value for tag2';

adMetadata

The additional information about the ads being played.

Name	Type	Required	Description
adTechnology	AdTechnology	false	Whether the ad is from server side or client side
isSlate	string	false	Whether the slate contents are available or not
adMediaFileApiFramework	string	false	Framework used for interactions between ad units and video player
adStitcher	string	false	Name of the adSticher vendor

AdTechnology

The following are the ad technology reported to conviva.

Name	Description
CLIENT_SIDE	Represents the ad is from client side
SERVER_SIDE	Represents the ad is from server side

Example

var adMetadata = {};
adMetadata.adTechnology = flConviva.AdTechnology.SERVER_SIDE;
adMetadata.isSlate = 'true'; // true or false
adMetadata.adMediaFileApiFramework = 'VPAID';
adMetadata.adStitcher = 'yospace';

Attach Video Player

The video player could take some time to initialize from the moment the user initiates playback so a different function is provided to attach the video player once the video player is initialized.

flConvivaSession.attachPlayer(player);

Update Metadata

To update or amend pre-defined and custom tags for video after attatching the player, use:

flConvivaSession.setContentMetadata(metadata)

Report Errors

To report any errors while authorizing the content, use:

flConvivaSession.reportError(error);

note

All error that occur in the middle of the playback are automatically reported by ConvivaSession. This API should be called to report errors that occur before initializing the player (e.g., authorizing the content)

Report Playback Events

Conviva allows reporting any user-wait states in the Playback flow so Video Start Time (VST) metric can be accurately captured. Here are some examples of user-wait states:

• parentel pin popup
• accepting strong language or violence
• resume or continue watching dialogue
• watch party initiation

To report user wait started:

flConvivaSession.reportEvent(Conviva.Constants.Events.USER_WAIT_STARTED);

To report user wait ended:

flConvivaSession.reportEvent(Conviva.Constants.Events.USER_WAIT_ENDED);

Report Custom Events

Conviva allows reporting custom player related events assiciated with a playback session. To report a custom event:

var eventName = "quality-change";
var info = {
  from: "FHD",
  to: "4K"
};

flConvivaSession.reportCustomEvent(eventName, info);

Backgrounding & Foregrounding

To report backgrounding events (e.g., user pressing home or power off buttons), use:

flConvivaSession.reportAppBackgrounded();

To handle foregrounding events:

flConvivaSession.reportAppForegrounded();

Destory Session

The conviva session has to be destoryed when application is terminated.

flConvivaSession.destroy();