Tutorial

This page describes in short the steps you need to perform to set up an integration using one of the Pulse SDKs. The examples given are for the Android and iOS Pulse SDK, but equivalent methods exist in the other Pulse SDKs (HTML5 and tvOS). The steps to follow are:

  1. Initialise the Pulse SDK
  2. Implement the Pulse Session Listener
  3. Create the Pulse Session
  4. Start the Pulse Session
  5. Implement Remaining Pulse Session Event Methods
  6. Handle the Pulse Video Ads
    1. Select the correct media file
    2. Implement the ad event methods
    3. Handle associated companion banners (optional)
  7. Handle the Pulse Pause Ads (optional)
    1. Verify the supported resource file
    2. Implement the pause ad event methods
  8. Implement Pulse Session Extension (optional)

Initialise the Pulse SDK

During the startup of the video player application, you initialise the Pulse SDK and set up the connection to your Ooyala Pulse account. For example, this is done with:

Android:

Pulse.setPulseHost(hostUrl, deviceContainer, persistentId);

iOS (Obj-C):

[OOPulse setPulseHost:hostUrl deviceContainer:container persistentId:userId];

where:

  • hostUrl is the URL to your Ooyala Pulse account, which can be created by taking your sub-domain and appending ".videoplaza.tv" after it. The sub-domain is found under Settings>Account Settings>Integration Information>Sub-domain after logging into Ooyala Pulse.
  • deviceContainer is the identifier for a range of devices, used for targeting and reporting. In general, this parameter should be set to NULL to use Pulse's built-in device detection.
  • persistentId is the unique user identifier, like a cookie, used for frequency capping, audience targeting, and so on.

For more information about these parameters, refer to Ooyala Video Advertising SDK Parameter Reference.

A code example would be:

Android:

Pulse.setPulseHost("http://pulse-demo.videoplaza.tv", null, null);

iOS (Obj-C):

[OOPulse setPulseHost:@"https://pulse-demo.videoplaza.tv" deviceContainer:nil persistentId:nil];

Implement the Pulse Session Listener

To respond to the events coming from the Pulse SDK, you need to implement a listener which overrides all required methods defined in the Pulse Session Listener protocol (iOS, tvOS) or interface (Android, HTML5). For example, in the Android Pulse sample integration, the listener interface is implemented in the PulseManager.java class.

The available methods to override, for example, for the Android Pulse SDK can be found here: Interface PulseSessionListener.

Create the Pulse Session

When you know which video the viewer has selected in the video player application, you create the Pulse Session object, which is used to send the video player events to the Pulse SDK. For example, this is done with:

Android:

Pulse.createSession(contentMetadata, requestSettings);

iOS (Obj-C):

[OOPulse sessionWithContentMetadata:contentMetadata requestSettings:requestSettings];

where:

  • contentMetadata is the object containing all meta data about the video requested by the viewer.
  • requestSettings is the object containing information about each position in the video where ads should be served.

For more information about these parameters, refer to Ooyala Video Advertising SDK Parameter Reference.

A code example would be:

Android:

public class PulseManager implements PulseSessionListener {
 private PulseSession pulseSession;
 
...
 
 pulseSession = Pulse.createSession(getContentMetadata(), getRequestSettings());
 
...
 
 private ContentMetadata getContentMetadata() {
  ContentMetadata contentMetadata = new ContentMetadata(); 
  // implement the creation of the contentMetadata object
  return contentMetadata;
 }
 
 private RequestSettings getRequestSettings() {
  RequestSettings newRequestSettings = new RequestSettings();
  // implement the creation of the newRequestSettings object
  return newRequestSettings;
 }
 
...
}

iOS (Obj-C):

@interface PulseManager <OOPulseSessionDelegate>
@property (strong, nonatomic) id<OOPulseSession> *pulseSession;
@end

@implementation PulseManager <OOPulseSessionDelegate>

- (void) initializePulseSession
{
  OOContentMetadata *contentMetadata = [[OOContentMetadata alloc] init];
  // fill the contentMetadata object
  ...

  OORequestSettings *requestSettings = [[OORequestSettings alloc] init];
  // fill the requestSettings object
  ...

  self.pulseSession = [OOPulse sessionWithContentMetadata:contentMetadata requestSettings:requestSettings];

  ...
}

@end

Start the Pulse Session

Now that you have created the Pulse Session, you start it to pass the Pulse Session Listener to the Pulse SDK, so it has the correct object to send events to. For example, this is done with:

Android:

PulseSession.startSession(listener);

iOS (Obj-C):

[OOPulseSession startSessionWithDelegate:listener];

where the listener is the reference to the Pulse Session Listener.

A code example would be:

Android:

public class PulseManager implements PulseSessionListener {
 private PulseSession pulseSession;
 
...
 
 pulseSession = Pulse.createSession(getContentMetadata(), getRequestSettings());
 pulseSession.startSession(this);
 
...
 
}

iOS (Obj-C):

@interface PulseManager <OOPulseSessionDelegate>
@property (strong, nonatomic) id<OOPulseSession> pulseSession;
@end

@implementation PulseManager

- (void) initializePulseSession
{
  ...

  self.pulseSession = [OOPulse sessionWithContentMetadata:contentMetadata requestSettings:requestSettings];
  [self.pulseSession startSessionWithDelegate:self];

  ...
}

@end

Implement Remaining Pulse Session Event Methods

You have implemented the listener to respond to events coming from the Pulse SDK. Now, you need to implement the remaining methods from the Pulse Session protocol (iOS, tvOS) or interface (Android, HTML5) to send information about content playback from the video player to the Pulse SDK. For example, in the Android Pulse sample integration, the session interface is also implemented in the PulseManager.java class.

The methods that need to be reported, for example, for the Android Pulse SDK can be found here: Interface PulseSession.

Handle the Pulse Video Ads

When an ad break is due, the Pulse SDK sends a startAdBreak event containing the ad break object. For example:

Android:

PulseSessionListener.startAdBreak(adBreak);

iOS (Obj-C):

- (void)startAdBreak:(id<OOPulseAdBreak>)adBreak;

In your application, you can prepare to start showing ads, for example, by stopping the video playback as a response to getting this event. The ad break object also gives you access to the amount of ads in the break, the amount of remaining ads in the break and a way to stop the ad break.

After an ad break has started, the Pulse SDK sends startAdPlayback events containing an ad and for each ad in the ad break. For example:

Android:

PulseSessionListener.startAdPlayback(ad, timeout);

iOS:

- (void)startAdPlaybackWithAd:(id<OOPulseVideoAd>)ad timeout:(NSTimeInterval)timeout;
Select the correct media file

Now, you need to select the correct media file to display from the ad. For example:

Android:

@Override
public void startAdPlayback(PulseVideoAd pulseVideoAd, float timeout) {
 currentPulseVideoAd = pulseVideoAd;
 adPlaybackTimeout = (long) timeout;
 String adUri = selectAppropriateMediaFile(pulseVideoAd.getMediaFiles()).getURL().toString();

...


}
 
...
 
MediaFile selectAppropriateMediaFile(List<MediaFile> potentialMediaFiles) {
 MediaFile selected = null;
 int highestBitrate = 0;
 for (MediaFile file : potentialMediaFiles) {
  if (file.getBitRate() > highestBitrate) {
   highestBitrate = file.getBitRate();
   selected = file;
  }
 }
 return selected;
}

iOS (Obj-C):

@interface PulseManager <OOPulseSessionDelegate>
@property (strong, nonatomic) id<OOPulseSession> pulseSession;
@property (strong, nonatomic) id<OOPulseVideoAd> currentPulseVideoAd;
@end

@implementation PulseManager

...

- (void)startAdPlaybackWithAd:(id<OOPulseVideoAd>)ad timeout:(NSTimeInterval)timeout
{
  self.currentPulseVideoAd = ad;
  NSString *uri = [self selectAppropriateMediaFileFromList:currentPulseVideoAd.mediaFiles].URL.absoluteString;

  ...

}

...

- (OOMediaFile *)selectAppropriateMediaFileFromList:(NSArray<OOMediaFile *>*)potentialMediaFiles
{
  OOMediaFile *selected = nil;
  NSInteger highestBitRate = 0;

  for (OOMediaFile *file in potentialMediaFiles) {
    if (file.bitRate > highestBitRate) {
      highestBitRate = file.bitRate;
      selected = file;
    }
  }
  return selected;
}

...

@end
Implement the ad event methods

When you have the correct media file, start the ad playback and implement all methods from the Pulse Video Ad protocol (iOS, tvOS) or interface (Android, HTML5) to send information about ad playback from the video player to the Pulse SDK. For example, in the Android Pulse sample integration, the ad interface is also implemented in the PulseManager.java class.

The methods that need to be reported, for example, for the Android Pulse SDK can be found here: Interface PulseVideoAd.

Handle associated companion banners (optional)
Note:

The following only needs to be implemented if you want to show companion banners in your native applications using the Android or iOS SDKs. Companion banners are handled automatically when using the HTML5 SDK.

For the Android and iOS SDKs, only static images are supported as companion banners. The Pulse SDK only returns companion banners with the static resource type.

Important:

There are two important prerequisites to show companion banners:

  1. The banner areas, also called zones, must be defined in your view(s).
  2. Companion banners should only be shown after you have successfully started playing back the linear ad they are associated with, so after you have sent the adStarted event.

If a linear ad has associated companion banners, then you can also show those in your native applications. The companion banners are accessed as follows:

Android:

@Override
public void startAdPlayback(PulseVideoAd pulseVideoAd, float timeout) {
    currentPulseVideoAd = pulseVideoAd;
    adPlaybackTimeout = (long) timeout;
 
...
 
    //code to start ad playback
 
...
 
    //report the adStarted event after successfully starting ad playback
    currentPulseVideoAd.adStarted();
 
    //get the associated companion banner ads, but only after successfully starting the ad playback
    List<PulseCompanionAd> companionAds = currentPulseVideoAd.getCompanions();
     
...
 
}

iOS (Obj-C):

- (void)startAdPlaybackWithAd:(id<OOPulseVideoAd>)ad timeout:(NSTimeInterval)timeout
{
  self.currentPulseVideoAd = ad;

  ...

  // code to start ad playback

  ...

  // report the adStarted event after successfully starting ad playback
  [self.currentPulseVideoAd adStarted];

  // get the associated companion banner ads, but only after successfully starting the ad playback
  NSArray<id<OOPulseCompanionAd>> *companionAds = self.currentPulseVideoAd.companions;

  ...

}

To be able to show the companion banners, verify that its zone is a valid banner area in your application and then show the resource in the banner area:

Android:

...
//list the available banner areas in your application
List<String> availableBannerAreas = Arrays.asList("companion-zone-top", "companion-zone-bottom");
 
...
 
//if there are companion ads, check that their zone is a valid banner area
if (companionAds != null) {
    for (PulseCompanionAd companionAd : companionAds) {
        if (availableBannerAreas.contains(companionAd.getZoneIdentifier())) {
            displayBannerAd(companionAd);
        }
    }
}  
 
...
 
//show the companion ad
void displayBannerAd(PulseCompanionAd companionAd) {
     
    //code to show the ad, using the .getResourceURL and .getZoneIdentifier methods on the companion ad object
 
}
 
...

iOS (Obj-C):

...

//list the available banner areas in your application
NSArray<NSString *> *availableBannerAreas = @[@"companion-zone-top", @"companion-zone-bottom"];
 
...
 
//if there are companion ads, check that their zone is a valid banner area
if (companionAds != nil) {
  for (id<OOPulseCompanionAd> companionAd in companionAds) {
    for (NSString *area in availableBannerAreas) {
      if ([companionAd.zoneIdentifier isEqualToString:area]) {
        [self displayBannerAd:companionAd];
      }
    }
  }
}
 
...
 
//show the companion ad
- (void) displayBannerAd:(id<OOPulseCompanionAd>) companionAd
{
     
    //code to show the ad, using the .resourceURL and .zoneIdentifier methods on the companion ad object
 
}
 
...

When you have successfully shown a companion ad, you must notify the session of it. If it was not successful, then do nothing.

Android:

...
  
//show the companion ad
void displayBannerAd(PulseCompanionAd companionAd) {
     
    //code to show the ad, using the .getResourceURL and .getZoneIdentifier methods on the companion ad object
 
    //if the companion ad was successfully shown, then report the adDisplayed event to the session
    companionAd.adDisplayed();
  
}
 
...

iOS (Obj-C):

...
 
//show the companion ad
- (void) displayBannerAd:(id<OOPulseCompanionAd>) companionAd
{

  //code to show the ad, using the .resourceURL and .zoneIdentifier methods on the companion ad object
  
  //if the companion ad was successfully shown, then report the adDisplayed event to the session
  [companionAd adDisplayed];

}
 
...

The methods available on the companion ad object, for example, for the Android Pulse SDK can be found here: Interface PulseCompanionAd.

Handle the Pulse Pause Ads (optional)

Although handling pause events in the player in a way to get pause ads is optional, it is good practice to implement the following methods, so your integration is ready whenever you want to start serving pause ads from Pulse.

When the viewer pauses the video, you report contentPaused to PulseSession. If you have requested pause ads in your integration, the Pulse SDK sends showPauseAd events containing a pause ad. For example:

Android:

...

PulseSession.contentPaused();

...

PulseSessionListener.showPauseAd(ad);

iOS (Obj-C):

...

[self.session contentPaused];

...

[self showPauseAd:ad];

.....
Verify the supported resource file

Now, you need to verify that your integration can access and display the provided ad. For example, in the Android Pulse sample integration you have to first verify if the provided pause ad type is supported by your integration, then you need to load the image from the URL:

Android:

@Override
public void showPauseAd(PulsePauseAd pulsePauseAd) {
  ...
  currentPulsePauseAd = pulsePauseAd;
  ...
  String pauseAdType = currentPulsePauseAd.getResourceType();

  if (pauseAdType.equals("image/jpeg")) {
    URL srcUrl = currentPulsePauseAd.getResourceUrl();
    if (srcUrl != null) {
      // Try to load the image from provided URL
      // pauseImageView is the container to show the image
      pauseImageView.loadImage(srcUrl);
      
      ...

      // after successfully showing the pause ad, you must report it
      currentPulsePauseAd.adDisplayed();
    }
  }
}

...

public void loadImage(URL url) {
  new DownloadImageTask(imageView, this)
    .execute(url.toString());
}

iOS (Obj-C):

- (void)showPauseAd:(id<OOPulsePauseAd>)ad
{
  ...
  
  self.currentPulsePauseAd = ad;
  
  ...
  
  NSString *pauseAdType = self.currentPulsePauseAd.resourceType;
  
  if ([pauseAdType isEqualToString:@"image/jpeg"]) {
    NSURL *srcUrl = self.currentPulsePauseAd.resourceURL;
    if (srcUrl != nil) {
      // load the image from the provided URL and display it

      ...
      
      // after successfully showing the pause ad, you must report it
      [self.currentPulsePauseAd adDisplayed];
    }
  }
}
Implement the pause ad event methods

When you have the correct source file, start displaying the ad and implement all methods from the Pulse Pause Ad protocol (iOS, tvOS) or interface (Android, HTML5) to send information about the ad from the video player to the Pulse SDK. For example, in the Android Pulse sample integration, the ad interface is also implemented in the PulseManager.java class.

The methods that need to be reported, for example, for the Android Pulse SDK can be found here: Interface PulsePauseAd.

Implement Pulse Session Extension (optional)

If you want to request more linear ads or new pause ads, you need to extend the Pulse Session by implementing the extendSession method. In the same way when creating the session, you must pass in content metadata and request settings. The content metadata can be the same, but you must make sure that none of the settings in the content metadata interfere with requesting the desired additional ads. For example, if you added a tag called 'standard-preroll' that prevents requesting midrolls, then you must update the content metadata object without this tag if you want to request midrolls in the session extension. The request settings have to be updated with the positions where you want to show additional ads with the following limitations:
  • You cannot request insertion points that have been requested already. For example, if you have already requested post-roll ads, then you cannot request them again.
  • You can request additional mid-rolls, but only for cue points that have not been requested yet. For example, if you have already requested midrolls to show after 10 seconds and 30 seconds of video content playback, you can only request more midrolls for times that differ from 10 and 30 seconds.
  • You may request pause ads multiple times, but the selected pause ad is always the last one requested. This means that the pause ad insertion point is always overwritten with the latest result from the session extension.

The extendSession method also takes a callback function, or a PulseSessionExtensionListener in case of the Android Pulse SDK, to execute when the session extension was successful. For example:

Android:

pulseSession.extendSession(updatedContentMetadata, updatedRequestSettings, new PulseSessionExtensionListener() {
  @Override
  public void onComplete() {
    Log.i("Pulse Demo Player", "Session was successfully extended.");
  }
});

iOS (Obj-C):

[self.session extendSessionWithContentMetadata:updatedContentMetadata 
                               requestSettings:updatedRequestSettings 
                                       success:^{NSLog(@"Session was successfully extended.");
}];

Was this article helpful?