Custom Player C++ SDK

Comprehensive Integration Guide for the C++-based MediaMelon Custom Player SDK

Step 1: MediaMelon SDK Files

Step 2: Register and Initialise the MediaMelon Player SDK

Step 3: Report Custom, Network & Presentation Information

Step 4: Report Player State & Actions

Step 5: Report Advertisement Analytics

Step 1: MediaMelon SDK Files

Add and import the required MediaMelon SDK header files provided in the release notes

#include "cpp_mmsmartstreaming.h"

Step 2: Register and Initialise the MediaMelon Player SDK

<customer_id> as your MediaMelon-assigned Customer ID. If you do not know your Customer ID contact MediaMelon at support@mediamelon.com

Register the MediaMelon SDK and report the player information and device information as shown below:

string component = "CPPSDK";
string deviceOS = "Linux";

MMSmartStreaming::registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", component, "SUBSCRIBER_ID","DOMAIN_NAME","SUBSCRIBER_TYPE", "SUBSCRIBER_TAG");
MMSmartStreaming::reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
MMSmartStreaming::reportDeviceInfo("DEVICE_BRAND", "DEVICE_MODEL", deviceOS,"DEVICE_OS_VERSION", "TELECOM_OPERATOR",<screenWidth:int>,<screenHeight:int>,"DEVICE_TYPE");

//Set content metadata of the video and initialise the session as shown below
MMContentMetadata contentMetadata;
contentMetadata.setAssetInfo("ASSET_ID", "ASSET_NAME", "VIDEO_ID");
contentMetadata.setContentType("CONTENT_TYPE");
contentMetadata.setDrmProtection("DRM_PROTECTION");
contentMetadata.setEpisodeNumber("EPISODE_NUMBER");
contentMetadata.setGenre("GENRE");
contentMetadata.setSeason("SEASON");
contentMetadata.setSeriesTitle("SERIES_TITLE");

MMSmartStreaming::getInstance().initializeSession(QBRModeDisabled,"MEDIA_URL","META_URL", contentMetadata, NULL);

Step 3: Report Custom, Network & Presentation Information

This information should be reported before the video starts playing.

Custom Metadata:

Reports custom metadata, in the form of a key-value pair, to analytics.

MMSmartStreaming::getInstance().reportCustomMetadata("KEY1", "VALUE1");
MMSmartStreaming::getInstance().reportCustomMetadata("KEY2", "VALUE2");

Network Type:

Reports the communication network type to analytics.

MMSmartStreaming::getInstance().reportNetworkType(<networkType:MMConnectionInfo>);

Enum values and their description for the MMConnectionInfo are as below;

Enum ValueDescription

MMConnectionInfo::Cellular

Connection type is cellular (generic). If user explicitly knows the kind of connection, 2G or 3G for example, then they should use explicit enum value corresponding to that connection type.

MMConnectionInfo::Cellular_2G

Connection type is 2G cellular.

MMConnectionInfo::Cellular_3G

Connection type is 3G cellular.

MMConnectionInfo::Cellular_4G

Connection type is 4G cellular.

MMConnectionInfo::Cellular_LTE

Connection type is LTE cellular.

MMConnectionInfo::Cellular_5G

Connection type is 5G cellular.

MMConnectionInfo::NotReachable

Connection non reachable.

MMConnectionInfo::Wifi

Connection type is WiFi.

MMConnectionInfo::WiredNetwork

Connection type is wired.

Presentation Information:

Reports the available representations of the video that the player can present.

MMPresentationInfo presentationInfo;
presentationInfo.isLive = false;        //video type (true for live video and fasle for VOD)
presentationInfo.duration = 100*1000;   //video duration in milliseconds

MMRepresentation *rep1 = new MMRepresentation(<trackIndex:int>,<bitrate:int>,<width:int>,<height:int>,"VCODEC,ACODEC");
presentationInfo.addRepresentation(rep1);
MMRepresentation *rep2 = new MMRepresentation(<trackIndex:int>,<bitrate:int>,<width:int>,<height:int>,"VCODEC,ACODEC");
presentationInfo.addRepresentation(rep2);

MMSmartStreaming::getInstance().setPresentationInformation(presentationInfo);

Step 4: Report Player State & Actions

Playback Initiation:

Reports that user initiated the playback session. This should be called at different instants depending on the mode of operation of player. In Auto Play Mode, should be the called when payer is fed with the manifest URL for playback In non-Auto Play Mode, should be called when the user presses the play button on the player.

MMSmartStreamingSDK::MMSmartStreaming::getInstance().reportUserInitiatedPlayback();

Player State:

Reports the current player state to analytics.

MMSmartStreaming::getInstance().reportPlayerState(<playerState:MMPlayerState>);

Enum values and their description for the MMPlayerState are as below;

Enum valueDescription

MMPlayerState::PLAYING

Player is playing available content to the screen. Delays due to re-buffering are still considered PLAYING.

MMPlayerState::PAUSED

Player is paused

MMPlayerState::STOPPED

Playback is stopped, either due to user request or reaching the end of the content.

Note: When the player enters the STOPPED state the current video session is terminated. Re-entering the PLAYING state will result in a new session being logged for the video. The most common reason for this occurring is when a video plays to the end and then the user seeks back to a point earlier in the video.

Playback Position:

Reports current playback position in media to analytics. This should be reported every two seconds if possible. Reported playback position should be in milliseconds.

MMSmartStreaming::getInstance().reportPlaybackPosition(<playbackPosition:int>);

Seek Complete:

Reports that a seek event is complete, with the new playback starting position in milliseconds. This is the point from which playback will start after the seek.

MMSmartStreaming::getInstance().reportPlayerSeekCompleted(<seekEndPosition:int>);

Buffering:

Reports the start and completion of the buffering.

MMSmartStreaming::getInstance().reportBufferingStarted();
MMSmartStreaming::getInstance().reportBufferingCompleted();

Error:

Reports an error encountered during the playback. Playback position should be in milliseconds.

MMSmartStreaming::getInstance().reportError("ERROR_MESSAGE", <playbackPosition:int>);

Chunk Request:

Reports the encoded chunk bitrate when the current playing chunk bitrate is different from the previous chunk bitrate.

MMChunkInformation mmChunkInfo;
mmChunkInfo.bitrate = <bitrate:int>; //encoded bitrate in bits per second
MMSmartStreaming::getInstance().reportChunkRequest(mmChunkInfo);

Download Rate:

Reports current download rate (rate at which chunk is downloaded) to analytics. This should be reported for every chunk download (if possible). If this value is not available on every chunk download, then last updated value with player should be reported every 2 seconds. Reported download rate should be in bits per second.

MMSmartStreaming::getInstance().reportDownloadRate(<downloadRate:int>);

Frame Loss:

Reports cumulative frame loss count to analytics. This is Cumulative count of frames lost in playback session.

MMSmartStreaming::getInstance().reportFrameLoss(<frameLossCount:int>);

Step 5: Report Advertisement Analytics

Ad Info:

Reports advertisement-related information before or at the time of ad start.

MMSmartStreaming::getInstance().reportAdInfo(<adInfo:MMAdInfo>);

MMAdInfo properties and their respective data types are mentioned below:

PropertyTypeDescription

adTitle

string

Advertisement title

adId

string

Advertisement ID

adDuration

int

Length of the video ad (in milliseconds).

adClient

string

Client used to play the ad, eg: VAST.

adServer

string

Ad server (ex. DoubleClick, YuMe, AdTech, Brightroll, etc.)

adCreativeId

string

The creative ID of the ad.

adCreativeType

string

Ad MIME type.

adPodIndex

int

Index of the ad pod.

adPodLength

int

Length of Pod, starts from 0 if ad in not part of any pod.

adPodPosition

int

Position of ad in Pod, starts from 0.

adPosition

string

Position of the ad in the video playback; one of “pre”, “post” or “mid” that represents that the ad played before, after or during playback respectively.

adBitrate

int

Advertisement bitrate (bits per second).

adResolution

string

Advertisement video resolution.

adUrl

string

Tag represented by the ad.

isBumper

bool

Represents the ad is bumper or not.

Ad State:

Reports advertisement playback state.

MMSmartStreaming::getInstance().reportAdState(<adState:MMAdState>);

Enum values and their description for the MMAdState are as below;

Enum valueDescription

MMAdState::AD_REQUEST

Ad is requested [initial state]

MMAdState::AD_IMPRESSION

Ad impression happened before ad starts playing

MMAdState::AD_STARTED

Ad started playing

MMAdState::AD_FIRST_QUARTILE

Ad reached 25% of the ad duration

MMAdState::AD_MIDPOINT

Ad reached 50% of the ad duration

MMAdState::AD_THIRD_QUARTILE

Ad reached 75% of the ad duration

MMAdState::AD_COMPLETED

Ad completed play [terminal state]

MMAdState::AD_ENDED

Ad ended before reaching the completion point [terminal state]

MMAdState::AD_SKIPPED

Ad is skipped [terminal state]

MMAdState::AD_PAUSED

Ad is paused

MMAdState::AD_RESUMED

Ad playback session resumed

MMAdState::AD_BLOCKED

Ad is blocked [terminal state]

MMAdState::AD_ERROR

Unknown error prevented Ad play [terminal state]

MMAdState::AD_CLICKED

User clicks an ad to be redirected to its landing page

Ad Playback Time:

Reports current advertisement playback position. This should be reported every two seconds if possible. Reported playback position should be in milliseconds.

MMSmartStreaming::getInstance().reportAdPlaybackTime(<playbackPosition:int>);

Ad Error:

Reports error encountered during the advertisement playback. Playback position should be in milliseconds.

MMSmartStreaming::getInstance().reportAdError("AD_ERROR_MESSAGE", <playbackPosition:int>);

Ad Buffering:

Reports the start and completion of the advertisement buffering.

MMSmartStreaming::getInstance().reportAdBufferingStarted();
MMSmartStreaming::getInstance().reportAdBufferingCompleted();

Last updated