Enable Open Measurement

Enable third-party viewability, verification measurement, and vendor restrictions through the Open Measurement Interface Definition.


The iOS SDK includes the Open Measurement (OM) SDK. By default, the Open Measurement functionality is disabled. When enabled, the OM SDK supports several ad-related features for VAST ads:

  • Third-party viewability
  • Verification measurement
  • Vendor restrictions

📘

TIP

If instead you are interested in utilizing the OM SDK for use with Google IMA, please refer to the documentation on Open Measurement in the Google IMA SDK.



Requirements

ItemNotes
JWPlayerKit4.1.0+
Google IMA SDK3.9.0+
Ads configured to traffic
AdVerifications in their VAST
•   <AdVerifications> VAST 4.1+
•   <Extension type="AdVerifications"> < VAST 4.1


Enable Open Measurement

👍

IMPORTANT

Refrain from covering the JWPlayerView with any overlays (transparent or opaque). These will be flagged as obstructions by the OM SDK and reduce viewability.


Use the following steps to enable the Open Measurement functionality:

  1. (Optional) Create an array of vendors allowed to execute scripts within the AdVerifications. If a verification script from an unauthorized vendor is found within an ad, the verificationNotExecuted script will be executed for the ad as per Open Measurement’s standard. If not defined, all vendors are assumed to be approved.
  2. Use JWOMIDConfigBuilder() to create an Open Measurement config, JWOMIDConfig. If defined in the previous step, be sure to pass the array of vendor allowed to execute scripts.
  3. Use JWPlayerConfigurationBuilder() to add the JWOMIDConfig to the player config.
do {
     // Create a JW Player VAST ad config
     let adConfig = try JWAdsAdvertisingConfigBuilder()
          .tag(URL(string: "ad_tag_url")!)
          .build()
            
     // Create an Open Measurement config
     let vendors: [String] = [
          "allowed.vendor.01", 
          "allowed.vendor.02"
     ]
     let omidConfig = try JWOMIDConfigBuilder()
          .allowedVendors(vendors)
          .build() 
            
     // Create a player item
     let item = try JWPlayerItemBuilder()
          .file(URL(string: "video_url")!)
          .build()
            
     // Initialize the JWPlayerConfiguration
     let config = try JWPlayerConfigurationBuilder()
          .playlist([item])
          .advertising(adConfig)
          .adTracker(omidConfig)
          .build()
            
     // Configure the player
     player.configurePlayer(with: config)
}
catch {
     // Handle errors
}
// Create a JW Player VAST ad config
    NSError *error = nil;
    JWAdvertisingConfig *adConfig = [[[JWAdsAdvertisingConfigBuilder new]
                                         tag: [NSURL URLWithString:@"ad_tag_url"]]
                                     buildAndReturnError:&error];
    if (error != nil) {
        // Handle error
    }
    
    // Create an Open Measurement config
    NSArray *vendors = @[@"allowed.vendor.01",
                         @"allowed.vendor.02"];
    JWOMIDConfig *omidConfig = [[[JWOMIDConfigBuilder new]
                                 allowedVendors:vendors]
                                buildAndReturnError:&error];
    
    if (error != nil) {
        // Handle error
    } 
    
    // Create a player item
    JWPlayerItem *item = [[[JWPlayerItemBuilder new]
                           file:[NSURL URLWithString:@"video_url"]]
                          buildAndReturnError:&error];
    
    if (error != nil) {
        // Handle Error
    }
    
    // Initialize the JWPlayerConfiguration
    JWPlayerConfiguration *config = [[[[[JWPlayerConfigurationBuilder new]
                                        playlist:@[item]]
                                       advertising:adConfig]
                                      adTracker:omidConfig]
                                     buildAndReturnError:&error];
    
    if (error != nil) {
        // Handle error
    }
    
    // Configure the player
    [player configurePlayerWith:config];


Manage friendly obstructions

If you use JWPlayerViewController, friendly obstructions within the interface are reported and handled. However, if you do not use JWPlayerViewController or want to prevent other UIViews from affecting ad viewability, you should register these obstructions as friendly.

The following examples apply to JW Player VAST and Google IMA/DAI ad clients.


Register a friendly obstruction

  1. Create a list of one or more JWFriendlyObstruction. Be sure to supply the purpose (using predefined constants) and the reason the obstruction is friendly.
let playButton = UIButton() // Assume this is a UIButton you have a reference to
        let countdownLabel = UILabel() // Assume this is a UILabel you have a reference to
        let obstructions = [
        JWFriendlyObstruction(view: playButton, purpose: .mediaControls, reason: "Play button"),
        JWFriendlyObstruction(view: countdownLabel, purpose: .other, reason: "Ad countdown")
    ]
UIButton *playButton = [UIButton new];
    UILabel *countdownLabel = [UILabel new];
    NSArray *obstructions = @[
        [[JWFriendlyObstruction alloc] initWithView:playButton purpose:JWFriendlyObstructionPurposeMediaControls reason:@"Play button"],
        [[JWFriendlyObstruction alloc] initWithView:countdownLabel purpose:JWFriendlyObstructionPurposeOther reason:@"Ad countdown"]
    ];
  1. Use func register(_ obstructions: [JWFriendlyObstruction]) to register the obstructions with the player.
player.friendlyObstructions.register(obstructions)
[player.friendlyObstructions register:obstructions];


Deregister a friendly obstruction

To deregister friendly obstructions, use one of the following approaches:

  • Deregister a defined list of friendly obstructions when calling func register(_ obstructions: [JWFriendlyObstruction])
player.friendlyObstructions.deregister(obstructions)
[player.friendlyObstructions deregister:obstructions];
  • Deregister all registered JWFriendlyObstruction objects.
player.friendlyObstructions.deregisterAllObstructions()
[player.friendlyObstructions deregisterAllObstructions];


Did this page help you?