Define ad rules (iOS)

You can define ad rules that control how often a viewer sees ads while viewing your video content. Ad rules can be used only while using the JWP or IMA advertising clients.

If you are publishing playlists that consist of short-duration videos, like tutorials or product reviews, you can define startOn (the first playlist item allowing ad playback) and frequency (the regularity of ads within a playlist).
If you are publishing long-form content, like webinars or interviews, you can define startOnSeek (which determines if a returning visitor is served a pre-roll before resuming content playback) and timeBetweenAds (which sets the minimum time that must elapse between ads playback).

You can read Ad rules reference to learn more about how each ad rule impacts a user's experience.

Implementation

Use the following steps and code samples to define ad rules for the player you added to your view with an ad schedule.

Create a JWAdRules object using the JWAdRulesBuilder().
Assign the created JWAdRules object to your JWAdvertisingConfig using either JWAdsAdvertisingConfigBuilder() or JWImaAdvertisingConfigBuilder().

Examples

Example 1: Short-form content

The following example illustrates a short-form media item with an IMA pre-roll. The first ad plays before the first playlist item (startOn: 1). Then, subsequent pre-rolls appear for every third playlist item (frequency: 3), starting with the fourth playlist item.

class ViewController: JWPlayerViewController {
    
     override func viewDidLoad() {
        super.viewDidLoad()

        // Create the ad rules
        let adRulesBuilder = JWAdRulesBuilder()
        .imaRules(startOn: 1,
                  frequency: 3)
        guard let adRules = try? adRulesBuilder.build() else {
            // Handle build error
            return
        }

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

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

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

        let itemBuilder2 = JWPlayerItemBuilder()
        .file(URL(string: <#Video URL String#>)!)
        guard let playerItem2 = try? itemBuilder2.build() else {
            // Handle build error
            return
        }

        let itemBuilder3 = JWPlayerItemBuilder()
        .file(URL(string: <#Video URL String#>)!)
        guard let playerItem3 = try? itemBuilder3.build() else {
            // Handle build error
            return
        }

        let itemBuilder4 = JWPlayerItemBuilder()
        .file(URL(string: <#Video URL String#>)!)
        guard let playerItem4 = try? itemBuilder4.build() else {
            // Handle build error
            return
        }

        let itemBuilder5 = JWPlayerItemBuilder()
        .file(URL(string: <#Video URL String#>)!)
        guard let playerItem5 = try? itemBuilder5.build() else {
            // Handle build error
            return
        }

        let configBuilder = JWPlayerConfigurationBuilder()
        .playlist([playerItem1, playerItem2, playerItem3, playerItem4, playerItem5])
        .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 rules
    JWError *error;
    JWAdRulesBuilder *adRulesBuilder = [[JWAdRulesBuilder alloc] init];
    [adRulesBuilder imaRulesWithStartOn:1 frequency:2];
    JWAdRules *rules = [adRulesBuilder buildAndReturnError:&error];


    // Create an 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
    }

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

    // Create player items
    JWError *playerItemError;

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

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

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

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

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

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

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

Example 2: Long-form content

The following example illustrates a long-form media item with multiple JWP ad breaks. The startOnSeek and timeBetweenAds (set to 300 seconds) ad rules have been defined.

class ViewController: JWPlayerViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create the ad rules
        let adRulesBuilder = JWAdRulesBuilder()
        .jwRules(startOn: 1,
                 frequency: 1,
                 timeBetweenAds: 300,
                 startOnSeek: .pre)
        guard let adRules = try? adRulesBuilder.build() else {
            // Handle build error
            return
        }

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

        let adBreakBuilder2 = JWAdBreakBuilder()
            .offset(.seconds(10))
            .tags([URL(string: <#Video URL String#>)!])
        guard let adBreak2 = try? adBreakBuilder2.build() else {
            // Handle build error
            return
        }

        let adBreakBuilder3 = JWAdBreakBuilder()
            ..offset(.seconds(15))
            .tags([URL(string: <#Video URL String#>)!])
        guard let adBreak3 = try? adBreakBuilder3.build() else {
            // Handle build error
            return
        }

        let adBreakBuilder4 = JWAdBreakBuilder()
            .offset(.percent(15))
            .tags([URL(string: <#Video URL String#>)!])
        guard let adBreak4 = try? adBreakBuilder4.build() else {
            // Handle build error
            return
        }

        let adBreakBuilder5 = JWAdBreakBuilder()
            .offset(.post)
            .tags([URL(string: <#Video URL String#>)!])
        guard let adBreak5 = try? adBreakBuilder5.build() else {
            // Handle build error
            return
        }

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

        let itemBuilder1 = JWPlayerItemBuilder()
        .file(URL(string: <#Video URL String#>)!)
        guard let playerItem1 = try? itemBuilder1.build() else {
            // Handle build error
            return
        }

        let configBuilder = JWPlayerConfigurationBuilder()
        .playlist([playerItem1])
        .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 rules
    JWError *error;
    JWAdRulesBuilder *builder = [[JWAdRulesBuilder alloc] init];
    [builder jwRulesWithStartOn:1 frequency:1 timeBetweenAds:300 startOnSeek:JWAdShownOnSeekPre];
    JWAdRules *rules = [builder buildAndReturnError:&error];


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

    JWAdBreakBuilder *breakBuilder2 = [[JWAdBreakBuilder alloc] init];
    [breakBuilder2 tags: @[[NSURL URLWithString:@<#Video URL String#>]]];
    [breakBuilder2 offset: [JWAdOffset midrollWithSeconds:10]];
    JWAdBreak *adBreak2 = [breakBuilder2 buildAndReturnError:&breakError];
    if (breakError != nil ) {
        // Handle error
    }

    JWAdBreakBuilder *breakBuilder3 = [[JWAdBreakBuilder alloc] init];
    [breakBuilder3 tags: @[[NSURL URLWithString:@<#Video URL String#>]]];
    [breakBuilder3 offset: [JWAdOffset midrollWithSeconds:10]];
    JWAdBreak *adBreak3 = [breakBuilder3 buildAndReturnError:&breakError];
    if (breakError != nil ) {
        // Handle error
    }

    JWAdBreakBuilder *breakBuilder4 = [[JWAdBreakBuilder alloc] init];
    [breakBuilder4 tags: @[[NSURL URLWithString:@<#Video URL String#>]]];
    [breakBuilder4 offset: [JWAdOffset midrollWithPercent:25]];
    JWAdBreak *adBreak4 = [breakBuilder4 buildAndReturnError:&breakError];
    if (breakError != nil ) {
        // Handle error
    }

    JWAdBreakBuilder *breakBuilder5 = [[JWAdBreakBuilder alloc] init];
    [breakBuilder5 tags: @[[NSURL URLWithString:@<#Video URL String#>]]];
    [breakBuilder5 offset: [JWAdOffset postroll]];
    JWAdBreak *adBreak5 = [breakBuilder5 buildAndReturnError:&breakError];
    if (breakError != nil ) {
        // Handle error
    }

    // Create ad config
    JWError *adConfigError;
    JWAdsAdvertisingConfigBuilder *builder = [[JWAdsAdvertisingConfigBuilder alloc] init];
    [builder schedule:@[adBreak1, adBreak2, adBreak3, adBreak4, adBreak5]];
    [builder adRules:adRules];
    JWAdvertisingConfig *adConfig = [builder buildAndReturnError:&error];
    if (adConfigError != nil ) {
        // Handle error
    }
    
    // Create the player config
    JWError *configError;
    JWPlayerConfigurationBuilder *configBuilder = [[JWPlayerConfigurationBuilder alloc] init];
    [configBuilder playlist:@[playerItem1]];
    [configBuilder advertising:adConfig];
    JWPlayerConfiguration *config = [configBuilder buildAndReturnError:&configError];
    if (configError != nil) {
        // Handle error
    }

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