Skip to content
AppLovin

Building a Custom Adapter

You can write a custom adapter if you want to support an ad network that is not listed in the AppLovin MAX Mediation Matrix. The following instructions show you how to do this.

Android

Implement a subclass of com.applovin.mediation.adapters.MediationAdapterBase. This subclass enables the interface between your mediation adapter and the AppLovin MAX SDK. That interface handles various functions of your SDK, including initialization, versioning, and resource cleanup.

  1. Create a subclass of MediationAdapterBase in the com.applovin.mediation.adapters package of your application. The name of this class should contain the network name (for example, com.mycompanyname.MyNetworkMediationAdapter).
  2. Override the initialize(final MaxAdapterInitializationParameters parameters, final Activity activity, final OnCompletionListener onCompletionListener) method. Implement code that initializes your ad network SDK. If you need to access the app ID set in the UI, you can do so via parameters.getServerParameters().getString( "app_id", null );. This logic executes in parallel with the initialization of the AppLovin SDK. Call onCompletionListener.onCompletion() after you initialize the ad network, and pass that completion handler one of the following values:
    • While the ad network SDK is initializing: InitializationStatus.INITIALIZING
    • If the ad network SDK initializes successfully: InitializationStatus.INITIALIZED_SUCCESS
    • If the ad network SDK fails to initialize: InitializationStatus.INITIALIZED_FAILURE (with a relevant error message)
    • If the ad network SDK does not have an initialization callback status: InitializationStatus.DOES_NOT_APPLY
    • If the ad network explicitly initialized, but without a status: InitializationStatus.INITIALIZED_UNKNOWN
  3. Override the getSdkVersion() method. Implement code that returns the network SDK version string from that method.
  4. Override the getAdapterVersion() method. Implement code that returns the version number of the mediation adapter from that method. All of AppLovin’s adapters use a five-number versioning scheme: The leftmost four numbers correspond to the network SDK version. The last number denotes the minor version number, which refers to the adapter release.
  5. Override the onDestroy() method. Implement the clean-up logic for the network SDK objects in that method.

Banner Ads

  1. Implement the MaxAdViewAdapter interface in your com.mycompanyname.MyNetworkMediationAdapter class.
  2. Override the loadAdViewAd() method which requests an ad. Call the parameters.getThirdPartyAdPlacementId() method to get the placement ID you need for your ad logic.
  3. Call the appropriate MaxAdViewAdapterListener methods. They notify the AppLovin MAX SDK about banner lifecycle events:
    • When an ad loads successfully, call MaxAdViewAdapterListener.onAdViewAdLoaded().
    • When an ad load fails, call MaxAdViewAdapterListener.onAdViewAdLoadFailed() with an appropriate MaxAdapterError.
    • Optionally, call the following banner lifecycle event notifications as appropriate: onAdViewAdClicked(), onAdViewAdCollapsed(), onAdViewAdDisplayed(), onAdViewAdDisplayFailed(), onAdViewAdExpanded(), onAdViewAdHidden().

Interstitials

  1. Implement the MaxInterstitialAdapter interface in your com.mycompanyname.MyNetworkMediationAdapter class.
  2. Override the loadInterstitialAd() method which requests an ad. Call the parameters.getThirdPartyAdPlacementId() method to get the placement ID you need for your ad logic.
  3. Override the showInterstitialAd() method which shows the loaded ad. Call the parameters.getThirdPartyAdPlacementId() method to get the placement ID you need for your ad logic. If the ad is not ready, call MaxInterstitialAdapterListener.onInterstitialAdDisplayFailed( MaxAdapterError.AD_NOT_READY ).
  4. Call the appropriate MaxInterstitialAdapterListener methods. They notify the AppLovin MAX SDK about interstitial lifecycle events:
    • When an ad loads successfully, call MaxInterstitialAdapterListener.onInterstitialAdLoaded().
    • When an ad load fails, call MaxInterstitialAdapterListener.onInterstitialAdLoadFailed() with an appropriate MaxAdapterError.
    • When an ad is hidden, call MaxInterstitialAdapterListener.onInterstitialAdHidden().
    • Optionally, call the following interstitial lifecycle event notifications as appropriate: onInterstitialAdClicked(), onInterstitialAdDisplayFailed().

Rewarded Ads

  1. Implement the MaxRewardedAdapter interface in your com.mycompanyname.MyNetworkMediationAdapter class.
  2. Override the loadRewardedAd() method which requests an ad. Call the parameters.getThirdPartyAdPlacementId() method to get the placement ID you need for your ad logic.
  3. Override the showRewardedAd() method which shows the loaded ad. Call the parameters.getThirdPartyAdPlacementId() method to get the placement ID you need for your ad logic. If the ad is not ready, call MaxRewardedAdapterListener.onRewardedAdDisplayFailed( MaxAdapterError.AD_NOT_READY ).
  4. Call the appropriate MaxRewardedAdapterListener methods. They notify the AppLovin MAX SDK about rewarded video lifecycle events:
    • When an ad loads successfully, call MaxRewardedAdapterListener.onRewardedAdLoaded().
    • When an ad load fails, call MaxRewardedAdapterListener.onRewardedAdLoadFailed() with an appropriate MaxAdapterError.
    • When an ad starts playing, call MaxRewardedAdapterListener.onRewardedAdDisplayed().
    • If a reward should be presented to the user, call MaxRewardedAdapterListener.onUserRewarded() with an appropriate MaxReward amount and currency. If no amount is available, default to MaxReward.DEFAULT_AMOUNT. AppLovin recommends that you call this immediately before MaxRewardedAdapterListener.onRewardedAdHidden().
    • When an ad is hidden, call MaxRewardedAdapterListener.onRewardedAdHidden().
    • Optionally, call the following rewarded video lifecycle event notification as appropriate: onRewardedAdClicked().

Native Ads

  1. Implement the MaxNativeAdAdapter interface in your com.mycompanyname.MyNetworkMediationAdapter class.
  2. Override the loadNativeAd() method which requests an ad.
  3. Call the appropriate MaxNativeAdAdapterListener methods. They notify the AppLovin MAX SDK about native ad lifecycle events:
    • When an ad loads successfully, call MaxNativeAdAdapterListener.onNativeAdLoaded().
    • When an ad load fails, call MaxNativeAdAdapterListener.onNativeAdLoadFailed() with an appropriate MaxAdapterError.
    • When an ad displays, call MaxNativeAdAdapterListener.onNativeAdDisplayed().
    • When the user clicks on an ad, call MaxNativeAdAdapterListener.onNativeAdClicked().

Privacy

MAX offers three boolean flags that indicate whether the user provides privacy consent. They are Boolean objects. Their value is null if the user has indicated neither consent or no consent. The parameters object is passed into each method. To obtain the value of the privacy flags, use the following methods of the parameters object:

MaxAdapterParameters.hasUserConsent()
for the GDPR consent flag. To determine if GDPR applies to the user, read the Platform > Overview > Privacy page of this documentation.
MaxAdapterParameters.isDoNotSell()
for the multi-state targeted advertising consent flag. AppLovin does not have an API that indicates whether the user belongs in a region to which this applies.
MaxAdapterParameters.isAgeRestrictedUser()
for the COPPA flag

iOS

Implement a subclass of ALMediationAdapter. This subclass enables the interface between your mediation adapter and the AppLovin MAX SDK. That interface handles various functions of your SDK, including initialization, versioning, and resource cleanup.

  1. Create a .m and .h extending from ALMediationAdapter in your project. The name of this class should contain the network name (for example, MyNetworkMediationAdapter).
  2. Implement the - (void)initializeWithParameters:(id<MAAdapterInitializationParameters>)parameters completionHandler:(void (^)(MAAdapterInitializationStatus NSString *_Nullable))completionHandler method Implement code that initializes your ad network SDK. If you need to access the app ID set in the UI, you can do so by means of parameters.serverParameters[@"app_id"]. This logic executes in parallel with the initialization of the AppLovin SDK. Call completionHandler after you initialize the ad network, and pass that handler one of the following values:
    • While the ad network SDK is initializing: MAAdapterInitializationStatusInitializing
    • If the ad network SDK initializes successfully: MAAdapterInitializationStatusInitializedSuccess
    • If the ad network SDK fails to initialize: MAAdapterInitializationStatusInitializedFailure (with a relevant error message)
    • If the ad network SDK does not have an initialization callback status: MAAdapterInitializationStatusDoesNotApply (with null as the error message)
    • If the ad network explicitly initialized, but without a status: MAAdapterInitializationStatusInitializedUnknown
  3. Implement the - (NSString *)SDKVersion method. Implement code that returns the network SDK version string from that method.
  4. Implement the - (NSString *)adapterVersion method. Implement code that returns the version number of the mediation adapter from that method. All of AppLovin’s adapters use a five-number versioning scheme: The leftmost four numbers correspond to the network SDK version. The last number denotes the minor version number, which refers to the adapter release.
  5. Implement the - (void)destroy method. Implement clean-up logic for the network SDK objects in that method.

Banner Ads

  1. Implement the MAAdViewAdapter protocol in your MyNetworkMediationAdapter class.
  2. Implement the - (void)loadAdViewAdForParameters:(id<MAAdapterResponseParameters>)parameters adFormat:(MAAdFormat *)adFormat andNotify:(id<MAAdViewAdapterDelegate>)delegate method which requests an ad. Call the parameters.thirdPartyAdPlacementIdentifier method to get the Placement ID you need for your ad logic.
  3. Call the appropriate MAAdViewAdapterDelegate methods. They notify the AppLovin MAX SDK about banner lifecycle events:
    • When an ad loads successfully, call -[MAAdViewAdapterDelegate didLoadAdForAdView].
    • When an ad load fails, call -[MAAdViewAdapterDelegate didFailToLoadAdViewAdWithError:] with an appropriate MAAdapterError.
    • Optionally, call the following banner lifecycle event notifications as appropriate: didClickAdViewAd, didCollapseAdViewAd, didDisplayAdViewAd, didExpandAdViewAd, didFailToDisplayAdViewAdWithError, didHideAdViewAd.

Interstitials

  1. Implement the MAInterstitialAdapter protocol in your MyNetworkMediationAdapter class.
  2. Declare the - (void)loadInterstitialAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MAInterstitialAdapterDelegate>)delegate method which requests an ad. Call the parameters.thirdPartyAdPlacementIdentifier method to get the placement ID you need for your ad logic.
  3. Declare the - (void)showInterstitialAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MAInterstitialAdapterDelegate>)delegate method which shows the loaded ad. Call the parameters.thirdPartyAdPlacementIdentifier method to get the placement ID you need for your ad logic. If the ad is not ready, call -[MAInterstitialAdapterDelegate didFailToDisplayInterstitialAdWithError: MAAdapterError.adNotReady].
  4. Call the appropriate MAInterstitialAdapterDelegate methods. They notify the AppLovin MAX SDK about interstitial lifecycle events:
    • When an ad loads successfully, call -[MAInterstitialAdapterDelegate didLoadInterstitialAd:].
    • When an ad load fails, call -[MAInterstitialAdapterDelegate didFailToLoadInterstitialAdWithError:] with an appropriate MAAdapterError.
    • When an ad displays successfully, call -[MAInterstitialAdapterDelegate didDisplayInterstitialAd].
    • When an ad is hidden, call -[MAInterstitialAdapterDelegate didHideInterstitialAd:].
    • Optionally, call the following interstitial lifecycle event notifications as appropriate: didClickInterstitialAd, didFailToDisplayInterstitialAdWithError.

Rewarded Ads

  1. Implement the MARewardedAdapter protocol in your MyNetworkMediationAdapter class.
  2. Declare the - (void)loadRewardedAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MARewardedAdapterDelegate>)delegate; method which requests an ad. Call the parameters.thirdPartyAdPlacementIdentifier method to get the placement ID you need for your ad logic.
  3. Declare the - (void)showRewardedAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MARewardedAdapterDelegate>)delegate; method which shows the loaded ad. Call the parameters.thirdPartyAdPlacementIdentifier method to get the placement ID you need for your ad logic. If the ad is not ready, call -[MARewardedAdapterDelegate didFailToDisplayRewardedAdWithError: MAAdapterError.adNotReady].
  4. Call the appropriate MARewardedAdapterDelegate methods. They notify the AppLovin MAX SDK about rewarded video lifecycle events:
    • When an ad loads successfully, call -[MARewardedAdapterDelegate didLoadRewardedAd:].
    • When an ad load fails, call -[MARewardedAdapterDelegate didFailToLoadRewardedAdWithError:] with an appropriate MAAdapterError.
    • When an ad starts playing, call -[MARewardedAdapterDelegate didDisplayRewardedAd:].
    • If a reward should be presented to the user, call -[MARewardedAdapterDelegate didRewardUserWithReward:] with an appropriate MAReward amount and currency. If no amount is available, default to MAReward.defaultAmount. AppLovin recommends that you call this immediately before -[MARewardedAdapterDelegate didHideRewardedAd:].
    • When an ad is hidden, call -[MARewardedAdapterDelegate didHideRewardedAd:].
    • Optionally, call the following rewarded video lifecycle event notification as appropriate: didClickRewardedInterstitialAd.

Native Ads

  1. Implement the MANativeAdAdapter protocol in your MyNetworkMediationAdapter class.
  2. Implement the - (void)loadNativeAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MANativeAdAdapterDelegate>)delegate; method which requests an ad.
  3. Call the appropriate MANativeAdAdapterDelegate methods. They notify the AppLovin MAX SDK about native ad lifecycle events:
    • When an ad loads successfully, call -[MANativeAdAdapterDelegate didLoadAdForNativeAd:].
    • When an ad load fails, call -[MANativeAdAdapterDelegate didFailToLoadNativeAdWithError:] with an appropriate MAAdapterError.
    • When an ad displays, call -[MANativeAdAdapterDelegate didDisplayNativeAdWithExtraInfo:].
    • When the user clicks on an ad, call -[MANativeAdAdapterDelegate didClickNativeAd:].

Privacy

MAX offers three boolean flags that indicate whether the user provides privacy consent. They are NSNumber objects. Their value is nil if the user has indicated neither consent or no consent. The parameters object is passed into each method. To obtain the value of the privacy flags, use the following APIs of the parameters object:

-[MAAdapterParameters hasUserConsent]
for the GDPR consent flag. To determine if GDPR applies to the user, read the Platform > Overview > Privacy page of this documentation.
-[MAAdapterParameters isDoNotSell]
for the multi-state targeted advertising consent flag. AppLovin does not have an API that indicates whether the user belongs in a region to which this applies.
-[MAAdapterParameters isAgeRestrictedUser]
for the COPPA flag

Testing

You can test your custom adapter by using the MAX Demo App and the Mediation Debugger (see Platform > Testing Networks). To get an ad request easily, raise the CPM of your placement in the waterfall.

Troubleshooting

If your custom adapter does not appear to be included in the waterfall as you expect, use the following troubleshooting checklist:

  1. Disable Test Mode (see Platform > Testing Networks > Test Mode)
  2. Make sure that the app package name, ad unit, and SDK key all match.
  3. Test with a physical device.
  4. Set the CPM of the custom network high enough that it has a high chance of winning in the waterfall.
Copyright © 2024 AppLovin
Terms | Privacy | Support | EULA | DMCA