# C++ SDK QoE Ads

### **Step 1:** MediaMelon SDK Files <a href="#step-1-add-mediamelon-smartstreaming-sdk-hardbreak" id="step-1-add-mediamelon-smartstreaming-sdk-hardbreak"></a>

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

```cpp
#include "cpp_mmsmartstreaming.h"
```

### **Step 2: Register and Initialise** the MediaMelon Player SDK <a href="#step-2-register-and-initialize-mediamelon-sdk" id="step-2-register-and-initialize-mediamelon-sdk"></a>

{% hint style="info" %}
\<customer\_id> as your MediaMelon-assigned Customer ID. If you do not know your Customer ID contact MediaMelon at [support@mediamelon.com](http://40mediamelon.com/)
{% endhint %}

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

```cpp
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.

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

#### Network Type:

Reports the communications network type to analytics.

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

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

<table><thead><tr><th width="312">Enum Value</th><th>Description</th></tr></thead><tbody><tr><td>MMConnectionInfo::Cellular</td><td>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.</td></tr><tr><td>MMConnectionInfo::Cellular_2G</td><td>Connection type is 2G cellular.</td></tr><tr><td>MMConnectionInfo::Cellular_3G</td><td>Connection type is 3G cellular.</td></tr><tr><td>MMConnectionInfo::Cellular_4G</td><td>Connection type is 4G cellular.</td></tr><tr><td>MMConnectionInfo::Cellular_LTE</td><td>Connection type is LTE cellular.</td></tr><tr><td>MMConnectionInfo::Cellular_5G</td><td>Connection type is 5G cellular.</td></tr><tr><td>MMConnectionInfo::NotReachable</td><td>Connection non reachable.</td></tr><tr><td>MMConnectionInfo::Wifi</td><td>Connection type is WiFi.</td></tr><tr><td>MMConnectionInfo::WiredNetwork</td><td>Connection type is wired.</td></tr></tbody></table>

#### Presentation Information:

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

```cpp
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.

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

#### Player State:

Reports the current player state to analytics.

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

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

<table><thead><tr><th width="253">Enum value</th><th>Description</th></tr></thead><tbody><tr><td>MMPlayerState::PLAYING</td><td>Player is playing available content to the screen. Delays due to re-buffering are still considered PLAYING.</td></tr><tr><td>MMPlayerState::PAUSED</td><td>Player is paused</td></tr><tr><td>MMPlayerState::STOPPED</td><td>Playback is stopped, either due to user request or reaching the end of the content.</td></tr></tbody></table>

> **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***.

```cpp
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.

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

#### Buffering:

Reports the start and completion of the buffering.

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

#### **Error:**

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

```cpp
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.

```cpp
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***.

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

#### Frame Loss:

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

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

### Step 5: Report Advertisement Analytics

#### Ad Info:

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

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

`MMAdInfo` properties and their respective data types are mentioned below:

<table><thead><tr><th width="210">Property</th><th width="119.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>adTitle</td><td><code>string</code></td><td>Advertisement title</td></tr><tr><td>adId</td><td><code>string</code></td><td>Advertisement ID</td></tr><tr><td>adDuration</td><td><code>int</code></td><td>Length of the video ad (in milliseconds).</td></tr><tr><td>adClient</td><td><code>string</code></td><td>Client used to play the ad, eg: VAST.</td></tr><tr><td>adServer</td><td><code>string</code></td><td>Ad server (ex. DoubleClick, YuMe, AdTech, Brightroll, etc.)</td></tr><tr><td>adCreativeId</td><td><code>string</code></td><td>The creative ID of the ad.</td></tr><tr><td>adCreativeType</td><td><code>string</code></td><td>Ad MIME type.</td></tr><tr><td>adPodIndex</td><td><code>int</code></td><td>Index of the ad pod.</td></tr><tr><td>adPodLength</td><td><code>int</code></td><td>Length of Pod, starts from 0 if ad in not part of any pod.</td></tr><tr><td>adPodPosition</td><td><code>int</code></td><td>Position of ad in Pod, starts from 0.</td></tr><tr><td>adPosition</td><td><code>string</code></td><td>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.</td></tr><tr><td>adBitrate</td><td><code>int</code></td><td>Advertisement bitrate (bits per second).</td></tr><tr><td>adResolution</td><td><code>string</code></td><td>Advertisement video resolution.</td></tr><tr><td>adUrl</td><td><code>string</code></td><td>Tag represented by the ad.</td></tr><tr><td>isBumper</td><td><code>bool</code></td><td>Represents the ad is bumper or not.</td></tr></tbody></table>

#### Ad State:

Reports advertisement playback state.

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

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

<table><thead><tr><th width="326">Enum value</th><th>Description</th></tr></thead><tbody><tr><td>MMAdState::AD_REQUEST</td><td>Ad is requested [initial state]</td></tr><tr><td>MMAdState::AD_IMPRESSION</td><td>Ad impression happened before ad starts playing</td></tr><tr><td>MMAdState::AD_STARTED</td><td>Ad started playing</td></tr><tr><td>MMAdState::AD_FIRST_QUARTILE</td><td>Ad reached 25% of the ad duration</td></tr><tr><td>MMAdState::AD_MIDPOINT</td><td>Ad reached 50% of the ad duration</td></tr><tr><td>MMAdState::AD_THIRD_QUARTILE</td><td>Ad reached 75% of the ad duration</td></tr><tr><td>MMAdState::AD_COMPLETED</td><td>Ad completed play [terminal state]</td></tr><tr><td>MMAdState::AD_ENDED</td><td>Ad ended before reaching the completion point [terminal state]</td></tr><tr><td>MMAdState::AD_SKIPPED</td><td>Ad is skipped [terminal state]</td></tr><tr><td>MMAdState::AD_PAUSED</td><td>Ad is paused</td></tr><tr><td>MMAdState::AD_RESUMED</td><td>Ad playback session resumed</td></tr><tr><td>MMAdState::AD_BLOCKED</td><td>Ad is blocked [terminal state]</td></tr><tr><td>MMAdState::AD_ERROR</td><td>Unknown error prevented Ad play [terminal state]</td></tr><tr><td>MMAdState::AD_CLICKED</td><td>User clicks an ad to be redirected to its landing page</td></tr></tbody></table>

#### Ad Playback Time:

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

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

#### Ad Error:

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

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

#### Ad Buffering:

Reports the start and completion of the advertisement buffering.

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