Build your custom adapter for Android

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

How to create an adapter for your network

Your network adapter will manage the network ad logic to allow publishers displaying ads from your networks using ironSource mediation. 

As part of this process, you will need to create an adapter class, called the BaseAdapter, and an additional class for each ad unit you’d like to support.

The BaseAdapter will help you manage your network’s SDK, including the SDK 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 determine the logic for loading, showing, and managing the ad, and will be instantiated for each ad appearance in your waterfall.

Currently, ironSource custom adapters support interstitial ads, with more ad units coming soon.  

Create your network base adapter

To implement your network adapter, create a new class in a dedicated package by extending the ironSource BaseAdapter class

Use the Package and Base adapter names you received in your custom adapter registration confirmation email. 

package com.ironsource.adapters.custom.<YourNetworkName>;
public class <YourNetworkName>CustomAdapter extends BaseAdapter {
   // Your class implementation 
}

Initialize network SDK

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

As part of your init implementation, make sure to call the initialization callbacks defined in the NetworkInitializationListener each time it succeeds (onInitSuccess) or fails (onInitFailed).

The AdData param will include the configuration data the publisher provided to ironSource. Learn more on AdData class here. 

void init(@NotNull AdData adData, @NotNull Context context, @Nullable NetworkInitializationListener listener)
{
   ... 
   if (init-success-condition) {
      // Initialization completed successfully 
      listener.onInitSuccess(); 
   } else {
     // Initialization failed 
     listener.onInitFailed(AdapterErrors.ADAPTER_ERROR_MISSING_PARAMS, error); 
   }
}

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 an API instead of a hard-coded value to allow more flexibility for adapter updates and SDK support.

@Nullable String getNetworkSDKVersion();
@NotNull String getAdapterVersion();

Add support for interstitial ad unit

Create interstitial ad unit class

Create a class that will manage your interstitial ad unit by extending the BaseInterstitial class, as part of the same package of your network’s custom adapter. This class will be activated when the publisher triggers a new interstitial ad in the app through the Load API.

package com.ironsource.adapters.custom.[YourNetworkName];
public class SampleCustomInterstitial extends BaseInterstitial<SampleCustomAdapter> implements SampleNetworkInterstitialAdListener {
public class <YourNetworkName>CustomInterstitial extends 
BaseInterstitial <<YourNetworkNameCustomAdapter>> { 
...
}

Implement ad unit constructor

Implement the constructor using the NetworkSetting object. This is required as part of the interstitial ad unit implementation, and it will make sure your network can be added to the waterfall.

public <YourNetworkName>CustomInterstitial(NetworkSettings networkSettings) {
   super(networkSettings);
}

Request an interstitial ad

Override the LoadAd API to allow publishers to request interstitial ads from your network. The AdData will allow you to access the publisher’s input and to receive the ad identifiers.

 Make sure you implement the InterstitialAdListener callbacks for the successful load of an ad (onAdLoadSuccess) and for any kind of failure (onAdLoadFailed). In case the listener callback is not triggered after a pre-defined amount of time, the meditation will stop loading and the network will not be able to provide an ad. 

public void loadAd(AdData adData, Activity activity, InterstitialAdListener listener) {
 
   // Load your ad     
}

Check if ad is available

Override the isAdAvailable API to allow publishers to check ad’s readiness before trying to present an ad to the user. The API should return true if an ad is loaded successfully, or false if no ad is currently loaded. This can be done by using the network’s is-ad-available indication, if your network offers one, or by managing the ad’s status manually as part of LoadAd and ShowAd APIs.

public boolean isAdAvailable(AdData adData) {
   return isAdAvailable;
}

Show an interstitial ad

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

public void showAd(AdData adData, InterstitialAdListener listener) { 
    
   // check your ad load status 
   if (isAdLoaded)  {
      // show your ad       
 
   } else {
      listener.onAdShowFailed(adatperErrorCode, adapterErrorMsg);
   }
}

Report the InterstitialAdListener callbacks

Make sure to override InterstitialAdListener’s callbacks according to the network’s functionality. Reporting the callbacks 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 onAdLoadSuccess();

// The interstitial ad failed to load. Use ironSource ErrorTypes (No Fill / Other) 
void onAdLoadFailed(@NotNull AdapterErrorType adapterErrorType, int errorCode, @Nullable String errorMessage);

// The interstitial ad is displayed successfully to the user. This indicates an impression.  
void onAdOpened();

// User closed the interstitial ad
void onAdClosed();

// The ad could not be displayed 
void onAdShowFailed(int errorCode, @Nullable String errorMessage);

Optional callbacks: 

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

// Indicates an ad was clicked 
void onAdClicked();

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
SampleCustomAdapter networkAdapter = getNetworkAdapter();
  
if (networkAdapter != null) {
   
   // call network level method
   String extraData = networkAdapter.sampleAppLevelData();
 
} 

Add support for rewarded video ad unit

Create rewarded video ad unit class

Create a class that will manage your rewarded video ad unit by extending the BaseRewardedVideo class, as part of the same package of your network’s custom adapter. This class will be activated when the publisher triggers a new rewarded video ad in the app through the Load API.

package com.ironsource.adapters.custom.[YourNetworkName];
import com.ironsource.mediationsdk.adunit.adapter.BaseRewardedVideo;
import com.ironsource.mediationsdk.adunit.adapter.listener.RewardedVideoAdListener;
import com.ironsource.mediationsdk.adunit.adapter.utility.AdData;
import com.ironsource.mediationsdk.adunit.adapter.utility.AdapterErrorType;
import com.ironsource.mediationsdk.adunit.adapter.utility.AdapterErrors;
import com.ironsource.mediationsdk.model.NetworkSettings;

Implement ad unit constructor

Implement the constructor using the NetworkSetting object. This is required as part of the rewarded video ad unit implementation, and it will make sure your network can be added to the waterfall.

public <YourCustomNetwork>CustomRewardedVideo(NetworkSettings networkSettings) {
        super(networkSettings);
}

Request a Rewarded Video ad

Override the LoadAd API to allow publishers to request rewarded video ads from your network. The AdData will allow you to access the publisher’s input and to receive the ad identifiers.

 Make sure you implement the RewardedVideoAdListener callbacks for the successful load of an ad (onAdLoadSuccess) and for any kind of failure (onAdLoadFailed). In case the listener callback is not triggered after a pre-defined amount of time, the meditation will stop loading and the network will not be able to provide an ad.

public void loadAd(@NotNull AdData adData, @NotNull Activity activity, @NotNull RewardedVideoAdListener rewardedVideoAdListener) {
   // Load your ad     
}

Check if ad is available

Override the isAdAvailable API to allow publishers to check ad’s readiness before trying to present an ad to the user. The API should return true if an ad is loaded successfully, or false if no ad is currently loaded. This can be done by using the network’s is-ad-available indication, if your network offers one, or by managing the ad’s status manually as part of LoadAd and ShowAd APIs.

public boolean isAdAvailable(AdData adData) {
   return isAdAvailable;
}

Show an rewarded video ad

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

public void showAd(AdData adData, RewardedVideoAdListener rewardedVideoAdListener) {
    
   // check your ad load status 
   if (isAdLoaded)  {
      // show your ad       
 
   } else {
      AdapterErrors adapterErrorCode = AdapterErrors.<ERROR CODE>;
      String adapterErrorMsg = “ERROR MESSAGE”;      rewardedVideoAdListener.onAdShowFailed(adatperErrorCode, adapterErrorMsg);
   }
}

Report the RewardedVideoAdListener callbacks

Make sure to override RewardedVideoAdListener’s callbacks according to the network’s functionality. Reporting the callbacks 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 rewarded video ad was loaded successfully 
void onAdLoadSuccess();
// The rewarded video ad failed to load. Use ironSource ErrorTypes (No Fill / Other) 
void onAdLoadFailed(@NotNull AdapterErrorType adapterErrorType, int errorCode, @Nullable String errorMessage);
// The rewarded video ad is displayed successfully to the user. This indicates an impression on the ironSource platform.  
void onAdOpened();
// User closed the rewarded video ad
void onAdClosed();
// The ad could not be displayed 
void onAdShowFailed(int errorCode, @Nullable String errorMessage);
// The ad was rewarded successfully 
void onAdRewarded(); 

Optional callbacks:

// Indicates an ad was clicked 
void onAdClicked();
// Indicates an ad was displayed on foreground 
void onAdVisible();
// Indicates an ad playable started 
void onAdStarted();
// Indicates an ad playable ended
void onAdEnded();

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 platform. These values will be available for you in run-time via the AdData object. 

The AdData 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, LoadAd, ShowAd, and isAdAvailable APIs.

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

// Get Publisher setup parameters 
final String appLevelParam1 = adData.getString(<YourAppLevelParam1>);
final String instanceLevelParam1 = adData.getString(<YourInstanceLevelParam1>);
final String instanceLevelParam2 = adData.getString(<YourInstanceLevelParam2>);

Use ironSource error codes and error types

Error type

This is relevant for onAdLoadFailed callback.

Error codes

These error codes are relevant for onAdLoadFailed and onAdShowFailed callbacks. 

Debug your adapter (optional)

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

public class <YourNetworkName>CustomAdapter extends BaseAdapter {
   @Override 
   public void setAdapterDebug(boolean adapterDebug) {
      this.adapterDebug = adapterDebug;
   }
}