Integrating Custom Networks

This section gives you step-by-step instructions to show you how you enable a custom SDK network as an ad network.

Step 1. Add Custom SDK Network Settings

In the MAX Dashboard, select MAX > Mediation > Manage > Networks. Then click Click here to add a Custom Network at the bottom of the page. The Create Custom Network page appears. Add the information about your custom network:

Network Type

Choose SDK.

Name

Type in the name of your custom network.

iOS Adapter Class Name

Type in the class name of your custom network adapter class (for example, TestMediationAdapter).

Android Adapter Class Name

Type in the fully-qualified class name of your custom network adapter class (for example, com.applovin.mediation.TestMediationAdapter).

Step 2. Enable the Custom SDK Network

Open MAX > Mediation > Manage > Ad Units in the MAX dashboard and select an ad unit for which you want to add the custom SDK network that you created in the previous step. Select which custom network you want to enable and enter the information for each placement. Refer to the network documentation to see what values you need to set for the App ID, Placement ID, and Custom Parameters.

This section gives you best practices and step-by-step instructions to show you how you enable a custom JS tag network as an ad network.

Custom Networks that leverage JS tags are not eligible to serve in regions where GDPR and CCPA are applicable.

Best Practices

MAX has no visibility into third-party code developed by other networks. For this reason, the process by which you integrate JS Tags provided by third-party networks is a complex one. When you work with third-party networks to do a custom network integration, AppLovin strongly recommends that you follow the best practices listed below:

• Place JS tag networks as low as possible in your waterfall to avoid reporting discrepancies between MAX and the JS network demand partner.
• Networks that count impressions on “load/request” when the ad is not on screen may observe discrepancies in impressions. To help minimize discrepancies between the numbers reported by MAX and by the third-party network, include the correct cache-busting macro in your JS tags (see “Cache Buster” in the Table of Macros below). If you don’t see a placeholder where you can add MAX’s cache-busting macro, it’s important that you check with the third-party network that provides the tag to learn how you should handle cache-busting. Any impression pixel that the AppLovin SDK traffics without a cache-busting method will result in discrepancies. The following is an example of a JS tag that includes a cache-busting macro:

  <script src="https://mobilecompany.com/js?id=418772&sizes=320x50&bundle=%%BUNDLE%%&ifa=%%ADVERTISING_ID_IFA%%&ifv=%%ADVERTISING_ID_IFV%%&lat=%%LATITUDE%%&lon=%%LONGITUDE%%&lltype=2&dnt=%%DNT%%&dnt=%%DNT%%&cb=%%CACHEBUSTER%%"></script>

• The failover tag can only be used by custom JS tag networks in the AppLovin SDK. When an ad network experiences timeouts or it does not have an eligible ad to show (no fill), it must properly call MAX’s failover tag. Implement the failover tag properly so that AppLovin’s ad server can call the next item in the waterfall based on priority (see How the Failover Tag Works below).

  If the ad network cannot implement the failover tag on its end, move that network to the end of your waterfall so that you will avoid issues with fill rate and revenue loss for the ad unit.

• Call the MAX failover tag synchronously, before you render any other content. If the JS Tag does not implement the failover tag properly, you may experience impression discrepancies and problems with the delivery of budgeted line items.
• Use a maximum of two tags, to minimize possible adverse downstream effects of using this method.
• Impression discrepancies are expected due to the nature of this integration. AppLovin recommends that you discount the CPMs that you enter in the MAX ad unit page to account for the impression difference.

If the HTML that the JS Tag generates includes a hyperlink (<a href…>) or a window.location redirect, the AppLovin SDK automatically tracks clicks and invokes a click event the first time the user clicks on the ad.

You cannot show MRAID ads by means of JS tags. The JS tag will serve, but MRAID will not run. Your JS tag should check for MRAID APIs before trying to use them, and should failover gracefully in their absence. Otherwise, this will likely result in a JS error and MAX will log this as an impression, resulting in possible discrepancies.

How the Load Success Tag Works

This is the MAX load success tag:

<script type="text/javascript" charset="utf-8">
  window.location="applovin://load";
</script>

When you call this load success tag, it loads in the webview and redirects the webview to the custom URI of applovin://load. This tells MAX that the ad source had an ad to show so MAX can notify the publisher that the ad is ready for display.

How the Failover Tag Works

This is the MAX failover tag:

<script type="text/javascript" charset="utf-8">
  window.location="applovin://failLoad";
</script>

When you call this failover tag, it loads in the webview and redirects the webview to the custom URI of applovin://failLoad. This tells MAX that the ad source had no ad to show and so MAX can fail over to the next source.

Step 1. Update the Network Tag

Contact the network to issue a JS tag. You can update the tag scheduled in the MAX Network section with the supported macros in the table below.

Step 2. Set Up a Custom Network

1. Go to MAX > Mediation > Manage > Networks and click Click here to add a Custom Network.
   
2. Enter the network name and copy and paste the JS tag in the Custom Network Tag field for each ad format.
   
3. Click ✓ Save.

Step 3. Enable the Custom Network in Your MAX Account

1. Go to MAX > Mediation > Manage > Ad Units and select an ad unit where you want to add the custom network that you created in the MAX Manage Networks section in Step 2.
2. Enter the Placement ID/Name and CPM Price, and set Country Targeting as needed.
   
3. Click ✓ Save.

To enable JS tag Bidding in MAX Mediation, you do not need the JS tag App ID and Zone IDs that are associated with the app you created.

Zone IDs/Placement IDs are placeholders for Custom Networks. Use these for reporting. You can create multiple Zone IDs in order to add the same custom network at different price points. Use relevant macros for accurate reporting. Due to the nature of this integration, discrepancies are expected. Please work with your network account manager if you have any questions.