Skip to end of metadata
Go to start of metadata

iOS Custom Adaptors

Custom adaptors allow our SDK to call out to another SDK installed on the same device, usually for mediation. This document describes the code you must write to create your own custom adaptors.

Note that the protocols described here are exactly what we used to implement our own mediation adaptors.

On This Page

Banners

In order to make mediation calls to another SDK to show banners, you must implement the ANCustomAdapterBanner protocol. There is only one method specified by this protocol: requestBannerAdWithSize. This method handles instantiating the mediated SDK and using it to make ad requests. It should fire events from the mediated SDK by calling delegate methods like didLoadBannerAd. See the examples below for details.

requestBannerWithAdSize takes the following arguments:

  • size: The size of the mediated ad view.

  • rootViewController: The controller for the mediated ad view.

  • parameterString: An optional opaque string passed from the server, this can be used to define SDK-specific parameters such as additional targeting information. The encoding of the contents of this string are entirely up to the implementation of the third-party SDK adaptor. In other words, the parameter must be populated with values understood by the third-party SDK’s ad server.

  • idString: The ID of the ad unit as understood by the third-party SDK’s ad server. It refers to a specific place where an advertiser can show ads in a mobile app. This ID is opaque to our mobile SDK; the ID’s contents and their encoding are up to the implementation of the third-party SDK.

  • targetingParameters: Any ad targeting parameters such as age, gender, or location that you would like to send to the mediated SDK. You are responsible for sending the mediated SDK parameters that it can understand.

Below is an example adaptor that mediates a fictional “Godzilla” SDK to show banner ads. For more information on the callbacks in this example, see the Required Callbacks and Optional Callbacks sections below.

 

Interstitials

In order to make mediation calls to another SDK to show interstitials, you must implement the ANCustomAdapterInterstitial protocol. There are three methods specified by this protocol:

  • requestInterstitialAdWithParameter: Requests the interstitial ads from the mediated SDK. It takes three arguments:

    • parameterString: An optional opaque string passed from the server, this can be used to define SDK-specific parameters such as additional targeting information. The encoding of the contents of this string are entirely up to the implementation of the third-party SDK adaptor. In other words, the parameter must be populated with values understood by the third-party SDK’s ad server.
    • idString: The ID of the ad unit as understood by the third-party SDK’s ad server. It refers to a specific place where an advertiser can show ads in a mobile app. This ID is opaque to our mobile SDK; the ID’s contents and their encoding are up to the implementation of the third-party SDK.
    • targetingParameters: Any ad targeting parameters such as age, gender, or location that you would like to send to the mediated SDK. You are responsible for sending the mediated SDK parameters that it can understand.
  • isReady: Whether or not there is an interstitial ad loaded and ready to show to the user.

  • presentFromViewController: Displays the interstitial ad to the user. Should include a check to isReady to see if it can operate. Takes one argument, viewController, which is the view controller used to display the interstitial.

In this example code, we mediate a fictional “Godzilla” SDK and have it show an interstitial ad:

Required Callbacks

The callbacks listed below must be implemented in your custom adaptor. You can see examples of their use in the code samples elsewhere on this page.

To indicate a successful ad request, call one of the following depending on whether the ad is a banner or interstitial:

  • - (void)didLoadBannerAd:(UIView *)view: The mediated SDK’s ad request completed and returned a banner successfully.

  • - (void)didLoadInterstitialAd:(id<ANCustomAdapterInterstitial>)adaptor: The mediated SDK’s ad request completed and returned an interstitial. Pass a reference to the current adaptor.

To indicate an unsuccessful ad request whether the ad is a banner or interstitial, call:

  • - (void)didFailToLoadAd:(ANAdResponseCode)errorCode: The mediated SDK’s ad request failed to return a valid ad.

Furthermore, for interstitial adaptors, a failed attempt to show() should call:

  • - (void)failedToDisplayAd: The mediated SDK received a call to present an interstitial, but no ad was available or the SDK failed to present.

Optional Callbacks

The callbacks listed below should be implemented in custom adaptors for both banners and interstitials. Note that they are not strictly required.

  • - (void)adWasClicked: The ad was clicked by the user while being displayed by the mediated SDK.

  • - (void)willPresentAd: The user interacts with the ad and the mediated SDK is about to present a modal view.

  • - (void)didPresentAd: The mediated SDK has presented the modal view.

  • - (void)willCloseAd: The mediated SDK is about to close the modal view.

  • - (void)didCloseAd: The mediated SDK closes the modal view.

  • - (void)willLeaveApplication: The mediated SDK will launch an external application.

Related Topics