Integrate AdColony with mediation

This guide shows you how to use the Google Mobile Ads SDK to load and display ads from AdColony using mediation, covering both bidding and waterfall integrations. It covers how to add AdColony to an ad unit's mediation configuration, and how to integrate the AdColony SDK and adapter into an Android app.

Supported integrations and ad formats

The AdMob mediation adapter for AdColony has the following capabilities:

Integration
Bidding
Waterfall
Formats
Banner
Interstitial
Rewarded
Native

Requirements

• Android API level 21 or higher

• [For bidding]: AdColony adapter 3.3.10.1 or higher (latest version recommended)

• Latest Google Mobile Ads SDK

• Complete the mediation Get started guide

Step 1: Set up configurations in AdColony UI

注册并登录您的 AdColony 帐号。点击设置新应用按钮，将您的应用添加到 AdColony 发布商信息中心。

填写表单，然后点击页面底部的 Create（创建），以将您的应用添加到 AdColony。

创建应用后，您可以依次转到应用的基本应用信息部分下的创收 > 应用来获取应用 ID。

接下来，在应用页面的广告区域部分点击设置新的广告区域按钮，创建新的广告区域。我们建议您为中介创建一个新的广告区域 AdMob （即使您已有广告区域）。

如需了解有关创建广告展示位置的其他说明，请选择与首选广告格式对应的标签页。

横幅

1. 将区域是否有效？设置为是。

2. 为您的广告区域输入名称。

   

3. 选择横幅作为广告区域尺寸。

   

4. 输入“每日播放上限”的值。

   

插页式广告

1. 将区域是否有效？设置为是。

2. 为您的广告区域输入名称。

   

3. 选择前贴片广告/插页式广告作为区域类型。

   

4. 输入“每日播放上限”的值。

   

已奖励

1. 将区域是否有效？设置为是。

2. 为您的广告区域输入名称。

   

3. 选择值交换/V4VC 作为区域类型。

4. 将 Client Side Only? 设为 Yes，然后输入虚拟货币名称、每日最大视频数和奖励金额。

   注意 ：除非奖励值在 AdMob界面中被替换，否则此处指定的奖励值将由适配器转发。

   

5. 输入“每日播放上限”的值。

   

完成创建广告区域后，点击创建按钮。

创建广告区域后，您可以在广告区域的集成部分下找到区域 ID。该区域 ID 将在下一步中使用。

要点 ：对于出价集成，您必须与 AdColony 支持团队联系，为出价启用区域 ID。

找到您的 AdColony API 密钥

注意 ：这仅适用于广告瀑布流集成。如果您使用的是出价集成，则可以跳过此步骤。

出价

出价集成不需要执行此步骤。

瀑布

您需要使用 AdColony API 密钥来设置您的AdMob 广告单元 ID。前往 AdColony 发布商信息中心中的帐号设置，找到您的 API 密钥。

开启测试模式

如需在 AdColony 上启用测试广告，请转到 AdColony 信息中心，然后依次转到创收 > 应用。在应用的广告区域部分下，选择您要启用测试广告的区域。在开发部分下，选中是以只显示测试广告？即可启用测试广告。

要点 ：对于出价集成，在 AdColony 界面中启用测试模式后，AdColony 将仅对测试出价请求出价。为确保 AdColony 收到测试出价请求，您还必须针对 AdMob的广告请求启用测试设备。

Step 2: Set up AdColony demand in AdMob UI

Configure mediation settings for your ad unit

You need to add AdColony to the mediation configuration for your ad unit.

First, sign in to your AdMob account. Next, navigate to the Mediation tab. If you have an existing mediation group you'd like to modify, click the name of that mediation group to edit it, and skip ahead to Add AdColony as an ad source.

To create a new mediation group, select Create Mediation Group.

Enter your ad format and platform, then click Continue.

Give your mediation group a name, and select locations to target. Next, set the mediation group status to Enabled, and then click Add Ad Units.

Associate this mediation group with one or more of your existing AdMob ad units. Then click Done.

You should now see the ad units card populated with the ad units you selected:

Add AdColony as an ad source

Bidding

Under the Bidding card in the Ad Sources section, select Add Ad Source. Then select AdColony.

Click How to sign a partnership agreement and set up a bidding partnership with AdColony.

Click Acknowledge & agree, then click Continue.

If you already have a mapping for AdColony, you can select it. Otherwise, click Add mapping.

Next, enter the App ID and Zone ID obtained in the previous section. Then click Done.

Important: The App ID must be associated with the targeted app as in the AdColony UI.

Waterfall

Under the Waterfall card in the Ad Sources section, select Add Ad Source. Then select AdColony.

Select AdColony and enable the Optimize switch. Enter the API Key obtained in the previous section to set up ad source optimization for AdColony. Then enter an eCPM value for AdColony and click Continue.

Note: You only need to set up ad source optimization once per network.

If you already have a mapping for AdColony, you can select it. Otherwise, click Add mapping.

Next, enter the App ID and Zone ID obtained in the previous section. Then click Done.

Important: The App ID must be associated with the targeted app as in the AdColony UI.

Note: Ad source optimization takes a few days to gather enough data to accurately calculate eCPM for a mediation network. In the meantime, the ad source optimization status is PENDING, so you must manually set an eCPM value for the network. Once the eCPM can be calculated, the ad source automatically starts updating the eCPM on your behalf.

Add AdColony to GDPR and US state regulations ad partners list

Important: Verify that you have Account Management permission to complete the configuration for EU Consent and GDPR, CPRA, and User Messaging Platform. See Manage user access to your account for details.

Follow the steps in GDPR settings and US state regulations settings to add AdColony to the GDPR and US state regulations ad partners list in the AdMob UI.

Step 3: Import the AdColony SDK and adapter

Note: Failure to integrate the compatible AdColony and Google Mobile Ads SDK versions might lead to build issues.

Android Studio integration (recommended)

In your app-level build.gradle.kts file, add the following implementation dependencies and configurations. Use the latest versions of the AdColony SDK and adapter:

dependencies {
    implementation("com.google.android.gms:play-services-ads:23.0.0")
    implementation("com.google.ads.mediation:adcolony:4.8.0.2")
}

Migrate project to AndroidX

The AdColony SDK depends on Android support libraries but the latest Google Mobile Ads SDK uses Jetpack libraries.

To ensure the AdColony SDK and the Google Mobile Ads SDK are compatible, create a gradle.properties file in the top-level of your project, and add the following code:

android.useAndroidX=true
android.enableJetifier=true

This will rewrite the AdColony SDK binary to use use Jetpack libraries. See AndroidX migration guide for more information about these settings.

Manual integration

• Download the AdColony Android SDK and extract the adcolony.jar under the Library folder and add it to your project.
• The AdColony SDK depends on the Annotations Support Library. See Improve Code Inspection with Annotations for details on how to add the Annotations Support Library to your project.
• Navigate to the AdColony adapter artifacts on Google's Maven Repository. Select the latest version, download the AdColony adapter's .aar file, and add it to your project.

Step 4: Implement privacy settings on AdColony SDK

EU Consent and GDPR

Under the Google EU User Consent Policy, you must ensure that certain disclosures are given to, and consents obtained from, users in the European Economic Area (EEA) regarding the use of device identifiers and personal data. This policy reflects the requirements of the EU ePrivacy Directive and the General Data Protection Regulation (GDPR). When seeking consent, you must identify each ad network in your mediation chain that may collect, receive, or use personal data and provide information about each network's use. Google currently is unable to pass the user's consent choice to such networks automatically.

The AdColony adapter provides the AdColonyMediationAdapter.getAppOptions() method to customize parameters to be sent to AdColony's SDK. Two methods relevant to GDPR on these options are setPrivacyFrameworkRequired() and setPrivacyConsentString(). The following sample code demonstrates how to pass consent information to the AdColony adapter, which are then used in AdColony's initialization method. These options must be set before you initialize the Google Mobile Ads SDK to ensure they get forwarded properly to AdColony's SDK.

Note: Your app must reference AdColony adapter 4.2.0.0 or higher and AdColony SDK 4.2.0 or higher to use the code below.

Java

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter;
//...

AdColonyAppOptions appOptions = AdColonyMediationAdapter.getAppOptions();
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.GDPR, true);
appOptions.setPrivacyConsentString(AdColonyAppOptions.GDPR, "1");

Kotlin

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter
//...

val appOptions = AdColonyMediationAdapter.getAppOptions()
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.GDPR, true)
appOptions.setPrivacyConsentString(AdColonyAppOptions.GDPR, "1")

See AdColony's GDPR implementation details for more details about what values may be provided in these methods.

US states privacy laws

U.S. states privacy laws require giving users the right to opt out of the "sale" of their "personal information" (as the law defines those terms), with the opt-out offered via a prominent "Do Not Sell My Personal Information" link on the "selling" party's homepage. The U.S. states privacy laws compliance guide offers the ability to enable restricted data processing for Google ad serving, but Google is unable to apply this setting to each ad network in your mediation chain. Therefore, you must identify each ad network in your mediation chain that may participate in the sale of personal information and follow guidance from each of those networks to ensure compliance.

The AdColony adapter provides the AdColonyMediationAdapter.getAppOptions() method to customize parameters to be sent to AdColony's SDK. Two methods relevant to CCPA on these options are setPrivacyFrameworkRequired() and setPrivacyConsentString(). The following sample code demonstrates how to pass consent information to the AdColony adapter, which are then used in AdColony's initialization method. These options must be set before you initialize the Google Mobile Ads SDK to ensure they get forwarded properly to AdColony's SDK.

Note: Your app must reference AdColony adapter 4.2.0.0 or higher and AdColony SDK 4.2.0 or higher to use the code below.

Java

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter;
//...

AdColonyAppOptions appOptions = AdColonyMediationAdapter.getAppOptions();
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.CCPA, true);
appOptions.setPrivacyConsentString(AdColonyAppOptions.CCPA, "1");

Kotlin

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter
//...

val appOptions = AdColonyMediationAdapter.getAppOptions()
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.CCPA, true)
appOptions.setPrivacyConsentString(AdColonyAppOptions.CCPA, "1")

See AdColony's CCPA implementation details for more details about what values may be provided in these methods.

Step 5: Add required code

No additional code is required for AdColony integration.

Step 6: Test your implementation

Enable test ads

Make sure you register your test device for AdMob and enable test mode in AdColony UI.

Important: Disable test mode for AdMob and AdColony before releasing your app.

Verify test ads

To verify that you are receiving test ads from AdColony, enable single ad source testing in ad inspector using the AdColony (Bidding) and AdColony (Waterfall) ad source(s).

Optional steps

Permissions

For optimal performance, AdColony recommends adding the following optional permissions to your app's AndroidManifest.xml file:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.VIBRATE" />

Using interstitial and rewarded ads

Network-specific parameters

The AdColony adapter supports additional request parameters which can be passed to the adapter using the AdColonyBundleBuilder class. The AdColonyBundleBuilder includes the following methods:

• setShowPrePopup(boolean): Sets whether or not to show a popup before showing an ad. Set to false for no popup before ad shows.
• setShowPostPopup(boolean): Sets whether or not to show a popup after showing an ad. Set to false for no popups after ad shows.

Here's a code example of how to set these ad request parameters:

Java

AdColonyBundleBuilder.setShowPrePopup(true);
AdColonyBundleBuilder.setShowPostPopup(true);

AdRequest request = new AdRequest.Builder()
  .addNetworkExtrasBundle(AdColonyAdapter.class, AdColonyBundleBuilder.build())
  .build();
rewardedInterstitialAd.loadAd(request);

Kotlin

AdColonyBundleBuilder.setShowPrePopup(true)
AdColonyBundleBuilder.setShowPostPopup(true)

val request = AdRequest.Builder()
  .addNetworkExtrasBundle(AdColonyAdapter::class.java, AdColonyBundleBuilder.build())
  .build()
rewardedInterstitialAd.loadAd(request)

Verify your adapter and SDK versions

To log the adapter and SDK versions, use the following code snippet:

AdColonyMediationAdapter adapter = new AdColonyMediationAdapter();
VersionInfo adapterVersion = adapter.getVersionInfo();
VersionInfo sdkVersion = adapter.getSDKVersionInfo();
// Log the adapter patch version to 3 digits to represent the x.x.x.x versioning
// used by adapters.
Log.d("TAG", String.format(
    "Adapter version: %d.%d.%03d",
    adapterVersion.getMajorVersion(),
    adapterVersion.getMinorVersion(),
    adapterVersion.getMicroVersion()));
Log.d("TAG", String.format(
    "SDK version: %d.%d.%d",
    sdkVersion.getMajorVersion(),
    sdkVersion.getMinorVersion(),
    sdkVersion.getMicroVersion()));

Error codes

If the adapter fails to receive an ad from AdColony, publishers can check the underlying error from the ad response using ResponseInfo.getAdapterResponse() under the following classes:

com.jirbo.adcolony.AdColonyAdapter
com.google.ads.mediation.adcolony.AdColonyMediationAdapter

Here are the codes and accompanying messages thrown by the AdColony adapter when an ad fails to load:

Error code	Reason
100	The AdColony SDK returned an error.
101	Invalid server parameters (e.g. missing Zone ID).
102	An ad was already requested for the same Zone ID.
103	The AdColony SDK returned an initialization error.
104	The requested banner size does not map to a valid AdColony ad size.
105	Presentation error due to ad not loaded.
106	Context used to initialize the AdColony SDK was not an Activity instance.

AdColony Android Mediation Adapter Changelog

Next Version

• Updated the minimum required Google Mobile Ads SDK version to 22.4.0.

Version 4.8.0.2

• Updated adapter to use new VersionInfo class.
• Updated the minimum required Google Mobile Ads SDK version to 22.0.0.

Built and tested with:

• Google Mobile Ads SDK version 22.0.0.
• AdColony SDK version 4.8.0.

Version 4.8.0.1

• Added support for forwarding COPPA information to the AdColony SDK.
• Updated the minimum required Google Mobile Ads SDK version to 21.5.0.

Built and tested with:

• Google Mobile Ads SDK version 21.5.0.
• AdColony SDK version 4.8.0.

Version 4.8.0.0

• Verified compatibility with AdColony SDK version 4.8.0.

Built and tested with:

• Google Mobile Ads SDK version 21.0.0.
• AdColony SDK version 4.8.0.

Version 4.7.1.1

• Updated compileSdkVersion and targetSdkVersion to API 31.
• Updated the minimum required Google Mobile Ads SDK version to 21.0.0.
• Updated the minimum required Android API level to 19.

Built and tested with:

• Google Mobile Ads SDK version 21.0.0.
• AdColony SDK version 4.7.1.

Version 4.7.1.0

• Verified compatibility with AdColony SDK version 4.7.1.

Built and tested with:

• Google Mobile Ads SDK version 20.6.0.
• AdColony SDK version 4.7.1.

Version 4.7.0.0

• Verified compatibility with AdColony SDK version 4.7.0.
• Updated the minimum required Google Mobile Ads SDK version to 20.6.0.

Built and tested with:

• Google Mobile Ads SDK version 20.6.0.
• AdColony SDK version 4.7.0.

Version 4.6.5.0

• Verified compatibility with AdColony SDK version 4.6.5.

Built and tested with:

• Google Mobile Ads SDK version 20.4.0.
• AdColony SDK version 4.6.5.

Version 4.6.4.0

• Verified compatibility with AdColony SDK version 4.6.4.

Built and tested with:

• Google Mobile Ads SDK version 20.4.0.
• AdColony SDK version 4.6.4.

Version 4.6.3.0

• Verified compatibility with AdColony SDK version 4.6.3.
• Updated the minimum required Google Mobile Ads SDK version to 20.4.0.

Built and tested with:

• Google Mobile Ads SDK version 20.4.0.
• AdColony SDK version 4.6.3.

Version 4.6.2.0

• Verified compatibility with AdColony SDK version 4.6.2.

Built and tested with:

• Google Mobile Ads SDK version 20.3.0.
• AdColony SDK version 4.6.2.

Version 4.6.0.0

• Verified compatibility with AdColony SDK version 4.6.0.
• Updated the minimum required Google Mobile Ads SDK version to 20.3.0.

Built and tested with:

• Google Mobile Ads SDK version 20.3.0.
• AdColony SDK version 4.6.0.

Version 4.5.0.0

• Added support for banners advanced bidding.
• Verified compatibility with AdColony SDK version 4.5.0.
• Updated the minimum required Google Mobile Ads SDK version to 20.0.0.

Built and tested with:

• Google Mobile Ads SDK version 20.0.0.
• AdColony SDK version 4.5.0.

Version 4.4.1.0

• Verified compatibility with AdColony SDK version 4.4.1.

Built and tested with:

• Google Mobile Ads SDK version 19.7.0.
• AdColony SDK version 4.4.1.

Version 4.4.0.0

• Verified compatibility with AdColony SDK version 4.4.0.
• Added support of AdColony's collectSignals() method for bidding.
• Updated the minimum required Google Mobile Ads SDK version to 19.7.0.

Built and tested with:

• Google Mobile Ads SDK version 19.7.0.
• AdColony SDK version 4.4.0.

Version 4.3.0.0

• Verified compatibility with AdColony SDK version 4.3.0.
• Updated the minimum required Google Mobile Ads SDK version to 19.5.0.

Built and tested with:

• Google Mobile Ads SDK version 19.5.0.
• AdColony SDK version 4.3.0.

Version 4.2.4.0

• Fixed a bug where onUserEarnedReward() was not forwarded for rewarded ads.
• Added additional error codes for AdColony SDK initialization errors.
• Updated the minimum required Google Mobile Ads SDK version to 19.4.0.

Built and tested with:

• Google Mobile Ads SDK version 19.4.0.
• AdColony SDK version 4.2.4.

Version 4.2.0.0

• Verified compatibility with AdColony SDK version 4.2.0.
• Updated the adapter to support inline adaptive banner requests.
• Updated the minimum required Google Mobile Ads SDK version to 19.2.0.

Built and tested with:

• Google Mobile Ads SDK version 19.2.0.
• AdColony SDK version 4.2.0.

Version 4.1.4.1

• Added descriptive error codes and reasons for adapter load/show failures.
• Updated the minimum required Google Mobile Ads SDK version to 19.0.1.

Built and tested with:

• Google Mobile Ads SDK version 19.0.1.
• AdColony SDK version 4.1.4.

Version 4.1.4.0

• Verified compatibility with AdColony SDK version 4.1.4.

Built and tested with:

• Google Mobile Ads SDK version 18.3.0.
• AdColony SDK version 4.1.4.

Version 4.1.3.1

• Fixed an issue where the onRewardedAdLoaded() callback is not being forwarded by the adapter.

Built and tested with:

• Google Mobile Ads SDK version 18.3.0.
• AdColony SDK version 4.1.3.

Version 4.1.3.0

• Verified compatibility with AdColony SDK version 4.1.3.

Built and tested with:

• Google Mobile Ads SDK version 18.3.0.
• AdColony SDK version 4.1.3.

Version 4.1.2.0

• Verified compatibility with AdColony SDK version 4.1.2.
• Updated the minimum required Google Mobile Ads SDK version to 18.3.0.

Built and tested with:

• Google Mobile Ads SDK version 18.3.0.
• AdColony SDK version 4.1.2.

Version 4.1.0.0

• Verified compatibility with AdColony SDK version 4.1.0.
• Added support for banner ads.
• Updated the minimum required Google Mobile Ads SDK version to 18.2.0.

Built and tested with:

• Google Mobile Ads SDK version 18.2.0.
• AdColony SDK version 4.1.0.

Version 3.3.11.0

• Verified compatibility with AdColony SDK version 3.3.11.
• Updated the minimum required Google Mobile Ads SDK version to 18.1.1.

Version 3.3.10.1

• Added bidding capability to the adapter for interstitial and rewarded ads.

Version 3.3.10.0

• Verified compatibility with AdColony SDK version 3.3.10.

Version 3.3.9.0

• Verified compatibility with AdColony SDK version 3.3.9.
• Removed setGdprRequired() and setGdprConsentString() methods on AdColonyBundleBuilder.
• Added the AdColonyMediationAdapter.getAppOptions() method. Publishers must now pass GDPR information to AdColony's SDK through these options. See the developer documentation for more details.

Version 3.3.8.1

• Updated adapter to support new open-beta Rewarded API.
• Updated the minimum required Google Mobile Ads SDK version to 17.2.0.

Version 3.3.8.0

• Verified compatibility with AdColony SDK version 3.3.8.

Version 3.3.7.0

• Verified compatibility with AdColony SDK version 3.3.7.

Version 3.3.6.0

• Verified compatibility with AdColony SDK version 3.3.6.

Version 3.3.5.1

• Updated the adapter to invoke the onRewardedVideoComplete() ad event.

Version 3.3.5.0

• Verified compatibility with AdColony SDK version 3.3.5.

Version 3.3.4.0

• Verified compatibility with AdColony SDK version 3.3.4.
• Updated the adapter with GDPR.

Version 3.3.3.0

• Verified compatibility with AdColony SDK version 3.3.3.
• Removed the setTestModeEnabled method from the Bundle builder class. Publishers can now request test ads from AdColony by specifying a test device via addTestDevice() method from the AdRequest builder class.

Version 3.3.2.0

• Verified compatibility with AdColony SDK version 3.3.2.

Version 3.3.0.1

• Fixed an issue where the adapter fails to fill when the adapter is reinitialized.
• Fixed an issue where reward callback is sent incorrectly.

Version 3.3.0.0

• Verified compatibility with AdColony SDK version 3.3.0.
• Updated the Adapter project for Android Studio 3.0.

Version 3.2.1.1

• Added setTestModeEnabled method to the Bundle builder class. Publishers can use this method to mark AdColony requests as test requests.

Version 3.2.1.0

• Verified compatibility with AdColony SDK version 3.2.1.

Version 3.2.0.0

• Verified compatibility with AdColony SDK version 3.2.0.

Version 3.1.2.0

• Fixed possible NullPointerExceptions.
• Verified compatibility with AdColony SDK version 3.1.2.

Version 3.1.1.0

• Verified compatibility with AdColony SDK version 3.1.1.

Version 3.1.0.0

• Verified compatibility with AdColony SDK version 3.1.0.

Version 3.0.6.0

• Changed the version naming system to [AdColony SDK version].[adapter patch version].
• Updated the minimum required AdColony SDK to v3.0.6.

Earlier Versions

• Supports rewarded video and interstitial ads.