Skip to main content

Bitmovin (Android)

The guide shows how to integrate Bitmovin 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
val player = PlayerBuilder(this)
    .setPlayerConfig(PlayerConfig(key = "<LICENCE_KEY>"))
    .build()
    
val playerView = findViewById(R.id.player_view)
playerView.player = player

// Attach your player to the current session
session.attachPlayer(player)

// Set the ad view
var contentFrame = playerView.findViewById<AspectRatioFrameLayout>(R.id.bmp_content_frame)
session.setAdView(contentFrame)

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 default ad view state before starting the playback
session.setAdViewState(AdViewState.NORMAL) // AdViewState.NORMAL or any other values

...

// Starting the playback
...

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

3. Register an ad friendly obstruction​

After setting the ad view instance and before starting the playback, register ad friendly obstruction views if any.

// Default Bitmovin UI elements
var adContainer = playerView.findViewById<FrameLayout>(R.id.ad_container)
var posterImage = playerView.findViewById<AppCompatImageView>(R.id.poster_image)
var webView: WebView? = playerView.children.firstOrNull { it is WebView } as? WebView
session.registerAdFriendlyObstructionView(
    adContainer,
    AdFriendlyObstructionPurpose.OTHER,
    "adContainer"
)

session.registerAdFriendlyObstructionView(
    posterImage,
    AdFriendlyObstructionPurpose.OTHER,
    "posterImage"
)

session.registerAdFriendlyObstructionView(
    webView,
    AdFriendlyObstructionPurpose.VIDEO_CONTROLS,
    "webView"
)

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
// The user interacts with the ad
session.adUserInteraction(AdInteractionType.CLICK)

5. Update last activity (Android TV only)​

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 Engine (aka MME). You can also add additional ad verification data through a method. It has to be called before starting the playback.

// Register ad verification data
session.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
session.setAdCustomReference("MyCustomReferenceData")

...

// Starting the playback
...

Full example​

// Init SmartLib
SmartLib.getInstance().init(this, "", "", "<your_broadpeak_domain_names>")
Omid.updateLastActivity()

// Create your player
val player = PlayerBuilder(this)
    .setPlayerConfig(PlayerConfig(key = "<LICENCE_KEY>"))
    .build()
    
val playerView = findViewById(R.id.player_view)
playerView.player = player

// Default Bitmovin UI elements
var contentFrame = playerView.findViewById<AspectRatioFrameLayout>(R.id.bmp_content_frame)
var adContainer = playerView.findViewById<FrameLayout>(R.id.ad_container)
var posterImage = playerView.findViewById<AppCompatImageView>(R.id.poster_image)
var webView: WebView? = playerView.children.firstOrNull { it is WebView } as? WebView

// Create SmartLib session
session = SmartLib.getInstance().createStreamingSession()

// Attach the player
session.attachPlayer(player)

// Ad session
session.activateAdvertising()
session.setAdView(contentFrame)
session.setAdViewState(AdViewState.NORMAL)
session.setAdCustomReference("MyCustomReferenceData") // Optional
session.registerAdVerificationData(
    "https://myserver/omsdk-files/omid-validation-verification-script.js", 
    "samplevendor", 
    "sampleparam"
) // Optional

// Register UI elements as friendly obstructions
session.registerAdFriendlyObstructionView(
    adContainer,
    AdFriendlyObstructionPurpose.OTHER,
    "adContainer"
)

session.registerAdFriendlyObstructionView(
    posterImage,
    AdFriendlyObstructionPurpose.OTHER,
    "posterImage"
)

session.registerAdFriendlyObstructionView(
    webView,
    AdFriendlyObstructionPurpose.VIDEO_CONTROLS,
    "webView"
)

// Get URL
Executors.newSingleThreadExecutor().submit {
    val result = session.getURL("<your_streaming_url>")
    if (!result.isError) {
        val sourceConfig = SourceConfig.fromUrl(result.url)
        val source = Source(sourceConfig)
        player.load(source)
        player.play()
    }
}