Skip to main content

ExoPlayer / Media3

The guide shows how to integrate ExoPlayer / Media3 with SmartLib in order to handle ad tracking with the OM SDK enabled. Before starting, you need to have done the OM SDK integration guide.

At this point, you should have initialized the lib, created a streaming session object and have integrated the session lifecycle with the ad tracking into your app.

Requirements

1. Set the ad view instance​

When creating the player instance, attach the content frame to the current session before starting the session (i.e before calling getURL).

// Create your player
mPlayer = new ExoPlayer.Builder(this).build();

// Get the global player view
mPlayerView = findViewById(R.id.player_view);

// Get the player content frame
mPlayerViewContent = mPlayerView.findViewById(R.id.exo_content_frame);

// Set the ad view
mSession.setAdView(mPlayerViewContent);

2. Set the ad view state​

After setting the ad view instance, set the first ad view state (i.e the state of the ad view before starting the playback). The ad view state can use these values:

  • AdViewState.NORMAL: player normal state (default state)
  • AdViewState.MINIMIZED: player minimized state (not visible)
  • AdViewState.COLLAPSED: player collapsed state (view reduced)
  • AdViewState.EXPANDED: player expanded state (view expanded)
  • AdViewState.FULLSCREEN: player fullscreen state (fullscreen view)
info

Once the playback started, the ad view state can be updated if the ad view state has been changed.

// Set the ad view
mSession.setAdView(mPlayerViewContent);

...

// Set the default ad view state before starting the playback
mSession.setAdViewState(AdViewState.NORMAL); // AdViewState.NORMAL or any other values

...

// Starting the playback
...

// After an user action that changed the ad view state
mSession.setAdViewState(...);

3. Register an ad friendly obstruction​

If you need to add an overlay with controls that should not be counted as an obstruction, these views have to be registered.

/**
 * Register an ad friendly obstruction view (OMSDK)
 * @param view view
 * @param purpose purpose
 * @param reason reason as string
 */
public void registerAdFriendlyObstructionView(View view, AdFriendlyObstructionPurpose purpose, String reason);

/**
 * Unregister ad friendly obstruction view (OMSDK)
 * @param view view
 */
public void unregisterFriendlyObstruction(View view);

/**
 * Unregister all ad friendly obstruction views (OMSDK)
 */
public void unregisterAllFriendlyObstructions();
public enum AdFriendlyObstructionPurpose {
    /**
     * Video controls view friendly obstruction
     */
    VIDEO_CONTROLS,

    /**
     * Close ad view friendly obstruction
     */
    CLOSE_AD,

    /**
     * Not visible view friendly obstruction
     */
    NOT_VISIBLE,

    /**
     * Other view friendly obstruction
     */
    OTHER
}

After setting the ad view instance and before starting the playback, register ad friendly obstruction views. If you are using the exoplayer-ui module, add the default obstruction views:

// Set the ad view
mSession.setAdView(mPlayerViewContent);

...

// Default ExoPlayer IU (if you are using the exoplayer-ui module)
mSession.registerAdFriendlyObstructionView(mPlayerView.findViewById(R.id.exo_ad_overlay), AdFriendlyObstructionPurpose.OTHER, "adoverlay");
mSession.registerAdFriendlyObstructionView(mPlayerView.findViewById(R.id.exo_overlay), AdFriendlyObstructionPurpose.OTHER, "appoverlay");
mSession.registerAdFriendlyObstructionView(mPlayerView.findViewById(R.id.exo_controller), AdFriendlyObstructionPurpose.VIDEO_CONTROLS, "controls");

// Register your own ad friendly obstruction view
mSession.registerAdFriendlyObstructionView(mPlayerView.findViewById(...), ..., "...");
...

4. Trigger an ad user interaction​

Once the playback started, the user can interact with the ad:

  • AdInteractionType.CLICK: ad user click interaction type
  • AdInteractionType.INVITATION_ACCEPTED: ad user invitation accept interaction type
// Starting the playback
...

// The user interacts with the ad
mSession.adUserInteraction(AdInteractionType.CLICK);

5. Update last activity​

The app has to signal to the OM SDK when a user interacts with the app via manuel input (play, pause...):

Omid.updateLastActivity();

Find more details on the IAB documentation.

6. Advanced features​

These optional methods could help you to enhance your ad experience.

Register an ad verification data​

Ad verification data are usually defined on your ad provider console and forwarded to the app through the manifest manipulator (BkYou). You can also add additional ad verification data through a method. It has to be called before starting the playback.

/**
 * Register an ad verification data url with parameters (OMSDK)
 * @param url url
 * @param vendor vendor
 * @param parameters parameters
 */
public void registerAdVerificationData(String url, String vendor, String parameters);
// Register ad verification data
mSession.registerAdVerificationData("https://myserver/omsdk-files/omid-validation-verification-script.js", "samplevendor", "sampleparam");

...

// Starting the playback
...
note

You can perform a test by configuring a local web server. Find more details on the OM SDK validation documentation.

Set the ad custom reference​

When the OM SDK ad session context is initialized, a custom reference data can be passed. It has to be called before starting the playback.

/**
 * Set ad custom reference data (OMSDK)
 * @param reference reference
 */
public void setAdCustomReference(String reference);
// Set ad custom reference data
mSession.setAdCustomReference("MyCustomReferenceData");

...

// Starting the playback
...