# MediaMelon Android Bitmovin SDK Integration Document

**Step 1:** [Set up the build environment](#step-1-set-up-the-build-environment)

**Step 2:** [Register and Initialise SDK](#step-2-register-and-initialise-sdk)

**Step 3:** [Report Custom Metadata](#step-3-report-custom-metadata)

**Step 4:** [Report Stream Level Info](#step-4-report-stream-level-information)

**Step 5:** [Report Ended State](#step-5-report-ended-state)

**Step 6:** [Setup SSAI Ad Manager for Ad Callbacks](#step-6-setup-ssai-a-d-manager-for-ad-callbacks)

**Step 7:** [Initialize Harmonic SSAI Ad Manager](#step-7-initialize-harmonic-ssai-a-d-manager)

**Step 8:** [Update Asset Info dynamically](#step-8-update-asset-info-dynamically)

[Release Notes](#release-notes)

### Step 1: Set up the build environment

The SDK files are added to the build environment and the required network permissions are enabled.

1. Copy [`bitmovin-lib-release.aar`](https://sdks.mediamelon.com/android/bitmovin/qoe/1.3.5/bitmovin-lib-release.aar) provided with the release notes.

#### **Step 1.1: Add Gradle Dependency:**

**Using AAR:**

1. ```
   dependencies {
     ...
     api files ('bitmovin-lib-release.aar')
   }
   ```

**Using Maven:**

1. Add the following library to `app/build.gradle` :-<br>

   ```java
   dependencies {
       ...
       implementation("com.github.MediamelonSDK:mediamelon_bitmovin_sdk:1.3.5")
       ...
   }
   ```

#### Step 1.2 Provide Permissions

Add network permissions to `$MEDIA3PROJECT/demos/main/src/main/AndroidManifest.xml`

```xml
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
```

#### Step 1.3: Import Packages

```java
import com.mediamelon.qubit.ep.ContentMetadata;
import com.mediamelon.smartstreaming.MMAVAssetInformation;
import com.mediamelon.smartstreaming.MMPlayerState;
import com.mediamelon.smartstreaming.MMRegistrationInformation;
import com.mediamelon.smartstreaming.MMSmartStreaming;
import com.mediamelon.smartstreaming.ssai.harmonic.MMHarmonicSSAIAdInfo;
import com.mediamelon.smartstreaming.ssai.harmonic.MMHarmonicSSAIEventListeners;
import com.mediamelon.smartstreaming.bitmovin_harmonic_ssai.MMSmartStreamingBitmovinAdaptor;
```

### Step 2: Register and Initialise SDK

The player application must register the MediaMelon Player SDK and provide player information once when the application launches. Please note that values provided in this integration step persist across video sessions. This is typically done when the player itself is initialised.

#### Step 2.1: Set Asset Information

```java
MMAVAssetInformation assetInformation = new MMAVAssetInformation("ASSET_ID", "ASSET_NAME", "VIDEO_ID");
String jsonAssetInfo = assetInformation.toJSON();
MMSmartStreamingBitmovinAdaptor.JsonFromClient = jsonAssetInfo;
```

#### Step 2.2: Create Adaptor Instance

```java
MMSmartStreamingBitmovinAdaptor mmSmartStreamingBitmovinAdaptor  = new MMSmartStreamingBitmovinAdaptor(getApplicationContext()) ;
```

#### Step 2.3: Set Registration and Player Information

{% hint style="info" %}
CUSTOMER\_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at <customer-support@mediamelon.com>.
{% endhint %}

{% hint style="info" %}
Please provide the `hashSubscriberId` value in `setSubscriberInformation()`, `hashSubscriberId` boolean variable indicates whether the `SUBSCRIBER_ID` to be hashed or not.
{% endhint %}

<pre class="language-java"><code class="lang-java">MMRegistrationInformation registrationInformation = new MMRegistrationInformation("CUSTOMER_ID", "PLAYER_NAME");
registrationInformation.setPlayerInformation("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
registrationInformation.setDomain("DOMAIN_NAME");
boolean hashSubscriberId = true; 
registrationInformation.setSubscriberInformation("SUBSCRIBER_ID", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", hashSubscriberId);
MMSmartStreamingBitmovinAdaptor.setPlayerRegistrationInformation(registrationInformation, <a data-footnote-ref href="#user-content-fn-1">player</a>, getApplicationContext());
</code></pre>

#### Step 2.4: Set Stream URL

```java
mmSmartStreamingBitmovinAdaptor.setURL(url);
```

#### Step 2.5: Report Base Player Information

```java
MMSmartStreamingBitmovinAdaptor.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
```

#### Step 2.6: Report Application Information

```java
mmSmartStreamingBitmovinAdaptor.reportAppInfo("APP_NAME", "APP_VERSION");
```

#### Step 2.7: Report Content Metadata

```java
ContentMetadata cm  = new ContentMetadata();

cm.videoId="VIDEO_ID";
cm.seriesTitle="SERIES_TITLE";
cm.season="SEASON";
cm.genre="GENRE";
cm.episodeNumber="EPISODE_NUMBER";
cm.drmProtection="DRM_PROTECTION";
cm.contentType="CONTENT_TYPE";
cm.assetName="ASSET_NAME";
cm.assetId="ASSET_ID";

JSONObject jsonObj = cm.getJSONObject();
MMSmartStreamingBitmovinAdaptor.contentMetadataFromUser = jsonObj;
```

#### Step 2.8: Report Experiment Name

```java
mmSmartStreamingBitmovinAdaptor.reportExperimentName("EXPERIMENT_NAME");
```

#### Step 2.9: Report View Session Id <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

```java
mmSmartStreamingBitmovinAdaptor.reportViewSessionId("VIEW_SESSION_ID");
```

#### Step 2.10: Report Sub Property Id <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

```java
mmSmartStreamingBitmovinAdaptor.reportSubPropertyId("SUB_PROPERTY_ID");
```

#### Step 2.11: Report Player Resolution

```java
mmSmartStreamingBitmovinAdaptor.reportPlayerResolution(playerWidth, playerHeight);
```

### Step 3: Report Custom Metadata

Check the custom tags configuration in your [dashboard](https://smartsight3.mediamelon.com/settings) and report accordingly. If the custom tags are not configured, please configure and use them accordingly.

```java
mmSmartStreamingBitmovinAdaptor.reportCustomMetadata("custom_1", "VALUE_1");
```

### Step 4: Report Stream Level Information

#### Step 4.1: Report Stream Info

Report key stream attributes that describe the encoding and delivery method.

```java
mmSmartStreamingBitmovinAdaptor.reportStreamInfo("STREAM_FORMAT", "MEDIA_TYPE", "SOURCE_TYPE", isLive)
```

#### Step 4.2: Report CDN

Report the name or identifier of the Content Delivery Network (CDN) used for streaming. This helps track performance and quality across different CDNs.

```java
mmSmartStreamingBitmovinAdaptor.reportCDN("CDN");
```

### Step 5: Report Ended State

```java
@Override
protected void onDestroy() {
    playerView.onDestroy();
    super.onDestroy();
    MMSmartStreaming.getInstance().reportPlayerState(MMPlayerState.STOPPED);
}
```

### Step 6: Setup SSAI Ad Manager for Ad Callbacks

To handle Harmonic SSAI events, create an object of `MMHarmonicSSAIEventListeners` in the required class and implement the methods you need. Once implemented, add the listener to `mmSmartStreamingBitmovinAdaptor` as shown below:

```swift
 MMHarmonicSSAIEventListeners mmHarmonicSSAIEventListeners = new MMHarmonicSSAIEventListeners() {
    @Override
    public void onAdImpression(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdStarted(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdFirstQuartile(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdMidpoint(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdThirdQuartile(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdComplete(MMHarmonicSSAIAdInfo ssaiAdInfo) { }
 };
 mmSmartStreamingBitmovinAdaptor.addSSAIListener(mmHarmonicSSAIEventListeners);
```

#### **6.1  MMHarmonicSSAIEventListners  callbacks:**

The following callbacks are available within the `MMHarmonicSSAIEventListeners` interface:

* `onAdImpression`
* `onAdStarted`
* `onAdFirstQuartile`
* `onAdMidpoint`
* `onAdThirdQuartile`
* `onAdComplete`

#### **6.2  AdInfo Accessible Methods:**

The `AdInfo` object provides several methods to access ad-related information:

* `getAdClient()`
* `getAdCurrentPlaybackTime()`
* `getAdDuration()`
* `getAdStartTime()`
* `getAdEndTime()`
* `getAdId()`
* `getAdServer()`

### Step 7: Initialize Harmonic SSAI Ad Manager

* **DASH** `PMM_URL`: Send the final redirected URL with the pmm ID.
* **HLS** `PMM_URL`: Send the variant URL with the pmm ID.

{% hint style="info" %}
Note: Call `initializeHarmonicSSAIAdManager` only once at the stream start.
{% endhint %}

```java
mmSmartStreamingBitmovinAdaptor.initializeHarmonicSSAIAdManager("PMM_URL");
```

### Step 8: Update Asset Info dynamically

If Asset Information needs to be updated dynamically during the live session without re-initiating the player, then the "updateAssetInfo” API can be used to update the new AssetInfo.

**Note:**

1. This API must be called for updating asset info for the live streams only
2. This API must be called after the Player has started the live-stream playback.
3. The new Asset Info Object will override the previous values, hence set all the required fields every time before calling this API.

```java
MMAVAssetInformation newAssetInformation = new MMAVAssetInformation("ASSET_ID", "ASSET_NAME", "VIDEO_ID");
MMSmartStreamingBitmovinAdaptor.updateAssetInfo(newAssetInformation, player, "SEASON","GENRE","EPISODE_NUMBER","CONTENT_TYPE","VIDEO_TYPE","DRM_PROTECTION","SERIES_TITLE");
```

#### Release Notes

<details>

<summary>Current Release</summary>

#### v1.3.5[^2]

* Added API to report App Session ID.
* Added API to report CDN.
* Added events for AD-BUFFERING.
* Fix for Ad playtime for session with no ads.
* Updated folder structure

</details>

***

<details>

<summary>Previous Releases</summary>

#### v1.3.4

* Added API to report Application Information
* Added API to report Stream Information

#### v1.3.3

* Number field in streaming\_progress removed

</details>

[^1]: Player Instance

[^2]: Release Date: 11/3/2026