Nowtilus Android Demo App Documentation

This document guides in using the Nowtilus Android Demo App.

Home Screen

In the home screen, the SSAI URL should be provided in the allocated text box. If it is a live stream, switch on the live button and click on the play button to load the media. If it is a VOD, switch off the live button and click on the play button to load the media. Once you click on the play button, screen 2 will appear where we can see the video player and ad information.

Player Screen

This screen contains the four different views as shown in the image.

1. The first view on the top contains the ad tracking information like tracking urls.

2. The second view in the middle of the screen contains the AV Player and its player controls.

3. The third view contains the functionalities like Ad Ends in, Click Ad and Skip Ad. In this, Ad Ends in text view shows the ad remaining time in seconds. As the ad progresses, the time reduces and the timer will get to 0 when the ad ends. Click Ad is a button which when clicked will redirect the user to safari browser and it opens the Ad Click Through url of that ad. Skip Ad button helps to skip the ads in VOD streams. This button will be enabled after First Quartile from the ad start. Currently this functionality is disabled for live streams.

4. The fourth view contains the current playing ad information like Ad Event, Ad Number, Ad Title and Ad ID.

List of Ad Events:

adCueTimelineAdded

adCueTimelineStart

adImpression

adStarted

adFirstQuartile

adMidpoint

adThirdQuartile

adComplete

adCueTimelineEnd

Stream URL Types

Live:

This app can handle multiple live URLs like - View, Master.m3u8 and Audio only. Based on the input URL given, the app will internally classify the URL and fetch the data accordingly.

Sample Live Stream URLs:

View: https://live.serverside.ai/hls/view/7a188add-300e-47cc-934f-aa2f0e2beb6a?api-key=e62ae75a-60d5-45b7-a171-27c9c6d29a9d

Master.m3u8:http://audio.enfqb0aqbtg3cwet.germanywestcentral.azurecontainer.io:3001/hls/master.m3u8

VOD:

A curl request to the VOD URL will be made and response of this request will be passed to the MediaMelon SDK for Ad detection.

Sample VOD Stream URL: https://live.serverside.ai/vod-proxy/hls/view/c1c73566-a98d-42a5-b2ad-c1c3b2d42f88?api-key=bbfd3d9c-9726-454f-b71b-d34fcafa6205&ssai-markers=0%2C2%2C30%3B120%2C2%2C30&ssai-content=https%3A%2F%2Fssaimediaservices-euwe.streaming.media.azure.net/62ec1234-fcf0-47d5-a4d4-ae463827dcfc/Cosmo_Laundromat.ism/manifest(format=m3u8-aapl-v3)

HTTP Header Fields for VOD

In the getURLDetails function, HTTP header fields should be provided for the VOD streams. As it is a POST request, along with the headers, HTTP request body should also be provided here as shown in the below code snippet.

        //HEADERS
        httpURLConnection.setRequestProperty("api-key","f69d10e4-33cd-472a-bc0d-b45939370818");
        httpURLConnection.setRequestProperty("Content-Type", "application/json");
        httpURLConnection.setRequestProperty("User-Agent","Mozilla/5.0%20(Linux;%20Android%208.1.0;%20CPH1809)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/79.0.3945.93%20Mobile%20Safari/537.36");
        httpURLConnection.setRequestProperty("Authorization","Basic bm93dGlsdXM6bm93dGlsdXM=");
        
        //raw data
        String data = "{\n  \"url\": \"https://serversideai.blob.core.windows.net/agsmrss/serverside/serverside_mrss_preroll_midroll.mrss\",\n  \"context\": \"web\",\n  \"ifa\": \"ifa\",\n    \"deliverytypes\": [\n    \"dash\"\n    ]\n}";

UI Elements

This section helps in understanding how the screen layouts are arranged for modifications.

Home Screen

Layout of this screen is called as sample_chooser_activity.xml , it was present in res folder, inside the layout folder . The layout of the screen looks like below:

In addition to the above layout, in the sample_chooser_activity.xml file, labels for Title, Version, URL Title and Live Text are added. The positioning and the fit of all these elements are handled in the this file. OnClick action for the play button is also handled in this file. In this onClick action, stream url and isLive variables will be assigned with the values taken from the user.

Player Screen

Layout of this screen is called as player_activity.xml file, present inside layout folder of res folder. The layout of the screen looks like below:

Inside the main view of this screen, total 4 individual views are added as shown in the above image. Positions and arrangements of all these views and elements are handled in this file.

Ad Events Info

Ad events info is being assigned to the UI inside the showAdEvents showAdInfo showTrackingURLs function of this file.

// Updating UI in the player screen for ad events
//SHOWING AD EVENTS ON UI
  public void showAdEvents(String msg){
    //adEventsView.setText(msg);
    Handler handler = new Handler(Looper.getMainLooper());
    handler.post(new Runnable() {
      @Override
      public void run() {
        adEventsView.setText(msg);
      }
    });
  }

  // FOR SHOWING AD INFORMATION ON UI
  public void showAdInfo(String msg1,String msg2,String msg3){

    Handler handler = new Handler(Looper.getMainLooper());
    handler.post(new Runnable() {
      @Override
      public void run() {
        adInfo3.setText(msg1); //shows AD ID
        adInfo4.setText(msg2); //Shoes AD Title
        adNum.setText(msg3); // shows ad Number
      }
    });

  }

  // FOR DISPLAYING TRACKING URLS ON UI
  public void showTrackingURLs(List<String> trackingURLs,boolean check){

    String tracking = "";
    if(trackingURLs!=null) {
      for (int i = 0; i < trackingURLs.size(); i++) {
        tracking += "--> ";
        tracking += trackingURLs.get(i);
        tracking += "\n\n";
      }
    }
    Handler handler = new Handler(Looper.getMainLooper());
    String finalTracking = tracking;

    handler.post(new Runnable() {
      @Override
      public void run() {
        if(check) {
          adInfo1.setText("");
        }
        else{
          adInfo1.setText(finalTracking);
        }
      }
    });

  }

// Updating UI in the player screen for ad events

Handling Click Ad Button

In this, Ad Click Through url is fetched from the SSAIAdManger and the same will be opened in the safari browser. The player will be paused when user clicked on the button and the player should resume manually when user came back to the application from browser.

At the same time, when user clicked on the Ad, adClickTrackingUrls will be fired from the SSAIAdManger.

// Fetching the click through url from the ad data
List<String> clickThrough = mmAd.getClickThroughURLs(); // fetching click through url from mmAd obj
        clickTracking = mmAd.getClickTrackingURLs(); // fetching click tracking url from mmAd obj

        if(clickThrough.size() > 0) {
          //make button visible
          click.setVisibility(View.VISIBLE);
          clickUrl = clickThrough.get(0); //storing the click through url in clickUrl variable
        }
// Fetching the click through url from the ad data

// Ad click button implementation
click.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View view) {
      player.setPlayWhenReady(false); // pausing the player when click through was clicked

      //Firing click tracking url when click through link was clicked
      nowtilusSSAIPlugin.fireTrackingUrl("ClickTrackingUrl",clickTracking);

      // redirecting to click through url in browser
      Uri uri = Uri.parse(clickUrl);
      Intent intent = new Intent(Intent.ACTION_VIEW, uri);
      startActivity(intent);
    }
  });
// Ad click button implementation

Handling Skip Ad Button

The skip ad button will be enabled after first quartile of the Ad Start for VOD streams. This button is disabled for live streams as of now.

// Ad Skip Enabling after First quartile only for VOD
@Override
      public void onAdFirstQuartile(mmAd mmAd) {
        Log.i("MM","**onAdFirstQuartile**");
        if(!isLiveStream) skip.setVisibility(View.VISIBLE);
      }

// Ad Skip Enabling after 5sec only for VOD

// Ad skip button implementation
skip.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View view) {
      player.seekTo(endTime-50);
      skip.setVisibility(View.INVISIBLE); // after skip  making button invisible
    }
  });
// Ad skip button implementation

Handling Ad Remaining Time TextView

Ad remaining time is calculated as the difference between adEndTime and pbTime. The function named onAdTime will be called 2 times in every second from the SSAIAdManger using delegates to update the ad remaining time.

// This callback updates the ad reamaining time continuously
@Override
      public void onAdTime(long pbTime, long adEndTime) {
        Handler handler = new Handler(Looper.getMainLooper());
        handler.post(new Runnable() {
          @Override
          public void run() {
            int min = (int) 0;
            int sec = (int) ((adEndTime-pbTime)/1000);
            String timeLeft = String.format(Locale.getDefault(),"%02d:%02d",min,sec);
            countDown.setText(timeLeft);
          }
        });