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.

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();

Add support for banner ad unit

Step 1. Create banner ad unit class

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

Step 2. Implement ad unit constructor

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

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

Banner Sizes

See the table below for details about our supported banner sizes. Custom networks may support any combination of these sizes. The banner size will be received as a param as part of the loadAd API. 

When the banner size received is SMART, make sure to change the size either to BANNER or LEADERBOARD, according to the device screen sizes (see instructions below).

Step 3. Request a banner ad

Implement the loadAd API to allow publishers to request banner ads from your network. The AdData will allow you to access the publisher’s input and receive the ad identifiers, and the ISBannerSize will indicate the requested banner size.

public void loadAd(@NotNull AdData adData, @NotNull Activity activity, @NotNull ISBannerSize bannerSize, @NotNull BannerAdListener bannerAdListener) {
 // Load your ad     
}

Step 4. Destroy banner

ironSource requires app developers to destroy a banner ad by implementing the following destroyAd method.

 public void destroyAd(@NotNull AdData adData) {
    }

Step 5. Report the BannerAdListener callbacks

Report the BannerAdListener’s callbacks according to the network’s functionality. This will ensure the network’s performance data to be reflected correctly in the ironSource platform. 

Mandatory callbacks:

// Indicates that a banner ad was loaded successfully 
void onAdLoadSuccess(@NotNull View adView, @NotNull FrameLayout.LayoutParams frameLayoutParams) 
// The banner ad failed to load. Use ironSource ErrorTypes (No Fill / Other) 
void onAdLoadFailed(@NotNull AdapterErrorType adapterErrorType, int errorCode, @Nullable String errorMessage)
// The banner ad is displayed successfully to the user. This indicates an impression on the ironSource platform.  
void onAdOpened()
// Indicates an ad was clicked 
void onAdClicked()

Optional callbacks:

//Should be invoked after a click, and before the user is taken out of the app 
void onAdLeftApplication()
// Should be invoked after the ad view presents fullscreen content
void onAdScreenPresented()
// Should be invoked after the fullscreen content is dismissed
void onAdScreenDismissed()  

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;
   }
}