本指南將說明如何使用 Google Mobile Ads SDK,透過中介服務載入及顯示 AdColony 的廣告,同時涵蓋出價和刊登序列整合。包括如何將 AdColony 新增至廣告單元的中介服務設定,以及如何將 AdColony SDK 和轉接程式整合到 Android 應用程式。
支援的整合功能和廣告格式
AdColony 的 AdMob 中介服務轉接程式具有下列功能:
整合 | |
---|---|
出價 | |
瀑布 | |
格式 | |
橫幅廣告 | |
插頁式 | |
已獲得獎勵 | |
原生 |
需求條件
- Android API 級別 19 以上
- [針對出價]:AdColony 轉接程式 3.3.10.1 以上版本 (建議最新版本)
最新版 Google Mobile Ads SDK
完成中介服務 入門指南
步驟 1:設定 AdColony
註冊並登入 AdColony 帳戶。按一下「Setup New App」按鈕,即可將應用程式新增至 AdColony 發布商資訊主頁。
填寫表單並按一下頁面底部的「Create」(建立),即可將應用程式新增至 AdColony。
建立應用程式後,您可以前往應用程式的「基本應用程式資訊」部分,依序前往「營利」>「應用程式」取得應用程式 ID。
接著,請在應用程式頁面的「Ad Zones」部分按一下「Setup New Ad Zone」按鈕,來建立新的廣告區。即使已有中介服務,仍建議您建立新的廣告區 AdMob 。
如需建立廣告刊登位置的其他操作說明,請選取與所需廣告格式對應的分頁。
橫幅廣告
- 將「Zone is Active?」設為「Yes」。
輸入廣告區域的「名稱」。
選擇「橫幅」做為「廣告區域大小」。
輸入「每日播放上限」的值。
插頁式
- 將「Zone is Active?」設為「Yes」。
輸入廣告區域的「名稱」。
選擇「片頭/插頁式」做為「區域類型」。
輸入「每日播放上限」的值。
已獲得獎勵
- 將「Zone is Active?」設為「Yes」。
輸入廣告區域的「名稱」。
選擇「Value Exchange/V4VC」做為「Zone Type」。
將「Client Side Only?」設為「Yes」,然後輸入「Virtual Currency Name」、「Daily Max Videos」和「Reward Amount」。
輸入「每日播放上限」的值。
建立完成後,按一下「Create」(建立) 按鈕,即可建立廣告區域。
廣告區域建立完成後,您可以在「Ad Zone」的「Integration」(整合) 部分下方找出區域 ID。在下一個步驟中,您將使用可用區 ID。
找出 AdColony API 金鑰
出價
出價整合不需要進行這個步驟。
瀑布
您需要使用 AdColony API 金鑰來設定AdMob 廣告單元 ID。前往 AdColony 發布商資訊主頁中的「Account Settings」(帳戶設定),找出您的 API 金鑰。
步驟 2:調整廣告單元的 AdMob 中介服務設定
您必須在廣告單元的中介服務設定中加入 AdColony。請先登入 AdMob 帳戶,
接著,前往「中介服務」分頁。如要修改現有的中介服務群組,請按一下該中介服務群組的名稱進行修改,然後直接跳到「將 AdColony 做為廣告來源」一文。
如要建立新的中介服務群組,請選取「建立中介服務群組」。
輸入廣告格式與平台,然後按一下「繼續」。
為中介服務群組命名,然後選取要指定的地區。接著,將中介服務群組狀態設為「已啟用」。按一下「Add Ad Units」(新增廣告單元),即可開啟廣告單元選項疊加層。
將這個中介服務群組與您現有的 AdMob 廣告單元建立關聯。然後按一下「Done」(完成)。
「廣告單元」資訊卡現在應該會開始填入您選取的廣告單元。
新增 AdColony 做為廣告來源
出價
在「Ad Source」區段的「出價」資訊卡下方,選取「新增廣告來源」。然後選取「AdColony」。
按一下「如何簽署合作夥伴協議」,並向 AdColony 設定出價合作夥伴。
按一下「確認並同意」,然後按一下「繼續」。
如果您已經有 AdColony 的對應,只要選取即可。 否則請按一下「新增對應」。
接著,輸入「對應名稱」、「應用程式 ID」和上一節取得的「可用區 ID」。然後點選「完成」。
瀑布
在「Ad Source」區段的「Waterfall」資訊卡下方,選取「Add Ad Source」。然後選取「AdColony」。
啟用「最佳化」切換鈕。輸入上一節取得的 API 金鑰,設定 AdColony 的廣告來源最佳化功能。然後輸入 AdColony 的有效千次曝光出價,並按一下「Continue」。
如果您已經有 AdColony 的對應,只要選取即可。 如果沒有的話,請按一下「新增對應」。
接下來,輸入上一節取得的「Mapping name」(對應名稱)、「App ID」(應用程式 ID) 和「Zone ID」(區域 ID)。然後點選「完成」。
步驟 3:匯入 AdColony SDK 和轉接程式
Android Studio 整合 (建議)
在應用程式層級的 build.gradle
檔案中,新增下列 Maven 存放區和最新版 AdColony SDK 和轉接程式的實作依附元件:
repositories { google() mavenCentral() } // ... dependencies { implementation 'com.google.android.gms:play-services-ads:22.4.0' implementation 'com.google.ads.mediation:adcolony:4.8.0.2' } // ...
將專案遷移至 AndroidX
AdColony SDK 需要 Android 支援資料庫,但最新的 Google Mobile Ads SDK 則是使用 Jetpack 程式庫。
為確保 AdColony SDK 和 Google Mobile Ads SDK 相容,請在專案頂層建立 gradle.properties
檔案,並新增下列程式碼:
android.useAndroidX=true
android.enableJetifier=true
這會重寫 AdColony SDK 二進位檔,以便使用 Jetpack 程式庫。如要進一步瞭解這些設定,請參閱 AndroidX 遷移指南。
手動整合
- 下載 AdColony Android SDK,然後擷取
Library
資料夾下的adcolony.jar
,並將其新增至專案。 - AdColony SDK 依附於註解支援資料庫。如要進一步瞭解如何在專案中新增註解支援資料庫,請參閱使用註解改善程式碼檢查功能。
- 前往 Google Maven 存放區中的 AdColony 轉接程式成果。選取最新版本,下載 AdColony 轉接程式的 .aar 檔案,然後新增至專案。
步驟 4:需要額外程式碼
無須額外程式碼即可進行 AdColony 整合。
步驟 5:測試實作結果
如要在 AdColony 上啟用測試廣告,請前往 AdColony 資訊主頁,然後依序前往「營利」>「應用程式」。在應用程式的「廣告區」部分底下,選取您要啟用測試廣告的區域。如要啟用測試廣告,請在「開發」部分下方勾選「是」,勾選「只顯示測試廣告?」。
選擇性步驟
歐盟同意聲明和 GDPR
根據 Google《歐盟地區使用者同意授權政策》規定,您必須確保向歐洲經濟區 (EEA) 境內使用者運用裝置 ID 和個人資料的規定,取得特定揭露事項和同意聲明。本政策是配合《歐盟地區電子通訊隱私指令》和《一般資料保護規則》(GDPR) 而製定。徵求同意聲明時,您必須找出中介服務鏈中能夠收集、接收或使用個人資料的每個廣告聯播網,並提供每個聯播網的使用情況資訊。Google 目前無法自動將使用者的同意聲明選擇傳送給這類網路。
AdColony 轉接程式提供 AdColonyMediationAdapter.getAppOptions()
方法,以自訂要傳送至 AdColony 的 SDK 的參數。針對這些選項中 GDPR 提供的兩種方法,分別是 setPrivacyFrameworkRequired()
和 setPrivacyConsentString()
。以下程式碼範例示範如何將同意聲明資訊傳遞給 AdColony 轉接程式,以便日後在 AdColony 的初始化方法中使用。您必須在初始化 Google Mobile Ads SDK 前設定這些選項,才能確保這些選項正確地轉送至 AdColony 的 SDK。
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")
如要進一步瞭解這些方法可提供的值,請參閱 AdColony 的 GDPR 導入詳細資料。
將 AdColony 新增至 GDPR 廣告合作夥伴清單
按照 GDPR 設定 的步驟,將 AdColony 新增至AdMob 使用者介面中的 GDPR 廣告合作夥伴清單。
CCPA
美國州級隱私權法律 規定使用者有權選擇拒絕「販售」其「個人資訊」(如該法案定義),您必須在「銷售」方的首頁提供醒目的「請勿銷售我的個人資訊」連結。美國州級隱私權法律法規遵循指南可讓您為 Google 廣告放送啟用受限的資料處理,但 Google 無法將這項設定套用至中介服務鏈中的每個廣告聯播網。因此,您必須找出中介服務鏈中的每個廣告聯播網,可能參與銷售個人資訊的行為,並遵循各聯播網的指引來確保遵循法規。
AdColony 轉接程式提供 AdColonyMediationAdapter.getAppOptions()
方法,以自訂要傳送至 AdColony 的 SDK 的參數。在這些選項中,與 CCPA 相關的兩種方法為 setPrivacyFrameworkRequired()
和 setPrivacyConsentString()
。以下程式碼範例示範如何將同意聲明資訊傳遞給 AdColony 轉接程式,以便日後在 AdColony 的初始化方法中使用。您必須在初始化 Google Mobile Ads SDK 前設定這些選項,才能確保這些選項正確地轉送至 AdColony 的 SDK。
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")
如要進一步瞭解這些方法可能提供的值,請參閱 AdColony 的 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 不支援在五秒內進行兩次設定。 |
105 | 無法顯示廣告。 |
106 | 用於獎勵的區域並非 AdColony 入口網站上的獎勵區域。 |
AdColony Android 中介服務轉接程式變更記錄
下一個版本
- 將 Google Mobile Ads SDK 的最低版本需求更新為 22.4.0 版。
4.8.0.2 版
- 更新了轉接程式,以使用新的
VersionInfo
類別。 - 將 Google Mobile Ads SDK 的最低版本需求更新至 22.0.0。
建構及測試以下項目:
- Google Mobile Ads SDK 22.0.0 版。
- AdColony SDK 4.8.0 版。
4.8.0.1 版
- 新增將 COPPA 資訊轉送至 AdColony SDK 的支援功能。
- 將 Google Mobile Ads SDK 的最低版本需求更新至 21.5.0。
建構及測試以下項目:
- Google Mobile Ads SDK 21.5.0 版。
- AdColony SDK 4.8.0 版。
4.8.0.0 版
- 驗證與 AdColony SDK 4.8.0 版的相容性。
建構及測試以下項目:
- Google Mobile Ads SDK 21.0.0 版。
- AdColony SDK 4.8.0 版。
4.7.1.1 版
- 已將
compileSdkVersion
和targetSdkVersion
更新為 API 31。 - 將 Google Mobile Ads SDK 的最低版本需求更新為 21.0.0。
- 將最低 Android API 級別更新為 19。
建構及測試以下項目:
- Google Mobile Ads SDK 21.0.0 版。
- AdColony SDK 4.7.1 版。
4.7.1.0 版
- 驗證與 AdColony SDK 4.7.1 版的相容性。
建構及測試以下項目:
- Google Mobile Ads SDK 20.6.0 版。
- AdColony SDK 4.7.1 版。
4.7.0.0 版
- 經驗證與 AdColony SDK 4.7.0 版相容。
- 將 Google Mobile Ads SDK 的最低版本需求更新為 20.6.0。
建構及測試以下項目:
- Google Mobile Ads SDK 20.6.0 版。
- AdColony SDK 4.7.0 版。
4.6.5.0 版
- 經驗證與 AdColony SDK 4.6.5 版相容。
建構及測試以下項目:
- Google Mobile Ads SDK 20.4.0 版。
- AdColony SDK 4.6.5 版。
4.6.4.0 版
- 經驗證與 AdColony SDK 4.6.4 版相容。
建構及測試以下項目:
- Google Mobile Ads SDK 20.4.0 版。
- AdColony SDK 4.6.4 版。
4.6.3.0 版
- 驗證與 AdColony SDK 4.6.3 版的相容性。
- 將 Google Mobile Ads SDK 的最低版本需求更新為 20.4.0 版。
建構及測試以下項目:
- Google Mobile Ads SDK 20.4.0 版。
- AdColony SDK 4.6.3 版。
4.6.2.0 版
- 經驗證與 AdColony SDK 4.6.2 版相容。
建構及測試以下項目:
- Google Mobile Ads SDK 20.3.0 版。
- AdColony SDK 4.6.2 版。
4.6.0.0 版
- 驗證與 AdColony SDK 4.6.0 版的相容性。
- 將 Google Mobile Ads SDK 的最低版本需求更新為 20.3.0 版。
建構及測試以下項目:
- Google Mobile Ads SDK 20.3.0 版。
- AdColony SDK 4.6.0 版。
4.5.0.0 版
- 新增對橫幅廣告進階出價的支援。
- 驗證與 AdColony SDK 4.5.0 版的相容性。
- 將 Google Mobile Ads SDK 的最低版本需求更新為 20.0.0。
建構及測試以下項目:
- Google Mobile Ads SDK 20.0.0 版。
- AdColony SDK 4.5.0 版。
4.4.1.0 版
- 驗證與 AdColony SDK 4.4.1 版的相容性。
建構及測試以下項目:
- Google Mobile Ads SDK 19.7.0 版。
- AdColony SDK 4.4.1 版。
4.4.0.0 版
- 驗證與 AdColony SDK 4.4.0 版的相容性。
- 新增了 AdColony 的
collectSignals()
出價方法支援。 - 將 Google Mobile Ads SDK 的最低版本需求更新至 19.7.0。
建構及測試以下項目:
- Google Mobile Ads SDK 19.7.0 版。
- AdColony SDK 4.4.0 版。
4.3.0.0 版
- 驗證與 AdColony SDK 4.3.0 版的相容性。
- Google Mobile Ads SDK 的最低版本需求已更新至 19.5.0 版。
建構及測試以下項目:
- Google Mobile Ads SDK 19.5.0 版。
- AdColony SDK 4.3.0 版。
4.2.4.0 版
- 修正無法針對獎勵廣告轉送
onUserEarnedReward()
的錯誤。 - 為 AdColony SDK 初始化錯誤新增額外的錯誤代碼。
- Google Mobile Ads SDK 的最低版本需求已更新至 19.4.0 版。
建構及測試以下項目:
- Google Mobile Ads SDK 19.4.0 版。
- AdColony SDK 4.2.4 版。
4.2.0.0 版
- 驗證與 AdColony SDK 4.2.0 版的相容性。
- 更新轉接程式以支援內嵌自動調整橫幅廣告請求。
- 將 Google Mobile Ads SDK 的最低版本需求更新至 19.2.0。
建構及測試以下項目:
- Google Mobile Ads SDK 19.2.0 版。
- AdColony SDK 4.2.0 版。
4.1.4.1 版
- 新增描述性錯誤代碼,以及轉接程式載入/顯示失敗的原因。
- Google Mobile Ads SDK 最低版本需求更新至 19.0.1。
建構及測試以下項目:
- Google Mobile Ads SDK 19.0.1 版。
- AdColony SDK 4.1.4 版。
4.1.4.0 版
- 經驗證與 AdColony SDK 4.1.4 版相容。
建構及測試以下項目:
- Google Mobile Ads SDK 18.3.0 版。
- AdColony SDK 4.1.4 版。
4.1.3.1 版
- 修正
onRewardedAdLoaded()
回呼未由轉接器轉送的問題。
建構及測試以下項目:
- Google Mobile Ads SDK 18.3.0 版。
- AdColony SDK 4.1.3 版。
4.1.3.0 版
- 驗證與 AdColony SDK 4.1.3 版的相容性。
建構及測試以下項目:
- Google Mobile Ads SDK 18.3.0 版。
- AdColony SDK 4.1.3 版。
4.1.2.0 版
- 驗證與 AdColony SDK 4.1.2 版的相容性。
- Google Mobile Ads SDK 的最低版本需求已更新至 18.3.0 版。
建構及測試以下項目:
- Google Mobile Ads SDK 18.3.0 版。
- AdColony SDK 4.1.2 版。
4.1.0.0 版
- 驗證與 AdColony SDK 4.1.0 版的相容性。
- 新增對橫幅廣告的支援。
- 將 Google Mobile Ads SDK 的最低版本需求更新至 18.2.0。
建構及測試以下項目:
- Google Mobile Ads SDK 18.2.0 版。
- AdColony SDK 4.1.0 版。
3.3.11.0 版本
- 驗證與 AdColony SDK 3.3.11 版相容性。
- Google Mobile Ads 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 版本
- 更新了轉接程式,以支援新的 Open-Beta 獎勵 API。
- 將 Google Mobile Ads 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 版本
- 已將
setTestModeEnabled
方法新增至 Bundle 建構工具類別。發布商可以使用這個方法將 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 version].[adapterpatch version]。
- 將必要的 AdColony SDK 最低版本更新至 3.0.6 版。
較舊版本
- 支援獎勵影片廣告和插頁式廣告。