将 AdColony 与中介集成

本指南适用于希望使用 Google 移动广告 SDK 通过出价和广告瀑布流中介从 AdColony 加载和展示广告的发布商。其中介绍了如何将 AdColony 广告添加到广告单元的中介配置,以及如何将 AdColony SDK 和适配器集成到 Android 应用中。

支持的集成和广告格式

AdMob 适用于 AdColony 的中介适配器具有以下功能:

集成
出价
瀑布
格式
横幅
插页式广告
激励广告
原生

要求

  • Android API 级别 19 或更高级别
  • [对于出价]:AdColony 适配器 3.3.10.1 或更高版本(建议使用最新版本)
  • 最新版 Google 移动广告 SDK

第 1 步:设置 AdColony

注册登录您的 AdColony 帐号。点击 Setup New App 按钮,将您的应用添加到 AdColony 发布商信息中心

AdColony 设置新应用

填写表单,然后点击页面底部的创建,将应用添加到 AdColony。

AdColony 创建应用

创建应用后,您可以转到应用的基本应用信息部分下方的获利,以获取应用 ID

AdColony 应用 ID

接下来,点击“应用”页面广告区域部分中的设置新广告区域按钮,创建一个新的广告区域。即使您已有,仍建议您为 AdMob 创建新的中介区域。

AdColony 设置区域

有关创建广告展示位置的更多说明,请选择与您的首选广告格式对应的标签页。

  1. 区域是否处于活动状态?设置为
  2. 输入广告区域的名称

  3. 选择 Banner 作为 Ad Zone Size

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

插页式广告

  1. 区域是否处于活动状态?设置为
  2. 输入广告区域的名称

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

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

激励广告

  1. 区域是否处于活动状态?设置为
  2. 输入广告区域的名称

  3. 选择 Value Exchange/V4VC 作为 Zone Type

  4. 仅客户端?设置为,然后输入虚拟货币名称每位用户的视频数量上限奖励金额

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

完成后,点击创建按钮以创建区域。

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

AdColony 区域 ID

[仅限广告瀑布流] 找到您的 AdColony API 密钥

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

AdColony 设置

第 2 步:为广告单元 AdMob 配置中介设置

您需要将 AdColony 添加到广告单元的中介配置中。首先,登录您的 AdMob 帐号

接下来,转到中介标签页。如果您已有要修改的中介组,请点击该中介组的名称进行修改,然后直接将 AdColony 添加为广告来源

要创建新的中介组,请选择创建中介组

AdMob Beta 中介标签页

输入广告格式和平台,然后点击继续

为中介组命名,然后选择要定位到的地理位置。 然后,将中介组状态设置为已启用。然后点击添加广告单元,此时会打开广告单元选择叠加层。

新建中介组 2

将此中介组与现有 AdMob 广告单元相关联。 然后,点击完成

选择广告单元

现在,您应该会看到“广告单元”卡片中填充了您选择的广告单元。

中介组广告单元

将 AdColony 添加为广告来源

出价

广告来源部分的出价卡片下,选择添加广告来源。然后选择 AdColony

接下来,输入在上一部分中获得的应用 ID区域 ID。 然后点击完成AdColony 配置广告单元

最后,点击保存

瀑布

广告来源部分的广告瀑布流卡片下,选择添加广告来源。然后选择 AdColony

启用优化开关。输入您在上一部分获得的 API 密钥,以便为 AdColony 设置广告来源优化。然后输入 AdColony 的有效每千次展示费用值,并点击继续

接下来,输入在上一部分中获得的应用 ID区域 ID。 然后,点击完成

配置 AdColony 广告单元

最后,点击保存

使用激励广告

在激励广告单元的设置中,提供奖励金额和奖励类型的值。然后,为确保无论投放哪个广告联盟,您都能向用户提供相同的奖励,请选中 应用于中介组中的所有广告联盟复选框。

如果您不应用此设置,AdColony 适配器会传回 AdColony 信息中心中指定的奖励。

如需详细了解如何为 AdMob 广告单元设置奖励值,请参阅创建广告单元

第 3 步:导入 AdColony SDK 和适配器

在应用级 build.gradle 文件中,添加以下最新版 Maven 代码库和实现依赖项,以及最新版 AdColony SDK 和适配器:

repositories {
    google()
    mavenCentral()
}

...
dependencies {
    implementation 'com.google.android.gms:play-services-ads:21.0.0'
    implementation 'com.google.ads.mediation:adcolony:4.8.0.0'
}
...

将项目迁移至 AndroidX

AdColony SDK 依赖于 Android 支持库,但最新的 Google 移动广告 SDK 使用的是 Jetpack 库。

要确保 AdColony SDK 和 Google 移动广告 SDK 兼容,请在项目的顶层创建一个 gradle.properties 文件,并添加以下代码:

android.useAndroidX=true
android.enableJetifier=true

这将重写 AdColony SDK 二进制文件以使用 Jetpack 库。如需详细了解这些设置,请参阅 AndroidX 迁移指南

手动集成

  1. 下载 AdColony Android SDK,提取 Library 文件夹下的 adcolony.jar,并将其添加到您的项目。

  2. AdColony SDK 依赖于注解支持库。如需详细了解如何将注解支持库添加到项目中,请参阅使用注解改进代码检查

  3. 转到 Google 的 Maven 代码库中的 AdColony 适配器工件。选择最新版本,下载 AdColony 适配器的 .aar 文件,并将其添加到您的项目。

第 4 步:需要其他代码

AdColony 集成无需其他代码。

第 5 步:测试您的实现效果

如需在 AdColony 上启用测试广告,请转到您的 AdColony 信息中心并依次转到获利 > 应用。在应用的广告区域部分下,选择要为哪个区域启用测试广告。通过在开发部分下选中仅显示测试广告?,即可启用测试广告。

AdColony 测试

可选步骤

根据 Google《欧盟地区用户意见征求政策》,您必须确保向欧洲经济区 (EEA) 内的用户披露与使用设备标识符和个人数据有关的信息,以及征得这些用户的同意。此政策反映了欧盟《电子隐私指令》和《一般数据保护条例》(GDPR) 的要求。在征求用户意见时,您必须指明中介链中可能会收集、接收或使用个人数据的广告联盟,并提供各个广告联盟的使用情况信息。Google 目前无法自动将用户的意见传递给此类网络。

以下部分介绍了如何为 AdColony 启用或停用个性化广告。

AdColony 适配器提供 AdColonyMediationAdapter.getAppOptions() 方法,用于自定义要发送到 AdColony 的 SDK 的参数。AdColony SDK 4.2.0 中添加了 setPrivacyFrameworkRequired()setPrivacyConsentString() 这两个与 GDPR 相关的方法。以下示例代码演示了如何将这些参数传递给 AdColony 适配器,适配器随后会在 AdColony 的初始化方法中使用该适配器。必须在初始化移动广告之前设置这些选项,以确保它们能够正确转发到 AdColony 的 SDK:

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

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

如需详细了解这些方法中可能提供哪些值,请参阅 AdColony 的 GDPR 实现详情

将 AdColony 添加到 GDPR 广告合作伙伴列表

按照 GDPR 设置 中的步骤将 AdColony 添加到AdMob 界面中的 GDPR 广告合作伙伴列表。

CCPA

《加州消费者隐私法案》(CCPA) 要求赋予加州居民以下权利:根据法律定义这些条款,禁止他们“销售”他们的个人信息(根据法律定义这些条款);通过“非公开个人信息”提供的链接,通过“非公开”个人信息中提供的“退出”链接,选择退出“个人信息”在 CCPA 准备指南中,您可以为 Google 广告投放启用受限的数据处理,但 Google 无法将此设置应用于中介链中的每个广告联盟。因此,您必须指明中介链中可能参与个人信息销售的每个广告联盟,并遵循各个广告联盟的指导,确保遵守 CCPA。

将 AdColony 添加到 CCPA 广告合作伙伴列表

按照 CCPA 设置 中的步骤将 AdColony 添加到AdMob 界面的 CCPA 广告合作伙伴列表中。

权限

为了获得最佳性能,AdColony 建议您向应用的 AndroidManifest.xml 文件添加以下可选权限

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

使用插页式广告和激励广告

广告联盟专用参数

AdColony 适配器支持其他请求参数,这些参数可以使用 AdColonyBundleBuilder 类传递给适配器。AdColonyBundleBuilder 包括以下方法:

  • setShowPrePopup(boolean) - 设置是否在展示广告之前显示弹出式窗口。设为 false 表示广告展示前不显示任何弹出式窗口。
  • setShowPostPopup(boolean) - 设置是否在展示广告后显示弹出式窗口。设置为 false 表示在广告展示后没有弹出窗口。

以下是如何设置这些广告请求参数的代码示例:

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)

验证适配器和 SDK 版本

如需记录适配器和 SDK 版本,请使用以下代码段:

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()));

错误代码

如果适配器未能从 AdColony 收到广告,则发布商可以使用以下类中的ResponseInfo.getAdapterResponse() 检查来自广告响应的根本错误:

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

当广告加载失败时,AdColony 适配器抛出的代码和附带的消息如下:

错误代码 原因
100 AdColony SDK 返回了错误。
101 服务器参数无效(例如缺少区域 ID)。
102 已针对同一区域 ID 请求了广告。
103 AdColony SDK 返回了初始化错误。
104 请求的横幅广告尺寸未映射到有效的 AdColony 广告尺寸。
105 因未加载广告而导致呈现错误。
106 用于初始化 AdColony SDK 的上下文不是 Activity 实例。
0 - 3 次 AdColony SDK 返回了错误。如需了解详情,请参阅这份文档
101 服务器参数无效(例如缺少区域 ID)。
102 用于展示广告的根视图控制器是 nil
103 AdColony SDK 返回了初始化错误。
104 AdColony SDK 不支持在 5 秒内进行两次配置。
105 未能展示广告。
106 用于奖励的可用区不是 AdColony 门户网站上的奖励可用区。

AdColony Android 中介适配器更新日志

4.8.0.0 版

  • 已验证与 AdColony SDK 4.8.0 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 21.0.0。
  • AdColony SDK 版本 4.8.0。

4.7.1.1 版

  • compileSdkVersiontargetSdkVersion 更新到了 API 31。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 21.0.0。
  • 已将最低的 Android API 级别更新为 19。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 21.0.0。
  • AdColony SDK 版本 4.7.1。

4.7.1.0 版

  • 已验证与 AdColony SDK 4.7.1 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.6.0
  • AdColony SDK 版本 4.7.1。

4.7.0.0 版

  • 已验证与 AdColony SDK 4.7.0 的兼容性。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 20.6.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.6.0
  • AdColony SDK 版本 4.7.0。

4.6.5.0 版

  • 已验证与 AdColony SDK 4.6.5 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.4.0。
  • AdColony SDK 版本 4.6.5。

4.6.4.0 版

  • 已验证与 AdColony SDK 4.6.4 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.4.0。
  • AdColony SDK 4.6.4 版。

4.6.3.0 版

  • 已验证与 AdColony SDK 4.6.3 的兼容性。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 20.4.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.4.0。
  • AdColony SDK 版本 4.6.3。

4.6.2.0 版

  • 已验证与 AdColony SDK 4.6.2 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.3.0。
  • AdColony SDK 版本 4.6.2。

4.6.0.0 版

  • 已验证与 AdColony SDK 4.6.0 的兼容性。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 20.3.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.3.0。
  • AdColony SDK 4.6.0 版。

4.5.0.0 版

  • 新增了对横幅高级出价的支持。
  • 已验证与 AdColony SDK 4.5.0 的兼容性。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 20.0.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 20.0.0
  • AdColony SDK 版本 4.5.0。

4.4.1.0 版

  • 已验证与 AdColony SDK 4.4.1 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 19.7.0。
  • AdColony SDK 4.4.1 版。

4.4.0.0 版

  • 已验证与 AdColony SDK 4.4.0 的兼容性。
  • 添加了对 AdColony 的 collectSignals() 出价方法的支持。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 19.7.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 19.7.0。
  • AdColony SDK 4.4.0 版。

4.3.0.0 版

  • 已验证与 AdColony SDK 4.3.0 的兼容性。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 19.5.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 19.5.0。
  • AdColony SDK 版本 4.3.0。

4.2.4.0 版

  • 修复了无法为激励广告转发 onUserEarnedReward() 的错误。
  • 为 AdColony SDK 初始化错误添加了额外的错误代码。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 19.4.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 19.4.0。
  • AdColony SDK 版本 4.2.4。

4.2.0.0 版

  • 已验证与 AdColony SDK 4.2.0 的兼容性。
  • 更新了适配器,以支持内嵌自适应横幅广告请求。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 19.2.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 19.2.0 版。
  • AdColony SDK 版本 4.2.0。

4.1.4.1 版

  • 添加了描述性错误代码以及适配器加载/显示失败的原因。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 19.0.1。

构建和测试时使用的工具:

  • Google 移动广告 SDK 19.0.1。
  • AdColony SDK 版本 4.1.4。

4.1.4.0 版

  • 已验证与 AdColony SDK 4.1.4 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 18.3.0。
  • AdColony SDK 版本 4.1.4。

4.1.3.1 版

  • 修复了适配器不转发 onRewardedAdLoaded() 回调的问题。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 18.3.0。
  • AdColony SDK 版本 4.1.3。

4.1.3.0 版

  • 验证了与 AdColony SDK 4.1.3 的兼容性。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 18.3.0。
  • AdColony SDK 版本 4.1.3。

4.1.2.0 版

  • 已验证与 AdColony SDK 4.1.2 的兼容性。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 18.3.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 18.3.0。
  • AdColony SDK 4.1.2 版。

4.1.0.0 版

  • 已验证与 AdColony SDK 4.1.0 的兼容性。
  • 新增了对横幅广告的支持。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 18.2.0。

构建和测试时使用的工具:

  • Google 移动广告 SDK 版本 18.2.0。
  • AdColony SDK 版本 4.1.0。

版本 3.3.11.0

  • 已验证与 AdColony SDK 3.3.11 的兼容性。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 18.1.1。

版本 3.3.10.1

  • 针对插页式广告和激励广告向适配器添加了出价功能。

版本 3.3.10.0

  • 已验证与 AdColony SDK 版本 3.3.10 的兼容性。

版本 3.3.9.0

  • 已验证与 AdColony SDK 3.3.9 的兼容性。
  • 移除了 AdColonyBundleBuilder 上的 setGdprRequired()setGdprConsentString() 方法。
  • 添加了 AdColonyMediationAdapter.getAppOptions() 方法。现在,发布商必须通过这些选项将 GDPR 信息传递给 AdColony' SDK。如需了解详情,请参阅开发者文档

版本 3.3.8.1

  • 更新了适配器,以支持新的公开 Beta 版 API。
  • 将所需的最低 Google 移动广告 SDK 版本更新为 17.2.0。

版本 3.3.8.0

  • 已验证与 AdColony SDK 3.3.8 版本的兼容性。

版本 3.3.7.0

  • 已验证与 AdColony SDK 版本 3.3.7 的兼容性。

版本 3.3.6.0

  • 验证了与 AdColony SDK 3.3.6 的兼容性。

版本 3.3.5.1

  • 更新了适配器,以调用 onRewardedVideoComplete() 广告事件。

版本 3.3.5.0

  • 验证了与 AdColony SDK 3.3.5 的兼容性。

版本 3.3.4.0

  • 验证了与 AdColony SDK 3.3.4 的版本兼容。
  • 更新了 GDPR 的适配器。

版本 3.3.3.0

  • 已验证与 AdColony SDK 3.3.3 的版本兼容。
  • 从 Bundle 构建器类中移除了 setTestModeEnabled 方法。现在,发布商可通过 AdRequest 构建器类中的 addTestDevice() 方法从 AdColony 请求测试设备。

版本 3.3.2.0

  • 已验证与 AdColony SDK 3.3.2 的兼容性。

版本 3.3.0.1

  • 修复了重新初始化适配器时适配器无法填充的问题。
  • 修复了奖励回调发送错误的问题。

版本 3.3.0.0

  • 验证了与 AdColony SDK 3.3.0 的兼容性。
  • 更新了 Android Studio 3.0 的 Adapter 项目。

版本 3.2.1.1

  • 向 Bundle 构建器类添加了 setTestModeEnabled 方法。发布商可以使用此方法将 AdColony 请求标记为测试请求。

版本 3.2.1.0

  • 已验证与 AdColony SDK 3.2.1 的版本兼容。

版本 3.2.0.0

  • 已验证与 AdColony SDK 3.2.0 的兼容性。

版本 3.1.2.0

  • 修复了可能的 NullPointerExceptions。
  • 验证了与 AdColony SDK 版本 3.1.2 的兼容性。

版本 3.1.1.0

  • 验证了与 AdColony SDK 3.1.1 的兼容性。

版本 3.1.0.0

  • 验证了与 AdColony SDK 3.1.0 的兼容性。

版本 3.0.6.0

  • 将版本命名系统更改为了 [AdColony SDK 版本 [适配器补丁程序版本]]。
  • 将必需的 AdColony SDK 更新到了 v3.0.6。

早期版本

  • 支持激励视频广告和插页式广告。