CustomAdIntegrationController

public protocol CustomAdIntegrationController

The shared controller for custom ad integrations. Use it to update the state of a custom ad integration.

  • The identifier for this integration, as passed to Ads.registerServerSideIntegration or Ads.registerClientSideIntegration.

    Declaration

    Swift

    var integration: String { get }
  • ads

    The scheduled ads managed by this integration.

    Remark

    Use CustomAdIntegrationController.createAd and CustomAdIntegrationController.removeAd to add or remove ads.

    Declaration

    Swift

    var ads: [Ad] { get }
  • The scheduled ad breaks managed by this integration.

    Remark

    Use CustomAdIntegrationController.createAdBreak and CustomAdIntegrationController.removeAdBreak to add or remove ad breaks.

    Declaration

    Swift

    var adBreaks: [AdBreak] { get }
  • Create a new ad.

    Remark

    The ad will be added to Ads.scheduledAds.

    Declaration

    Swift

    func createAd(params: AdInit, adBreak: AdBreak?) -> Ad

    Parameters

    params

    The initial properties to be set on the created ad.

    adBreak

    If given, appends the ad to the given existing AdBreak. Otherwise, appends the ad to a new or existing AdBreak with the configured AdInit.timeOffset.

    Return Value

    The created Ad object.

  • Update the given ad.

    Declaration

    Swift

    func updateAd(ad: Ad, params: AdInit)

    Parameters

    ad

    The ad to be updated.

    params

    The properties to be updated on the ad.

  • Update the playback progression of the given ad.

    Remark

    The player will fire progression events such as AdsEventTypes.AD_FIRST_QUARTILE, AdsEventTypes.AD_MIDPOINT and AdsEventTypes.AD_THIRD_QUARTILE.

    Declaration

    Swift

    func updateAdProgress(ad: Ad, progress: Double)

    Parameters

    ad

    The ad to be updated.

    progress

    The playback progress, as a number between 0 (at the start of the ad) and 1 (at the end of the ad).

  • Begin the given ad.

    Remark

    The ad will be added to Ads.currentAds. An AdsEventTypes.AD_BEGIN event will be fired.

    Declaration

    Swift

    func beginAd(ad: Ad)

    Parameters

    ad

    The Ad that will begin.

  • End the given ad.

    Remark

    The ad will be removed from Ads.currentAds. If the ad was currently playing, an AdsEventTypes.AD_END event will be fired.

    Declaration

    Swift

    func endAd(ad: Ad)

    Parameters

    ad

    The Ad that will end.

  • Skip the given ad.

    Remark

    The ad will be removed from Ads.currentAds. If the ad was currently playing, an AdsEventTypes.AD_SKIP event will be fired.

    Declaration

    Swift

    func skipAd(ad: Ad)

    Parameters

    ad

    The Ad that will be skipped.

  • Report that the given ad counts as an impression.

    Remark

    The player will fire an AdsEventTypes.AD_IMPRESSION event on every call. The call is ignored if the ad has not begun.

    Declaration

    Swift

    func reportAdImpression(ad: Ad)

    Parameters

    ad

    The ad that counts as an impression.

  • Report that the user clicked on the given ad’s click-through, or on one of its companions.

    Remark

    The player will fire an AdsEventTypes.AD_CLICKED event on every call. The player does not open the click-through; the integration is responsible for that. The ad does not need to be playing, since a companion can stay visible after its ad ended. The call is ignored if the ad was removed.

    Declaration

    Swift

    func reportAdClick(ad: Ad)

    Parameters

    ad

    The ad that was clicked.

  • Remove the given ad.

    Remark

    The ad will be removed from Ads.currentAds and Ads.scheduledAds. If the ad was currently playing, it will first be ended.

    Declaration

    Swift

    func removeAd(ad: Ad)

    Parameters

    ad

    The Ad that will be removed.

  • Create a new ad break.

    This can be used to indicate where ad breaks can be expected in advance, before populating those ad breaks with ads.

    Remark

    The ad break will be added to CustomAdIntegrationController.adBreaks and Ads.scheduledAdBreaks.

    Declaration

    Swift

    func createAdBreak(params: AdBreakInit) -> AdBreak

    Parameters

    params

    The initial properties to be set on the created ad break.

    Return Value

    The created AdBreak object.

  • Update the given ad break.

    Declaration

    Swift

    func updateAdBreak(adBreak: AdBreak, params: AdBreakInit)

    Parameters

    adBreak

    The ad break to be updated.

    params

    The properties to be updated on the ad break.

  • End the given ad break.

    An ad break begins implicitly when the first of its ads is begun with CustomAdIntegrationController.beginAd.

    Remark

    Remark:

    Declaration

    Swift

    func endAdBreak(adBreak: AdBreak)

    Parameters

    adBreak

    The AdBreak that will end.

  • Remove the given ad break and all of its ads.

    Remark

    The ad break will be removed from CustomAdIntegrationController.adBreaks and Ads.scheduledAdBreaks. Any remaining ads in the ad break will be removed.

    Declaration

    Swift

    func removeAdBreak(adBreak: AdBreak)

    Parameters

    adBreak

    The ad break to be removed.

  • Remove all ads and ad breaks.

    Remark

    This is a shorthand for calling CustomAdIntegrationController.removeAdBreak on all ad breaks in CustomAdIntegrationController.adBreaks.

    Declaration

    Swift

    func removeAllAds()
  • Fire an AdsEventTypes.AD_ERROR event on the player’s Ads interface.

    This does not stop playback.

    Declaration

    Swift

    func error(error: Error)

    Parameters

    error

    The error.

  • Fire a fatal PlayerEventMap.ERROR event on the player.

    This stops playback immediately. Use THEOplayer.source to load a new source.

    Declaration

    Swift

    func fatalError(error: Error, code: THEOErrorCode?)

    Parameters

    error

    The error.

    code

    The error code. By default, this is set to THEOErrorCode.AD_ERROR.