You can write a custom adapter if you want to support an ad network that is not listed in the AppLovin MAX Mediation Matrix.
-
Getting Started
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.- Create a subclass of
MediationAdapterBase
in thecom.applovin.mediation.adapters
package of your application. The name of this class should contain the network name (for example,com.mycompanyname.MyNetworkMediationAdapter
). - Override the
initialize(final MaxAdapterInitializationParameters parameters, final Activity activity, final OnCompletionListener onCompletionListener)
method and 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 ofparameters.getServerParameters().getString( "app_id", null );
. This logic executes in parallel with the initialization of the AppLovin SDK. CallonCompletionListener.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
- While the ad network SDK is initializing:
- Override the
getSdkVersion()
method and implement code that returns the network SDK version string from that method. - Override the
getAdapterVersion()
method and 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 and the last number denotes the minor version number which refers to the adapter release. - Override the
onDestroy()
method and implement the clean-up logic for the network SDK objects in that method.
Banner Ads
- Implement the
MaxAdViewAdapter
interface in yourcom.mycompanyname.MyNetworkMediationAdapter
class. - Override the
loadAdViewAd()
method which requests an ad. Call theparameters.getThirdPartyAdPlacementId()
method to get the placement ID you need for your ad logic. - Call the appropriate
MaxAdViewAdapterListener
methods to 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 appropriateMaxAdapterError
. - Optionally, make the following banner lifecycle events notification calls as appropriate:
onAdViewAdClicked()
,onAdViewAdCollapsed()
,onAdViewAdDisplayed()
,onAdViewAdDisplayFailed()
,onAdViewAdExpanded()
,onAdViewAdHidden()
.
- When an ad loads successfully, call
Interstitials
- Implement the
MaxInterstitialAdapter
interface in yourcom.mycompanyname.MyNetworkMediationAdapter
class. - Override the
loadInterstitialAd()
method which requests an ad. Call theparameters.getThirdPartyAdPlacementId()
method to get the placement ID you need for your ad logic. - Override the
showInterstitialAd()
method which shows the loaded ad. Call theparameters.getThirdPartyAdPlacementId()
method to get the placement ID you need for your ad logic. If the ad is not ready, callMaxInterstitialAdapterListener.onInterstitialAdDisplayFailed( MaxAdapterError.AD_NOT_READY )
. - Call the appropriate
MaxInterstitialAdapterListener
methods to 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 appropriateMaxAdapterError
. - When an ad is hidden, call
MaxInterstitialAdapterListener.onInterstitialAdHidden()
. - Optionally, make the following interstitial lifecycle events notification calls as appropriate:
onInterstitialAdClicked()
,onInterstitialAdDisplayFailed()
.
- When an ad loads successfully, call
Rewarded Ads
- Implement the
MaxRewardedAdapter
interface in yourcom.mycompanyname.MyNetworkMediationAdapter
class. - Override the
loadRewardedAd()
method which requests an ad. Call theparameters.getThirdPartyAdPlacementId()
method to get the placement ID you need for your ad logic. - Override the
showRewardedAd()
method which shows the loaded ad. Call theparameters.getThirdPartyAdPlacementId()
method to get the placement ID you need for your ad logic. If the ad is not ready, callMaxRewardedAdapterListener.onRewardedAdDisplayFailed( MaxAdapterError.AD_NOT_READY )
. - Call the appropriate
MaxRewardedAdapterListener
methods to 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 appropriateMaxAdapterError
. - When an ad starts playing, call
MaxRewardedAdapterListener.onRewardedAdDisplayed()
. - If a reward should be presented to the user, call
MaxRewardedAdapterListener.onUserRewarded()
with an appropriateMaxReward
amount and currency. If no amount is available, default toMaxReward.DEFAULT_AMOUNT
. AppLovin recommends that you call this immediately beforeMaxRewardedAdapterListener.onRewardedAdHidden()
. - When an ad is hidden, call
MaxRewardedAdapterListener.onRewardedAdHidden()
. - Optionally, make the following rewarded video lifecycle event notification call as appropriate:
onRewardedAdClicked()
.
- When an ad loads successfully, call
Native Ads
- Implement the
MaxNativeAdapter
interface in yourcom.mycompanyname.MyNetworkMediationAdapter
class. - Override the
loadNativeAd()
method which requests an ad. - Call the appropriate
MaxNativeAdapterListener
methods to notify the AppLovin MAX SDK about native ad lifecycle events:- When an ad loads successfully, call
MaxNativeAdapterListener.onNativeAdLoaded()
. - When an ad load fails, call
MaxNativeAdapterListener.onNativeAdLoadFailed()
with an appropriateMaxAdapterError
. - When an ad displays, call
MaxNativeAdapterListener.onNativeAdDisplayed()
. - When the user clicks on an ad, call
MaxNativeAdapterListener.onNativeAdClicked()
.
- When an ad loads successfully, call
Privacy
MAX offers three boolean flags represented by a
Boolean
object that indicates whether the user provides privacy consent (or that arenull
if the user has indicated neither consent or no consent). To obtain the value of these flags, use the following methods of theparameters
object passed into each method:MaxAdapterParameters.hasUserConsent()
- for the GDPR consent flag. You can find out about how to determine if GDPR applies to the user in the Privacy page of this documentation.
MaxAdapterParameters.isDoNotSell()
- for the multi-state targeted advertising consent flag. AppLovin currently does not have an API to indicate whether the user belongs in a region to which this applies.
MaxAdapterParameters.isAgeRestrictedUser()
- for the COPPA flag
- Create a subclass of
-
Getting Started
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.- Create a .m and .h extending from
ALMediationAdapter
in your project. The name of this class should contain the network name (for example,MyNetworkMediationAdapter
). - Implement the
- (void)initializeWithParameters:(id<MAAdapterInitializationParameters>)parameters completionHandler:(void (^)(MAAdapterInitializationStatus NSString *_Nullable))completionHandler
method and 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 ofparameters.serverParameters[@"app_id"]
. This logic executes in parallel with the initialization of the AppLovin SDK. CallcompletionHandler
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
(withnull
as the error message) - If the ad network explicitly initialized, but without a status:
MAAdapterInitializationStatusInitializedUnknown
- While the ad network SDK is initializing:
- Implement the
- (NSString *)SDKVersion
method and implement code that returns the network SDK version string from that method. - Implement the
- (NSString *)adapterVersion
method and 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 and the last number denotes the minor version number which refers to the adapter release. - Implement the
- (void)destroy
method and implement the clean-up logic for the network SDK objects in that method.
Banner Ads
- Implement the
MAAdViewAdapter
protocol in yourMyNetworkMediationAdapter
class. - Implement the
- (void)loadAdViewAdForParameters:(id<MAAdapterResponseParameters>)parameters adFormat:(MAAdFormat *)adFormat andNotify:(id<MAAdViewAdapterDelegate>)delegate
method which requests an ad. Call theparameters.thirdPartyAdPlacementIdentifier
method to get the Placement ID you need for your ad logic. - Call the appropriate
MAAdViewAdapterDelegate
methods to 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 appropriateMAAdapterError
. - Optionally, make the following banner lifecycle event notification calls as appropriate:
didClickAdViewAd
,didCollapseAdViewAd
,didDisplayAdViewAd
,didExpandAdViewAd
,didFailToDisplayAdViewAdWithError
,didHideAdViewAd
.
- When an ad loads successfully, call
Interstitials
- Implement the
MAInterstitialAdapter
protocol in yourMyNetworkMediationAdapter
class. - Declare the
- (void)loadInterstitialAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MAInterstitialAdapterDelegate>)delegate
method which requests an ad. Call theparameters.thirdPartyAdPlacementIdentifier
method to get the placement ID you need for your ad logic. - Declare the
- (void)showInterstitialAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MAInterstitialAdapterDelegate>)delegate
method which shows the loaded ad. Call theparameters.thirdPartyAdPlacementIdentifier
method to get the placement ID you need for your ad logic. If the ad is not ready, call-[MAInterstitialAdapterDelegate didFailToDisplayInterstitialAdWithError: MAAdapterError.adNotReady]
. - Call the appropriate
MAInterstitialAdapterDelegate
methods to 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 appropriateMAAdapterError
. - When an ad displays successfully, call
-[MAInterstitialAdapterDelegate didDisplayInterstitialAd]
. - When an ad is hidden, call
-[MAInterstitialAdapterDelegate didHideInterstitialAd:]
. - Optionally, make the following interstitial lifecycle event notification calls as appropriate:
didClickInterstitialAd
,didFailToDisplayInterstitialAdWithError
.
- When an ad loads successfully, call
Rewarded Ads
- Implement the
MARewardedAdapter
protocol in yourMyNetworkMediationAdapter
class. - Declare the
- (void)loadRewardedAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MARewardedAdapterDelegate>)delegate;
method which requests an ad. Call theparameters.thirdPartyAdPlacementIdentifier
method to get the placement ID you need for your ad logic. - Declare the
- (void)showRewardedAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MARewardedAdapterDelegate>)delegate;
method which shows the loaded ad. Call theparameters.thirdPartyAdPlacementIdentifier
method to get the placement ID you need for your ad logic. If the ad is not ready, call-[MARewardedAdapterDelegate didFailToDisplayRewardedAdWithError: MAAdapterError.adNotReady]
. - Call the appropriate
MARewardedAdapterDelegate
methods to 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 appropriateMAAdapterError
. - When an ad starts playing, call
-[MARewardedAdapterDelegate didDisplayRewardedAd:]
. - If a reward should be presented to the user, call
-[MARewardedAdapterDelegate didRewardUserWithReward:]
with an appropriateMAReward
amount and currency. If no amount is available, default toMAReward.defaultAmount
. AppLovin recommends that you call this immediately before-[MARewardedAdapterDelegate didHideRewardedAd:]
. - When an ad is hidden, call
-[MARewardedAdapterDelegate didHideRewardedAd:]
. - Optionally, make the following rewarded video lifecycle event notification call as appropriate:
didClickRewardedInterstitialAd
.
- When an ad loads successfully, call
Native Ads
- Implement the
MANativeAdAdapter
protocol in yourMyNetworkMediationAdapter
class. - Implement the
- (void)loadNativeAdForParameters:(id<MAAdapterResponseParameters>)parameters andNotify:(id<MANativeAdAdapterDelegate>)delegate;
method which requests an ad. - Call the appropriate
MANativeAdAdapterDelegate
methods to 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 appropriateMAAdapterError
. - When an ad displays, call
-[MANativeAdAdapterDelegate didDisplayNativeAdWithExtraInfo:]
. - When the user clicks on an ad, call
-[MANativeAdAdapterDelegate didClickNativeAd:]
.
- When an ad loads successfully, call
Privacy
MAX offers three boolean flags represented by an
NSNumber
object that indicates whether the user provides privacy consent (or that arenil
if the user has indicated neither consent or no consent). To obtain the value of these flags, use the following APIs of theparameters
object passed into each method:-[MAAdapterParameters hasUserConsent]
- for the GDPR consent flag. You can find out how to determine if GDPR applies to the user in the Privacy page of this documentation.
-[MAAdapterParameters isDoNotSell]
- for the multi-state targeted advertising consent flag. AppLovin currently does not have an API to indicate whether the user belongs in the relevant region.
-[MAAdapterParameters isAgeRestrictedUser]
- for the COPPA flag
- Create a .m and .h extending from
Testing
You can test your custom adapter by using the MAX Demo App and Mediation Debugger. To get an ad request easily, you can set the CPM of your placement in the waterfall higher.
Troubleshooting
If your custom adapter does not appear to be included in the waterfall as you expect, use the following checklist to fix the most common issues that might be causing this:
- Disable Test Mode.
- Make sure that the app package name, ad unit, and SDK key all match.
- Test with a physical device.
- Set the CPM of the custom network high enough that it has a high chance of winning in the waterfall.