Build a custom adapter for Android
Develop a custom adapter for Android to integrate your ad network into Unity LevelPlay mediation by creating a BaseAdapter and ad unit classes, handling SDK initialization, and managing ad logic.
読み終わるまでの所要時間 1 分最終更新 1日前
This document covers the steps to build a custom adapter and provide your publishers the resources required to integrate your network with ironSource mediation.
Prerequisites
- Complete the custom adapter registration form
- Make sure you have the following information available:
- Adapter package name
- Adapter class names
- Network configuration keys
- Download latest LevelPlay SDK here
- Min required LevelPlay SDK version is 7.1.13, for Rewarded Video and Interstitial ad units.
注
For Android and Unity developed projects, the minimum required LevelPlay SDK
version is 7.3.0 for banner ad unit
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 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. Use the package and interstitial class names you received from ironSource as part of the registration process.package com.ironsource.adapters.custom.[YourNetworkName];public class SampleCustomInterstitial extends BaseInterstitial<SampleCustomAdapter> implements SampleNetworkInterstitialAdListener {public class <YourNetworkName>CustomInterstitial extendsBaseInterstitial <<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
After 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 successfullyvoid 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 advoid onAdClosed();// The ad could not be displayedvoid 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 clickedvoid 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 adapterSampleCustomAdapter 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. Use the package and rewarded video class names you received from ironSource as part of the registration process.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;
public class SampleCustomRewardedVideo extends BaseRewardedVideo<SampleCustomAdapter> implements SampleNetworkRewardedVideoListener { // Add your adapter code here}
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
After 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 successfullyvoid 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 advoid onAdClosed();// The ad could not be displayedvoid onAdShowFailed(int errorCode, @Nullable String errorMessage);// The ad was rewarded successfullyvoid onAdRewarded();
Optional callbacks
// Indicates an ad was clickedvoid onAdClicked();// Indicates an ad was displayed on foregroundvoid onAdVisible();// Indicates an ad playable startedvoid onAdStarted();// Indicates an ad playable endedvoid onAdEnded();
Add support for banner ad unit (Android-developed apps only)
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. Use the package and banner class names you received from ironSource as part of the registration process.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
Refer to the following table 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 (refer to the following instructions).ISBannerSize | Description | Dimensions in dp (WxH) |
|---|---|---|
| BANNER | Standard Banner | 320 x 50 |
| LARGE | Large Banner | 320 x 90 |
| RECTANGLE | Medium Rectangular (MREC) | 300 x 250 |
| SMART | Smart Banner (Adjusted for both mobile and tablet) | If (screen width ≤ 720) 320 x 50 If (screen width > 720) 728 x 90 |
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) {}
注
If your network SDK does not support this kind of API, you should add an empty
implementation.
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
Define the values of the LayoutParams object passed to the onAdLoadSuccess callback by the network in the custom adapter. Below you can find the best practice:// Indicates that a banner ad was loaded successfullyvoid 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 clickedvoid onAdClicked()
- Pass the width and height of the actual banner size.
- Define gravity property as Gravity.CENTER.
Optional callbacks
//Should be invoked after a click, and before the user is taken out of the appvoid onAdLeftApplication()// Should be invoked after the ad view presents fullscreen contentvoid onAdScreenPresented()// Should be invoked after the fullscreen content is dismissedvoid onAdScreenDismissed()
Access publisher's input by using 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 by using 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 parametersfinal 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 type | Description |
|---|---|
| Used when there is no available ad to show |
| Used for any other reason reported by the network |
Error codes
These error codes are relevant for onAdLoadFailed and onAdShowFailed callbacks.Error code | Description |
|---|---|
| The action failed because some required information was not available when API was called |
| Use to indicate if the ad was expired |
| 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 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; }}