Skip to main content

AVPlayer

The guide shows how to integrate AVPlayer with SmartLib in order to handle ad tracking with the OM SDK enabled. Before starting, you need to have done the OM SDK integration guide.

At this point, you should have initialized the lib, created a streaming session object and have integrated the session lifecycle with the ad tracking into your app.

Requirements

1. Set the ad view instance​

When creating the player instance, attach the content frame to the current session before starting the session (i.e before calling getURL).

// Create your player
AVPlayer *player = [AVPlayer playerWithPlayerItem:nil];

// Attach the player
[self.session attachPlayer:self.player];

// Set the ad view
[self.session setAdView:self.playerView];

2. Set the ad view state​

After setting the ad view instance, set the first ad view state (i.e the state of the ad view before starting the playback). The ad view state can use these values:

  • BPAdViewStateNormal: player normal state (default state)
  • BPAdViewStateMinimized: player minimized state (not visible)
  • BPAdViewStateCollapsed: player collapsed state (view reduced)
  • BPAdViewStateExpanded: player expanded state (view expanded)
  • BPAdViewStateFullscreen: player fullscreen state (fullscreen view)
info

Once the playback started, the ad view state can be updated if the ad view state has been changed.

// Set the ad view
[self.session setAdView:self.playerView];

...

// Set the default ad view state before starting the playback
[self.session setAdViewState:BPAdViewStateNormal]; // BPAdViewStateNormal or any other values

...

// Starting the playback
...

// After an user action that changed the ad view state
[self.session setAdViewState:...];

3. Register an ad friendly obstruction​

If you need to add an overlay with controls that should not be counted as an obstruction, these views have to be registered.

/**
 * Register an ad friendly obstruction view (OMSDK)
 * @param view view
 * @param purpose purpose
 * @param reason reason as string
 */
- (void)registerAdFriendlyObstructionView:(UIView *)view purpose:(AdFriendlyObstructionPurpose)purpose reason:(NSString *)reason;

/**
 * Unregister ad friendly obstruction view (OMSDK)
 * @param view view
 */
- (void)unregisterFriendlyObstruction:(UIView *)view;

/**
 * Unregister all ad friendly obstruction views (OMSDK)
 */
- (void)unregisterAllFriendlyObstructions;
typedef enum : int {
    /**
     * Player controls view friendly obstruction
     */
    BPAdFriendlyObstructionPurposeMediaControls,
    
    /**
     * Close ad view friendly obstruction
     */
    BPAdFriendlyObstructionPurposeCloseAd,
    
    /**
     * Not visible view friendly obstruction
     */
    BPAdFriendlyObstructionPurposeNotVisible,
    
    /**
     * Other view friendly obstruction
     */
    BPAdFriendlyObstructionPurposeOther
} AdFriendlyObstructionPurpose;

After setting the ad view instance and before starting the playback, register ad friendly obstruction views. If you are using the exoplayer-ui module, add the default obstruction views:

// Set the ad view
[self.session setAdView:self.playerView];

...

// Register your own ad friendly obstruction view
[self.session registerAdFriendlyObstructionView:self.skipAdButton purpose:BPAdFriendlyObstructionPurposeCloseAd reason:@"adskip"];
...

4. Trigger an ad user interaction​

Once the playback started, the user can interact with the ad:

  • BPAdInteractionTypeClick: ad user click interaction type
  • BPAdInteractionTypeInvitationAccepted: ad user invitation accept interaction type
// Starting the playback
...

// The user interacts with the ad
[self.session adUserInteraction:BPAdInteractionTypeClick];

5. Advanced features​

These optional methods could help you to enhance your ad experience.

Register an ad verification data​

Ad verification data are usually defined on your ad provider console and forwarded to the app through the manifest manipulator (BkYou). You can also add additional ad verification data through a method. It has to be called before starting the playback.

/**
 * Register an ad verification data url with parameters (OMSDK)
 * @param url url
 * @param vendor vendor
 * @param parameters parameters
 */
- (void)registerAdVerificationData:(NSString *)url vendor:(NSString *)vendor parameters:(NSString *)parameters;
// Register ad verification data
[self.session registerAdVerificationData:@"https://myserver/omsdk-files/omid-validation-verification-script.js" vendor:@"samplevendor" parameters:@"sampleparam"];

...

// Starting the playback
...
note

You can perform a test by configuring a local web server. Find more details on the OM SDK validation documentation.

Set the ad custom reference​

When the OM SDK ad session context is initialized, a custom reference data can be passed. It has to be called before starting the playback.

/**
 * Set ad custom reference data (OMSDK)
 * @param reference reference
 */
- (void)setAdCustomReference:(NSString *)reference;
// Set ad custom reference data
[self.session setAdCustomReference:@"IAB-AVPlayerView"];[self.session setAdCustomReference:@"MyCustomReferenceData"];

...

// Starting the playback
...