C++ SDK QoE Ads

This guide is for integrating the C++-based MediaMelon Custom Player SDK

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 [email protected]

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

string component = "component";
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 communications network type to analytics.

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

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

Enum Value	Description
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 value	Description
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:

Property	Type	Description
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 value	Description
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();