Schedule Google IMA ads (iOS)

After adding the Google IMA SDK to your app and acquiring the required items listed in the Requirements section, you can schedule Google IMA ads in your iOS app.

Requirements

Scheduling Ad Breaks

Add a pre-roll ad to a player

👍
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.

Use the following steps to add a pre-roll ad to the player you added to your view:

Use JWAdBreakBuilder() to instantiate a JWAdBreak object. The JWAdBreak object defines the ad tag and the pre-roll offset.

The ad tag can include ad pods and have custom parameters appended to the URL.
📘
If the ad tag you are using is a VAST VMAP file, follow the steps to Schedule ads using a VMAP file.

Use JWImaAdvertisingConfigBuilder() and the JWAdBreak to instantiate a JWImaAdvertisingConfig. This object creates an IMA configuration to play a pre-roll ad.

Use JWPlayerConfigurationBuilder() to instantiate a JWPlayerConfiguration that associates the JWImaAdvertisingConfig with the player.

class ViewController: JWPlayerViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create the ad break
        let adBreakBuilder = JWAdBreakBuilder()
            .offset(.preroll())
            .tags([URL(string: <#Video URL String#>)!])
        guard let adBreak = try? adBreakBuilder.build() else {
            // Handle build error
            return
        }

        // Create the ad config
        let adConfigBuilder = JWImaAdvertisingConfigBuilder()
        .schedule([adBreak])
        guard let adConfig = try? adConfigBuilder.build() else {
            // Handle build error
            return
        }

        
        // Create player item
        let itemBuilder = JWPlayerItemBuilder()
        .file(URL(string: <#Video URL String#>)!)
        guard let playerItem = try? itemBuilder.build() else {
            // Handle build error
            return
        }

        let configBuilder = JWPlayerConfigurationBuilder()
        .playlist([playerItem])
        .advertising(adConfig)
        guard let config = try? configBuilder.build() else {
            // Handle build error
            return
        }

        // Set the config
        player.configurePlayer(with: config)
    }
}

@implementation ObjCViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // Create the Ad Break
    JWError *breakError;
    JWAdBreakBuilder *breakBuilder = [[JWAdBreakBuilder alloc] init];
    [breakBuilder tags: @[[NSURL URLWithString:@<#Video URL String#>]]];
    JWAdOffset *offset = [JWAdOffset preroll];
    [breakBuilder offset: offset];
    JWAdBreak *adBreak = [breakBuilder buildAndReturnError:&breakError];
    if (breakError != nil ) {
        // Handle error
    }

    JWError *adConfigError;
    JWImaAdvertisingConfigBuilder *adConfigBuilder = [[JWImaAdvertisingConfigBuilder alloc] init];
    [adConfigBuilder schedule:@[adBreak]];
    JWAdvertisingConfig *adConfig = [adConfigBuilder buildAndReturnError:&adConfigError];
    if (adConfigError != nil) {
        // Handle error
    }

    JWError *playerItemError;
    JWPlayerItemBuilder *playerItemBuilder = [[JWPlayerItemBuilder alloc] init];
    [playerItemBuilder file:[NSURL URLWithString:@<#Video URL String#>]];
    JWPlayerItem *playerItem = [playerItemBuilder buildAndReturnError:&playerItemError];
    if (playerItemError != nil) {
        // Handle error
    }

    JWError *configError;
    JWPlayerConfigurationBuilder *configBuilder = [[JWPlayerConfigurationBuilder alloc] init];
    [configBuilder playlist:@[item]];
    [configBuilder advertising:adConfig];
    JWPlayerConfiguration *config = [configBuilder buildAndReturnError:&configError];
    if (configError != nil) {
        // Handle error
    }

    // Set the config
    [self.player configurePlayer:config];
}

Add multiple ad breaks to a player

Use the following steps to add multiple ad breaks to the previous VAST pre-roll example:

Use JWAdBreakBuilder() to instantiate another JWAdBreak object.
Add the additional JWAdBreak to the schedule array of JWImaAdvertisingConfig().

// // Create a pre-roll ad break
        let adBreakBuilder1 = JWAdBreakBuilder()
            .offset(.preroll())
 n            .tags([URL(string: <#Video URL String#>)!])
        guard let adBreak1 = try? adBreakBuilder1.build() else {
            // Handle build error
            return
        }

        // Create an ad break for 30% into the video
        let adBreakBuilder2 = JWAdBreakBuilder()
            .offset(.percent(30))
            .tags([URL(string: <#Video URL String#>)!])
        guard let adBreak2 = try? adBreakBuilder2.build() else {
            // Handle build error
            return
        }

        // Create the ad config
        let adConfigBuilder = JWImaAdvertisingConfigBuilder()
        .schedule([adBreak1, adBreak2])
        guard let adConfig = try? adConfigBuilder.build() else {
            // Handle build error
            return
        }

// Create a pre-roll ad break
    JWError *breakError1;
    JWAdBreakBuilder *breakBuilder1 = [[JWAdBreakBuilder alloc] init];
    [breakBuilder1 tags: @[[NSURL URLWithString:@<#Video URL String#>]]];
    JWAdOffset *offset1 = [JWAdOffset preroll];
    [breakBuilder1 offset: offset1];
    JWAdBreak *adBreak1 = [breakBuilder1 buildAndReturnError:&breakError1];
    if (breakError1 != nil ) {
        // Handle error
    }

    // Create an ad break for 30% into the video
    JWError *breakError2;
    JWAdBreakBuilder *breakBuilder2 = [[JWAdBreakBuilder alloc] init];
    [breakBuilder2 tags: @[[NSURL URLWithString:@<#Video URL String#>]]];
    JWAdOffset *offset2 = [JWAdOffset midrollWithPercent:30];
    [breakBuilder2 offset: offset2];
    JWAdBreak *adBreak2 = [breakBuilder2 buildAndReturnError:&breakError2];
    if (breakError2 != nil ) {
        // Handle error
    }

    JWError *adConfigError;
    JWImaAdvertisingConfigBuilder *adConfigBuilder = [[JWImaAdvertisingConfigBuilder alloc] init];
    [adConfigBuilder schedule:@[adBreak1, adBreak2]];
    JWAdvertisingConfig *adConfig = [adConfigBuilder buildAndReturnError:&adConfigError];
    if (adConfigError != nil) {
        // Handle error
    }

Schedule ads using a VMAP file

🚧
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.

A VAST video multiple ad playlist (VMAP) file. According to the IAB, "VMAP enables the content owner to define the ad breaks within their content, including the timing for each break, how many breaks are available, what type of ads and how many are allowed in each break".

Use the following steps to schedule ads using a VMAP file:

Instantiate a JWImaAdvertisingConfig object using the JWImaAdvertisingConfigBuilder(), setting the tag property with the URL of the VMAP file.
Using the JWImaAdvertisingConfig you created and JWPlayerConfigurationBuilder(), instantiate a JWPlayerConfiguration.

@implementation ObjCViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // Create an ad config.
    JWError *adConfigError;
    JWImaAdvertisingConfigBuilder *builder = [[JWImaAdvertisingConfigBuilder alloc] init];
    [builder vmapURL:<#VMAP URL#>];
    JWAdvertisingConfig *adConfig = [builder buildAndReturnError:&adConfigError];
    if (adConfigError != nil) {
        // Handle error
    }

    // Create a player item
    JWError *playerItemError;
    JWPlayerItemBuilder *builder = [[JWPlayerItemBuilder alloc] init];
    [builder file:[NSURL URLWithString:@<#Video URL String#>]];
    JWPlayerItem *playerItem = [builder buildAndReturnError:&playerItemError];
    if (playerItemError != nil) {
        // Handle error
    }

    // Create a player configuration
    JWError *configError;
    JWPlayerConfigurationBuilder *builder = [[JWPlayerConfigurationBuilder alloc] init];
    [builder playlist:@[item]];
    [builder advertising:adConfig];
    JWPlayerConfiguration *config = [builder buildAndReturnError:&configError];
    if (configError != nil) {
        // Handle error
    }

    // Set the config
    [self.player configurePlayer:config];
}

@end

class ViewController: JWPlayerViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create the ad config
        let builder = JWImaAdvertisingConfigBuilder()
           .vmapURL(<#VMAP URL#>)
        guard let adConfig = try? builder.build() else {
            // Handle build error
            return
        }

        
        // Create player item
        let itemBuilder = JWPlayerItemBuilder()
        .file(URL(string: <#Video URL String#>)!)
        guard let playerItem = try? itemBuilder.build() else {
            // Handle build error
            return
        }

        let configBuilder = JWPlayerConfigurationBuilder()
          .playlist([playerItem])
          .advertising(adConfig)
        guard let config = try? configBuilder.build() else {
            // Handle build error
            return
        }

        // Set the config
        player.configurePlayer(with: config)
    }
}