VO Player (Nowtilus SSAI)

Step by step guide for integrating the VO Player SDK with Nowtilus SSAI to a VO Player based Player Application

STEP 0

Please find the Sample reference application under

https://mediamelon-builds.s3.amazonaws.com/MM-RELEASE-BUILDS/SDK_RELEASES/Android/2023-05-11/voPlayer/VO-Player-SSAI-Release-(09.05.00).zip

STEP 1

Add the following lines to access the SDK

In the Sample Application this is added in CustomPlayerActivity.java

//MM1
import com.mediamelon.smartstreaming.MMPlayerState;
import com.mediamelon.smartstreaming.MMSmartStreamingNowtilusSSAIPlugin;
import com.mediamelon.smartstreaming.mmAd;
import com.mediamelon.smartstreaming.mmAdTimelineInfo;
import com.mediamelon.smartstreaming.MMSSAIEventsListeners;
import com.mediamelon.smartstreaming.MMSmartStreaming;
import com.mediamelon.smartstreaming.MMSmartStreamingVOAdaptor;
//MM1

STEP 2

startMediaMelonSDK() API calls all MediaMelon SDK Integration API's. To start MediaMelon SDK, please call startMediaMelonSDK() API.And register MediaMelon SDK using your assigned customerID in StartMediaMelonSDK() API. Please refer code block below.

Note:

Please provide the exact correct details in all fields like CUSTOMER_ID, ASSET_ID, ASSET_TITLE, VIDEO_ID, PLAYER_BRAND, PLAYER_MODEL, PLAYER_VERSION, PLAYER_NAME, DOMAIN_NAME, SUBSCRIBER_ID, SUBSCRIBER_TYPE & SUBSCRIBER_TAG. This data helps in debugging through MediaMelon SmartSight if anything goes wrong.

    //MM2
    boolean sdkIntegration = false;
    public void startMediaMelonSDK() {

        //MM2A
            sdkIntegration = true;
            mmVoPlayerAdapter = new MMSmartStreamingVOAdaptor(getApplicationContext(), mMyVOPlayer);
            mmVoPlayerAdapter.enableLogTrace(true); // Set false in production
    
            if (!MMSmartStreaming.getRegistrationStatus()) {
                mmVoPlayerAdapter.registerMMSmartStreaming("VoPlayer", "1922042005", "subscriber_id", "Domain", "subscriber_type", "subscriber_tag");
            }
    
            Log.d("MM Reg", "MM Reg:" + MMSmartStreaming.getRegistrationStatus());
            mmVoPlayerAdapter.reportPlayerInfo("VO", "VoPlayers", "1.0");
            //MM2A
             
    }
    //MM2

Parameters passed in Registration call

Variable	Description
$PLAYERNAME	Player Name as in ExoPlayer, KalturaPlayer etc.
$CUSTOMERID	String containing your MediaMelon-assigned Customer ID.
$SUBSCRIBERID	String containing your subscriber’s ID. If you do not use subscriber IDs, leave it as it is.
$DOMAINNAME	String containing your section of your subscriber or assets. (Optional)
$SUBSCRIBERTYPE	String containing the subscriber type (e.g. “Free”, “Paid”). If you do not use subscriber types, leave it as it is.
$SUBSCRIBERTAG	String containing an additional subscriber-specific information. This is sent in clear (not hashed) to SmartSight and it is advised to not send sensitive information in this field.

STEP 3

Add the below lines following the registration to enable the Nowtilus SSAI Ad Manager in startMediaMelonSDK() API.

NOTE - boolean enablePollingforSSAI variable indicates whether the Mediamelon SDK needs to poll for the VAST URL or not. Please set it to true if you want to opt for polling else set it to false.

For VOD Streams , set isLive Parameter false and stores AD information in vodResponseData and sends to NowtilusAdManager

Refer getURLDetails function in the sample application to get the mediaURL and AD Data from the curl request for both live and VoD streams. If the stream is VoD, set the isLive variable to false. If the stream is Live, set the isLive variable to true.

       //MM2
       public void startMediaMelonSDK(){
            //MM2A
            .......
            //MM2A
            
            //MM2B
            //PROVIDE THE VIDEO ASSET INFORMATION HERE
            JSONObject mVideoAssetInfo = new JSONObject();
            try {
                 mVideoAssetInfo.put("assetName","SampleAsset");
                 mVideoAssetInfo.put("assetId","0001") ;
                 mVideoAssetInfo.put("videoId","0002") ;
                 mVideoAssetInfo.put("contentType","contentType");
                 mVideoAssetInfo.put("drmProtection","drm");
                 mVideoAssetInfo.put("episodeNumber","episode");
                 mVideoAssetInfo.put("genre","genre");
                 mVideoAssetInfo.put("seriesTitle","series");
                 mVideoAssetInfo.put("season","season");
                 mVideoAssetInfo.put("videoType","video");

                 //For CustomTags
                 JSONObject customTags = new JSONObject();
                 customTags.put("ABC","123");
                 customTags.put("DEF","456");
     
                 mVideoAssetInfo.put("customTags", customTags);
     
             } catch (JSONException e) {
                 // TODO Auto-generated catch block
                 e.printStackTrace();
             }
            // mMyUri - Media URL
            //$ISLIVE - FOR LIVE STREAMS TRUE ELSE FALSE
             mmVoPlayerAdapter.initializeSession(mMyVOPlayer, mMyUri,mVideoAssetInfo,$ISLIVE);
             
             // vastURL - URL for VAST
            // vodResponseData - 
            // isLive(third parameter) - True for Live streams and false for VOD
            // The last parameter setupNowtilusAdManager enablePollingforSSAI is alsways
            
             mmVoPlayerAdapter.setupNowtilusAdManager(mMyUri, vastURL,vodResponseData, true, true);
             
             mmVoPlayerAdapter.reportUserInitiatedPlayback();
            //MM2B
       
       }
       //MM2
       
  

STEP 4

Subscribe to AD EVENTS in startMediaMelonSDK() API. Please refer code block below

//MM2
public void startMediaMelonSDK(){
    
     //MM2A
        ......
     //MM2A
     
            
     //MM2B
        .......
     //MM2B     
     
     //MM2C    
        // Subscribe to AD EVENTS
        MMSSAIEventsListeners mmssaiEventsListeners = new MMSSAIEventsListeners() {
            @Override
            public void onAdImpression(mmAd ssaiAdInfo) {
                Log.d("APP SSAI", "onAdImpression:" + ssaiAdInfo.adId);
            }

            @Override
            public void onAdComplete(mmAd ssaiAdInfo) {
                Log.d("APP SSAI", "onAdComplete:" + ssaiAdInfo.adId);
            }

            @Override
            public void onCueTimelineAdded(mmAdTimelineInfo timelineInfo) {
                Log.d("APP SSAI", "onCueTimelineAdded totalAds: " + timelineInfo.totalAds);
            }

            @Override
            public void onCueTimelineEnter(mmAd ssaiAdInfo) {
                Log.d("APP SSAI", "onCueTimelineEnter:" + ssaiAdInfo.adId);
            }

            @Override
            public void onCueTimelineExit(mmAd ssaiAdInfo) {
                Log.d("APP SSAI", "onCueTimelineExit:" + ssaiAdInfo.adId);
            }
        };
        mmVoPlayerAdapter.getSSAIAdManager().addListener(mmssaiEventsListeners);
    //MM2C
}
//MM2

STEP 5

ADD API for stopping MediaMelon SDK.To stop MediaMelon SDK please call stopMediaMelonSDK(). Please refer code block below

    //MM3
        public void stopMediaMelonSDK(){
           if(sdkIntegration) mmVoPlayerAdapter.closeMediaMelonSDK(); 
        }
    //MM3

STEP 6 : To Stop the SSAI Ad Manager

Report the player state has ENDED, when the player was destroyed

ADD closeSSAIAdManager() API in onDestroy() listener in CustomPlayerActivity.java

@Override
protected void onDestroy() {
    
    //MM4
    this.mmSmartStreamingNowtilusSSAIPlugin.closeSSAIAdManager(); // Added for stopping VastInfo after player destroyed
    
    //...........

}

List of AD EVENTS

onAdImpression
onAdStarted
onAdFirstQuartile
onAdMidpoint
onAdThirdQuartile
onAdProgress
onAdComplete
onCueTimelineAdded 
onCueTimelineEnter
onCueTimelineExit

Event Callback	Description
onAdImpression	Fired when an Ad Impression occurs
onAdStarted	Fired when Ad starts playing
onAdFirstQuartile	Fired when Ad playback reaches the First Quartile point
onAdMidpoint	Fired when Ad playback reaches the Midpoint
onAdThirdQuartile	Fired when Ad playback reaches the Third Quartile point
onAdProgress	Fired every second during Ad Playback, used to track Ad Playback progress
onAdComplete	Fired when Ad Playback completes
onCueTimelineAdded	Fired when an Ad break information gets added
onCueTimelineEnter	Fired when an Ad break ( which can contain multiple Ads) starts
onCueTimeLineExit	Fired when an Ad break ( which can contain multiple Ads) ends

Get Ad Related Information

You can use the below commands from inside any of the AD Events(listed above) that you subscribe to.

1. ssaiAdInfo.getTotalAds()- returns a int which signifies the number of Ads in the current Ad break.

2. ssaiAdInfo.getClickTrackingURLs()-returns the click tracking URLs as a List<String>.

3. ssaiAdInfo.getClickThroughURLs() -returns the clickthrough URLs as a List<String>.

4. ssaiAdInfo.getAdSkipOffset()- returns the AD offset in seconds.

5. ssaiAdInfo.getCompleteTrackers() - returns the AD Complete Tracking URLs as a List<String>.

6. ssaiAdInfo.getMidpointTrackers() - returns the AD Midpoint Tracking URLs as a List<String>.

7. ssaiAdInfo.getThirdQuartileTrackers() - returns the AD ThirdQuartile Tracking URLs as a List<String>.

8. ssaiAdInfo.getFirstQuartileTrackers() - returns the AD FirstQuartile Tracking URLs as a List<String>.

9. ssaiAdInfo.getImpressionTrackers() - returns the AD Impression URLs as a List<String>.

10. ssaiAdInfo.getAdIndex() - returns the index of the current AD in the AD break.

11. ssaiAdInfo.getStartPos() - returns the start position of the Ad Break relative to the first manifest program time

12. ssaiAdInfo.getEndPos() - returns the end position of the Ad Break relative to the first manifest program time