Register friendly obstructions (iOS)

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



If you 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 JWAdvertisingConfig 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. Create a FriendlyObstruction object, passing a reference to the view that you want to mark as a friendly obstruction.
  2. Use the created FriendlyObstruction object to create a FriendlyObstructionContainer.
  3. Set the friendly obstruction container on the JWImaAdvertisingConfigBuilder using the friendlyObstructionsContainer(_ container: FriendlyObstructionsContainer) function.
  4. Call build() on the JWImaAdvertisingConfigBuilder.

// Have a reference to the view you want to register as a friendly obstruction.
@IBOutlet weak var fullScreenButton: UIButton?

// Create a JWFriendlyObstruction object using the view you
// want to register.
let friendlyObstruction = JWFriendlyObstruction(view: fullScreenButton, purpose: .mediaControls)

// Create a JWFriendlyObstructionContainer using the 
// created JWFriendlyObstruction
let friendlyObstructionContainer = JWFriendlyObstructionContainer([friendlyObstruction])

// Create a JWImaAdvertisingConfigBuilder and set the JWFriendlyObstructionContainer.
let builder = JWImaAdvertisingConfigBuilder()
              .tag(URL(string: <#Tag URL#>)!)
              .friendlyObstructionContainer(friendlyObstructionContainer)

// Create a JWAdvertisingConfig using the builder.
do {
    let config = try builder.build()
    // Use the config to create a JWPlayerConfiguration
} catch is JWError {
    // Handle the error
}
// Have a reference to the view you want to register as a friendly
// obstruction.
UIButton *fullScreenButton = [[UIButton alloc] initWithFrame:CGRectZero];

// Create a JWFriendlyObstruction object using the view you
// want to register.
JWFriendlyObstruction *obstruction = [[JWFriendlyObstruction alloc] initWithView:fullScreenButton purpose:JWFriendlyObstructionPurposeMediaControls reason:@”Reason”];

// Create a JWFriendlyObstructionContainer using the 
// created JWFriendlyObstruction
JWFriendlyObstructionContainer *container = [[JWFriendlyObstructionContainer alloc] init:@[obstruction]];

// Create a JWImaAdvertisingConfigBuilder and set the JWFriendlyObstructionContainer.
JWError *error;
JWImaAdvertisingConfigBuilder *builder = [[JWImaAdvertisingConfigBuilder alloc] init];
[builder tag: [NSURL URLWithString: @"http://testurl.com"]];
[builder adRules:rules];
[builder friendlyObstructionsContainer:container];
JWAdvertisingConfig *adConfig = [builder buildAndReturnError:&error];