AdColony

If you plan to use the MoPub SDK to load and display ads from AdColony via mediation, use this article for integration instructions and information unique to the ad network. To learn more about how MoPub mediation works, refer to our MoPub Network Mediation article.

Supported Ad Formats

AdColony currently supports the following ad formats. For support information, visit the AdColony homepage.

MoPub Formats AdColony Ad Formats
Banner Banner
Medium Rectangle Medium Rectangle
Interstitial Interstitial
Rewarded Ad Rewarded Video

Download and Integrate

To download the AdColony adapters, navigate to the Mediation Integration Tool. You must also download the AdColony SDK:

  • Download AdColony SDK for iOS

  • Download AdColony SDK for Android

    For Android, AdColony adapters are released as an Android Archive (AAR) file starting with version 3.3.8.1. The AAR includes the required Manifest data for AdColony. As a result, you no longer need to update your AndroidManifest manually for any generic data, such as permissions and Activities. Any other app-level placement configuration required by AdColony must be manually entered into the AndroidManifest.

For the latest download and integration instructions, consult AdColony’s tutorials before you integrate the SDK and adapters.

Set Up AdColony on the MoPub Dashboard

  • App ID and Zone ID are required. Each Zone ID must be unique per MoPub ad unit.

  • No field is provided for allZoneIds, but allZoneIds will be passed to the AdColony adapters. They will contain all of the Zone ID entries for that app.

  • clientOptions is optional and only applicable on Android.

Network Reporting and Auto CPM

The following setup is required to take advantage of Auto CPM. To enable AdColony network reporting and Auto CPM:

  1. Navigate to the MoPub UI’s Networks tab. (Refer to these additional instructions that provide more detail for the remaining steps.)

  2. In the Network settings page for AdColony:

    • enable reporting access

    • provide the API Key

      To find the API Key, in AdColony, navigate to Settings and look for Read-Only API Key.

      Ad Colony Reporting

  3. Navigate to the Auto CPM preferences page and turn on Auto CPM.

Migrate AdColony from Custom Native Setup

  1. Transfer the App IDs and Zone IDs (if applicable) from the old custom native connection to the supported AdColony instance.

  2. MoPub will initiate the following AdColony mediation adapter class names to render the ads:

    • iOS

      • AdColonyBannerCustomEvent
      • AdColonyInterstitialCustomEvent
      • AdColonyRewardedVideoCustomEvent
    • Android

      • com.mopub.mobileads.AdColonyBanner
      • com.mopub.mobileads.AdColonyInterstitial
      • com.mopub.mobileads.AdColonyRewardedVideo

    If you are manually entering these class names, migrate to the new network setup and pause the Custom Native Network. If you are using your own mediation adapter class names, make sure that both the old custom native network and the new AdColony network UI are set up for backward compatibility.

Important: During migration, make sure the custom native network and the AdColony network are not both live at the same time, because this may impact your revenue.

Test an Ad

We recommend that you test your AdColony integration using MoPub mediation test mode to verify that the adapter works as expected. Test mode must be set up on both the MoPub side and the AdColony side.

Set Up Test Mode on the MoPub Side

Refer to our Mediation Test Mode article for complete details on using this mode.

Set Up Test Mode on the AdColony Side

AdColony supports test mode in its UI. For AdColony, you can enable test mode at the zone level. We recommend that you create new zones to use specifically for testing. Scroll down to “Step 3: Toggle Test Ads” in this section of AdColony docs for instructions on using the test mode in the AdColony UI.

Early Initialization to Test Advanced Bidding

To test Advanced Bidding, AdColony requires that you initialize the network SDK early (before the MoPub SDK even), and that you initialize it manually, without waiting for the MoPub server to trigger AdColony to initialize. To do this, you must include the AdColony-specific Application ID key in your initialization code for both iOS and Android, as well as for Unity Prefabs.

If your AdColony test environment is under a different Application ID key, then you must update these test keys in your initialization code for iOS, Android, and Unity Prefabs before you test, so that AdColony initializes not only for your production account details, but for your testing account details as well. (This is not a concern if you use the same Application ID for your AdColony production and testing environments.)

Initialization Network Configuration

AdColony requires your App Id and Zone Ids information to successfully initialize. This can be done on the spot on first ad request (also called lazy initialization), or during MoPub initialization, which will ensure AdColony initializes early on. If you’re initializing MoPub manually or using AdColony for Advanced Bidding, this is important to follow.

- iOS:

  • v4.3.0.2 and newer: You can enter your App Id (appId) as a String parameter, and all your Zone Ids (allZoneIds) as an NSArray. Example below:

      // Your MoPub SDK initialization code
      let sdkConfig = MPMoPubConfiguration(adUnitIdForAppInitialization: YOUR_MOPUB_AD_UNIT_ID)
      sdkConfig.mediatedNetworkConfigurations = [String(describing: AdColonyAdapterConfiguration.self):
      ["appId": "YOUR_AD_COLONY_APP_ID", "allZoneIds" : ["ZONE_ID_1","ZONE_ID_2","ZONE_ID_3"]]]
    
  • Below 4.3.0.2: You can enter your App Id (appId) as a String parameter, and all your Zone Ids (allZoneIds) as a string of JSON Array. Example below:

      // Your MoPub SDK initialization code
      let sdkConfig = MPMoPubConfiguration(adUnitIdForAppInitialization: YOUR_MOPUB_AD_UNIT_ID)
      sdkConfig.mediatedNetworkConfigurations = [String(describing: AdColonyAdapterConfiguration.self):
      ["appId": "YOUR_AD_COLONY_APP_ID", "allZoneIds" : "{\"zoneId\": \"ZONE_ID_1\", \"zoneId\": \"ZONE_ID_2\"}"]]
    

- Android:

  • You can enter your App Id (appId) as a String parameter, and all your Zone Ids (allZoneIds) as a String Array. Example below:

      // Your MoPub SDK initialization code
      final SdkConfiguration.Builder configBuilder = new SdkConfiguration.Builder("YOUR_MOPUB_AD_UNIT_ID");
      Map<String, String> adColonyConfigs = new HashMap<>();
      adColonyConfigs.put("appId", "YOUR_AD_COLONY_APP_ID");
      String[] allZoneIds = new String[]{"ZONE_ID_1", "ZONE_ID_2"};
      adColonyConfigs.put("allZoneIds", Arrays.toString(allZoneIds));
      configBuilder.withMediatedNetworkConfiguration(AdColonyAdapterConfiguration.class.getName(), adColonyConfigs);
    

- Unity:

  • Using MoPubManager Prefab Ensure you attach AdColony Network Configuration script to your MoPub Manager Prefab, enable the script, and populate the App Id and Zone Id information. Please see the “Network Configuration (Mediation)” topic here for an example.

  • Manual Initialization:

      MoPub.InitializeSdk(new MoPub.SdkConfiguration {
              // Define the AdColony app and zone IDs you want to initialize with
              MediatedNetworks = new MoPub.MediatedNetwork[]
              {
                   new MoPub.SupportedNetwork.AdColony
                   {
                        NetworkConfiguration = new Dictionary<string,object> {
                             { "appId", "YOUR_APP_ID_STRING" },
                             { "allZoneIds", "[\"YOUR_ZONE_ID_1\",\"YOUR_ZONE_ID_2\"]" }
                        },
                   },
              },
         });
    

Advanced Bidding Requirements

There are two requirements for AdColony Advanced Bidding:

  1. Pre-initialization of AdColony before and outside of MoPub SDK initialization.
  2. Adding required Google Play services dependencies (Android only).

1- Pre-initialization of AdColony

In order to properly generate an Advanced Bidding Token and have AdColony ad server bid on Advanced Bidding ad requests, the AdColony SDK needs to be initialized before the MoPub SDK. Follow the below steps to do that:

  • iOS:
    1. Just before where you call MoPub SDK Initialization, define your AdColony related configuration details:
         NSString * appId = @"your_app_id";
         NSArray  * allZoneIds = [NSArray arrayWithObjects:@"ZONE_ID_1",@"ZONE_ID_2"]; // And all your other zoneIds
         NSString * userId = @"your_user_id"; // optional
      
    2. Call AdColony initialization method with the values you defined.
         // Initialize the AdColony SDK with the defined IDs
         [AdColonyController initializeAdColonyCustomEventWithAppId:appId allZoneIds:allZoneIds userId:userId callback:^{
      
             // Initialize the MoPub SDK
             [[MoPub sharedInstance] initializeSdkWithConfiguration:sdkConfig completion:^{
      
             }];
         }];
      
  • Android:

    1. Prior to the MoPub SDK initialization, define your AdColony configuration:
         String[] adColonyAllZoneIds = {"ZONE_ID_1", "ZONE_ID_2"};
         String adColonyAppId = "your_app_id";
      
    2. AdColony initialization also asks for AdColonyAppOptions as an input parameter. You can pass in an empty AdColonyAppOptions object. Alternatively, you can also call:
         AdColonyAppOptions adColonyAppOptions = AdColonyAdapterConfiguration.getAdColonyAppOptionsAndSetConsent("");
      

      This will generate an object for you without any client options. Note that on any ad request, MoPub AdColony adapters will pass in updated AdColonyAppOptions that will contain GDPR, Legitimate Interest and adapter version details.

    3. Call AdColony initialization method:
         AdColony.configure(getApplicationContext(), adColonyAppOptions, adColonyAppId, adColonyAllZoneIds);
      
    4. AdColony’s Android SDK initialization method does not have a callback. If you observe problems of AdColony initialization, you can address this problem by adding a few seconds wait time after calling AdColony initialization. You can adjust this amount through trial and error.

    5. Continue with your MoPub initialization code by preparing your MoPub SDK configuration, and then by calling MoPub.initializeSdk. Note that you do not need to pass in Network Configuration details for AdColony again explained here.
  • Unity: Please apply the Initialization Network Configuration requirements for Unity described here.

2- Adding required Google Dependencies (Android Only)

On Android, AdColony SDK depends on Google Play services dependencies to collect the Advertising ID. Without this identifier, the AdColony ad server cannot bid on Advanced Bidding requests. Refer to additional AdColony documentation.

The following dependency must be installed on your Android (and Unity to Android) projects:

  • com.google.android.gms.play-services-ads

Failure to include this dependency would produce this log statement:

  W/AdColony [WARNING]: Google Play Services ads dependencies are missing. Collecting Android ID instead of Advertising ID.

If you see this log statement, please ensure you add the Google dependencies correctly. If you’re still having issues, check your device’s Advertising settings to see if limit ad tracking is off.

Important Notes:

  • If you already have Google Play Services or AdMob installed in your project, then you don’t need to add this dependency.
  • Adding play-services-ads will also require you to follow an additional step to update your AndroidManifest.xml, see here for details.
  • Advertising ID value is not obtained if the user opts out of ads personalization and limits ad tracking. In this case, AdColony ad server will not bid on Advanced Bidding requests.

Additional Support

For inquiries and support, email AdColony at support@adcolony.com.


Last updated March 30, 2021

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2021 MoPub (a division of Twitter, Inc.)