Build your custom adapter for iOS

This document covers the steps to build a custom adapter and provide your publishers the resources required to integrate your network with ironSource mediation. 

Before you start
  1. Complete the custom adapter registration form 
  2. Make sure you have the following information available:
    • Adapter class names 
    • Network configuration keys
  3. Download latest ironSource SDK here

Important 

  • Make sure to handle main-thread requirements as part of your code
  • Make sure to add code protections and exception handling to protect apps from unexpected failures 

How to create an adapter for your network

Your network adapter will manage the network ads logic and allow publishers to display your networks ads as part of their ironSource mediation configuration. 

As part of this process, you will need to create an adapter class (referred as BaseAdapter) and an additional class for each ad unit you intend to support.

The BaseAdapter will back your network management, including the network initialization process, and allow you to define variables and constants that will be available throughout the session, for all ad units.

The ad unit classes will manage the ad unit logic for loading, showing, and managing the ad, and will be instantiated per each ad appearance in the waterfall.

Currently, ironSource custom adapters supports interstitial ads.  

Create your network base adapter

To implement your network adapter, create a new class and import ironSource ISBaseNetworkAdapter class. 

Use the Base adapter name you received from your network registration confirmation email when creating your adapter. 

#import "IronSource/ISBaseNetworkAdapter.h"
#import "IronSource/ISAdapterErrors.h"
​​@interface IS<YourNetworkName>CustomAdapter : ISBaseNetworkAdapter
@objc(IS<YourNetworkName>CustomAdapter)
public class IS<YourNetworkName>CustomAdapter:ISBaseNetworkAdapter {
   ...
}

Initialize network SDK

ironSource mediation will call the init method of the base adapter as part of any initialization process in the mediation. As a result, this method can be called several times. 

As part of your init implementation, make sure to call the initialization callbacks defined in the NetworkInitializationListener each time; upon success (onInitSuccess) and/or upon failure (onInitFailed). 

The adData param will include the configuration data as provided by the publisher in the ironSource platform. Learn more on ISAdData class here.  

(void)init:(ISAdData *)adData delegate:(id<ISNetworkInitializationDelegate>)delegate {
   ... 
   // handle errors 
   if (error-handling) {
      [delegate onInitDidFailWithErrorCode:ISAdapterErrorMissingParams errorMessage:error];
   }
   // init success 
   [delegate onInitDidSucceed];
}

Provide SDK and adapter versions

This information will indicate which SDK and adapter versions are currently implemented on the publisher’s app. When implementing getNetworkSDKVersion, we recommend using a method rather than a hard-coded value, to allow more flexibility in terms of adapter updates and SDK support.

- (NSString *) networkSDKVersion {
   return [ALSdk version];
}
- (NSString *) adapterVersion {
   return kAdapterVersion;
}

Add support for interstitial ad unit

Create interstitial ad unit class

Create a class that will manage your interstitial ad unit. Import ironSource ISBaseAdAdapter, and make sure to add relevant delegates to your main adapter file. This class will be activated whenever the publisher triggers a new interstitial ad in the app by the Load method.

Important! Use the interstitial class names you received from ironSource as part of the registration process
#import "IronSource/ISBaseAdAdapter.h"
#import "IronSource/ISAdapterErrors.h"
@interface IS<YourNetworkName>CustomInterstitial : ISBaseAdAdapter
@objc(IS<YourNetworkName>CustomInterstitial)
public class IS<YourNetworkName>CustomInterstitial  : ISBaseAdAdapter {
   ...
}

Request an interstitial ad

Override the loadAdWithAdData method to allow publishers to request interstitial ads from your network. The ISAdData will allow you to access the publisher input and to receive the ad identifiers that are required for this process.

Make sure to implement the ISAdapterAdDelegate callbacks for successful load of an ad (adDidLoad) and for any kind of failure (adDidFailToLoadWithErrorType). In case the listener callback is not triggered after a pre-defined amount of time, the meditation will stop the load process due to a timeout, and the network will not be able to provide an ad.

- (void)loadAdWithAdData:(nonnull ISAdData *)adData
                delegate:(nonnull id<ISAdapterAdDelegate>)delegate {
  
   // Load your ad 
}

Check if ad is available

Override the isAdAvailableWithAdData method to allow publishers to check each ad’s readiness before trying to present it to the user. The method should return YES if an ad is loaded successfully, or NO if no ad is currently loaded. This can be done by using the network’s is-ad-available indication, if it exists, or by managing the ad’s status manually as part of loadAdWithAdData and showAdWithViewController methods.

- (BOOL)isAdAvailableWithAdData:(nonnull ISAdData *)adData {
   return _renderedAd != nil;
}

Show an interstitial ad

Once an ad is loaded successfully, the publisher should be able to show it. You can override the showAdWithViewController method after verifying that isAdAvailableWithAdData is true, to provide a better experience for publishers. Part of the information you receive in this method is ISAdData. Using this object, you will be allowed to show the relevant ad. The adDidFailToShowWithErrorCode callback should be returned if the show could not be performed.

- (void)showAdWithViewController:(nonnull UIViewController *)viewController
                          adData:(nonnull ISAdData *)adData
                        delegate:(nonnull id<ISAdapterAdDelegate>)delegate {
   // check if ad can be displayed
   if (CannotShowsAd) {
      [delegate adDidFailToShowWithErrorCode:ISAdapterErrorInternal
                                 errorMessage:nil];
      return;
   }
   // show ad 
   [_ad showAd:_renderedAd];
}

Report the ISAdapterAdDelegate callbacks

Make sure to override ISAdapterAdDelegate callbacks according to the network’s functionality. Reporting the delegates correctly will ensure ironSource mediation’s best practice flow, and will enable the network’s performance data to be reflected correctly in the ironSource platform. 

Mandatory callbacks:

// Indicates that interstitial ad was loaded successfully 
-(void)adDidLoad;

// The interstitial ad failed to load. Use ironSource ErrorTypes (No Fill / Other) 
-(void)adDidFailToLoadWithErrorType:(ISAdapterErrorType)errorType errorCode:(int)errorCode errorMessage:(NSString*)errorMessage;

// The interstitial ad was displayed successfully to the user. This indicates an impression.  
-(void)adDidOpen;

// User closed the interstitial ad
-(void)adDidClose;

// The ad could not be displayed 
-(void)adDidFailToShowWithErrorCode:(int)errorCode errorMessage:(NSString*)errorMessage;

Optional callbacks: 

// Indicates the network differentiates between show-success and ad-open (impression)
-(void)adDidShowSucceed;

// Indicates an ad was clicked 
-(void)adDidClick;

How to get data from your base adapter (optional)

Use the getNetworkAdapter API if your base adapter manages states or params that are relevant for your ad units through the session. This includes any objects defined as part of your base adapter that should be used in your ad-unit APIs.

// example of data retrieved from your network level adapter
IS<yourNetworkName>CustomAdapter *sampleNetworkAdapter = nil;
id<ISAdapterBaseProtocol> adapter = [self getNetworkAdapter];
if ([adapter isKindOfClass:[IS<yourNetworkName>CustomAdapter class]]) {
   sampleNetworkAdapter = (IS<yourNetworkName>CustomAdapter*) adapter;
}

Access publisher’s input via the adapter

As part of the custom adapter registration process, you provided App and Instance level keys. 

The value of these keys will be defined by the publisher on the ironSource mediation platform configuration. These values will be available for you in run-time via the ISAdData object. 

The ISAdData object contains a map with the configuration values, and is part of the adapter and the ad unit classes APIs. This parameter is available in the init, loadAdWithAdData, showAdWithViewController and isAdAvailableWithAdData methods.

You can access the values from the ISAdData map structure using the names you received as part of the registration confirmation email. 

// Get Publisher setup parameters 
NSString *appLevelParam1 = ISAdData.configuration[<YourAppLevelParam1>];
NSString *instanceLevelParam1 = ISAdData.configuration[<YourInstanceLevelParam1>];
NSString *instanceLevelParam2 = ISAdData.configuration[<YourInstanceLevelParam2>];

Use ironSource error codes and error types

Error type

This is relevant for adDidFailToLoadWithErrorType delegates. 

Error type Description
ISAdapterErrorTypeNoFill Used when there is no available ad to show
ISAdapterErrorTypeInternal Used for any other reason reported by the network

Error codes

These error codes are relevant for adDidFailToLoadWithErrorType and adDidFailToShowWithErrorCode delegates. 

Error code Description
ISAdapterErrorMissingParams The action failed because some required information was not available when API was called
ISAdapterErrorAdExpired Use to indicate if the ad was expired
ISAdapterErrorInternal Used for any other error reported by the network

Debug your adapter (optional)

If you choose to support debug logs, implement and call the setAdapterDebug method from your app. This should be done as part of the ISBaseNetworkAdapter

- (void) setAdapterDebug:(BOOL) adapterDebug {
   _adapterDebug = adapterDebug;
}