Register custom video controls (Android v3)

Register custom controls as friendly obstructions when using OMID with Google IMA ads in your Android app.


Rather than relying on the default UI, you may choose to implement custom UI controls by wiring up native controls to the player API -- such as having a Button with an ⏯ image call play(). See our Best Practice App target DemoNativeControls for an example implementation of this.

If you also use the IAB Open Measurement Interface Definition (OMID) and run Google IMA ads, all custom video controls that overlay the media element must be registered as friendly obstructions. Friendly obstructions are views -- such as video controls -- that are essential to the user’s experience but do not impact viewability.

The JWFriendlyAdObstructions class enables you to register fully transparent overlays or small buttons. Once registered, your custom video controls are excluded from the ad viewability measurements that the Open Measurement SDK calculates.

The following table lists the views that can and cannot be registered.

PermittedNot permitted
β€’ Transparent overlay used to capture user taps
β€’ Transient buttons such as the following:
Β Β Β β—¦ Pause
Β Β Β β—¦ Play
Β Β Β β—¦ Fullscreen
Β Β Β β—¦ Cast/AirPlay
Β Β Β β—¦ Collapse
Β Β Β β—¦ Progress/Seek
Β Β Β β—¦ Other playback-related actions
β€’ Watermarks
β€’ Pop-ups
β€’ Dialogs
β€’ Non-transient buttons
β€’ Other obscuring views


Register a custom control

Use the following steps and code sample to register a custom video control as a friendly ad obstruction:

  1. Add the custom view, for example customControlbar, to your app.
  2. Use getJWFriendlyAdObstructions() to get a reference to the list of friendly ad obstructions.
  3. Add the custom view to the JWFriendlyAdObstructions list.
mPlayerView = findViewById(R.id.jwplayer);
View customControlbar = findViewById(R.id.custom_controlbar);

// Add our custom controlbar to the list of friendly ad obstructions
friendlyAdObstructions = mPlayerView.getJWFriendlyAdObstructions();
friendlyAdObstructions.add(customControlbar);

List<AdBreak> adSchedule = new ArrayList<>();

AdBreak adBreak = new AdBreak.Builder()
    .tag("https://www.domain.com/adtag.xml")
    .build();
        
adSchedule.add(adBreak);

ImaAdvertising imaAdvertising = new ImaAdvertising(AdSource.IMA, adSchedule);

PlaylistItem playlistItem = new PlaylistItem.Builder()
    .file("https://cdn.jwplayer.com/manifests/{media_id}.m3u8")
    .build();

List<PlaylistItem> playlist = new ArrayList<>();
playlist.add(playlistItem);

PlayerConfig config = new PlayerConfig.Builder()
    .playlist(playlist)
    .advertising(imaAdvertising)
    .build();

mPlayerView.setup(config);