建立自訂事件

使用自訂事件，發布商就能使用 AdMob中介服務，為支援的廣告聯播網以外的第三方廣告聯播網新增刊登序列中介服務。本指南將說明如何在 Unity 專案中使用 Android 和 iOS 建構的現有自訂事件。

必要條件

• 完成開始使用。您的 Unity 應用程式應該已經匯入 Google Mobile Ads Unity 外掛程式。

• 專為 Android 和 iOS 打造的自訂事件轉接程式。如要建立自訂事件轉接程式，請參閱Android 和iOS的自訂事件指南。

定義自訂事件

您必須在 AdMob 網頁介面上定義自訂事件，才能讓自訂事件參與中介服務。為 Android 和 iOS 中介服務群組新增自訂事件。

這張螢幕截圖顯示一些自訂事件設定範例：

如何填寫參數
類別名稱 (iOS)	如果是 iOS，請輸入導入自訂事件的類別名稱。 如果類別是透過 Swift 導入，則必須在類別名稱前面加上其應用程式 / 架構模組的名稱 (例如 appName.className)。 如果專案中有多個目標，或是專案名稱與目標名稱不同，就必須提供目標名稱。若是目標名稱，看起來會像這樣：appName_targetName.className。另外，請記得將所有非英數字元 (如破折號) 替換成底線。
類別名稱 (Android)	如果是 Android，請確保您為 Class Name 提供的值是 Android 的完整類別名稱 (例如 com.google.ads.mediation.sample.customevent.SampleCustomEvent)。
標籤	請輸入事件專屬名稱。
參數	如果您希望將字串引數 (例如廣告單元 ID) 傳遞至自訂事件，

匯入自訂事件程式庫

自訂事件可能需要加入其他程式庫才能正確運作。舉例來說，您可能需要納入下列程式庫：

• Android 第三方 SDK
• Android 第三方自訂事件
• iOS 第三方廣告 SDK
• iOS 第三方自訂事件

程式庫類型

你可以透過多種方式將 Android 或 iOS 程式碼匯入 Unity 專案，包括：

• 使用 Unity 的外部依附元件管理工具匯入預先建構的 Android 或 iOS 構件
• 匯入 AAR 外掛程式和 Android 程式庫
• 匯入 Java 和 Kotlin 來源檔案
• 匯入 iOS 來源檔案和靜態資料庫

視使用的程式庫封裝方式而定，您可能需要為每個程式庫採用不同的匯入策略。我們稍後會進一步說明每個選項。

(建議) 匯入預先建構的 Android 或 iOS 構件

使用 Unity 適用的外部依附元件管理工具，從 Maven 或 CocoaPods 匯入預先建構的構件。這個外掛程式包含在 GoogleMobileAds 外掛程式中。

如要匯入現有的構件，請建立設定檔來定義匯入項目。檔案名稱和路徑須符合下列要求：

• 檔案必須位於 /Editor/ 資料夾中。
• 檔案名稱必須以 Dependencies.xml 結尾。

舉例來說，如要為名為 AdPub 的假設廣告聯播網匯入自訂事件轉接程式，請建立檔案：

Assets/AdPub/Editor/AdPubDependencies.xml

接下來，請在 AdPubDependencies.xml 檔案中定義依附元件。您可以在 External Dependency Manager for Unity 入門中找到設定匯入作業的規則。以下程式碼片段包含某個假想「AdPub」廣告聯播網的 Android 和 iOS SDK 及自訂事件程式庫。

Assets/AdPub/Editor/AdPubDependencies.xml

<dependencies>
  <androidPackages>
    <androidPackage spec="com.adpub.android:adpub-sdk:1.0.0" />
    <androidPackage spec="com.adpub.android:adpub-custom-event:1.0.0">
      <repositories>
        <repository>https://repo.maven.apache.org/maven2/</repository>
        <repository>https://dl.google.com/dl/android/maven2/</repository>
      </repositories>
    </androidPackage>
  </androidPackages>
  <iosPods>
    <iosPod name="AdPubSDK" version="1.0" />
    <iosPod name="AdPubCustomEvent" version="1.0">
      <sources>
        <source>https://github.com/CocoaPods/Specs</source>
      </sources>
    </iosPod>
  </iosPods>
</dependencies>

如果自訂事件構件在必要的廣告聯播網 SDK 中已具有依附元件，就不必明確定義 SDK 依附元件：範例

External Dependency Manager 會自動監控設定變更，並解析依附元件。您也可以使用下列選單指令執行手動解析度：

Assets > External Dependency Manager > Android Resolver > Force Resolve

匯入 AAR 外掛程式和 Android 程式庫

Unity 支援匯入 *.aar 檔案和 Android 程式庫專案。如果以這種方式封裝 Android 自訂事件，請參閱 AAR 外掛程式和 Android 程式庫的操作說明，瞭解如何在 Unity 專案中加入這些檔案。

匯入 Java 和 Kotlin 來源檔案

從 Unity 2018.2 以上版本開始，如果您的 Android 自訂事件程式碼包含未編譯的 *.java 或 *.kt 檔案，您可以使用 Java 或 Kotlin 來源檔案做為外掛程式。

匯入 iOS 來源檔案和靜態資料庫

Unity 支援 *.framework 構件、*.h 和 *.m 來源檔案。如要瞭解如何匯入 iOS 構件和來源檔案，請參閱 Unity 原生外掛程式指南。

使用廣告檢查器測試自訂事件

廣告檢查器可用來測試自訂事件是否已正確匯入應用程式。只要利用手勢，或利用最少的程式碼，就能透過程式輔助方式開啟廣告檢查器。

(選用) 從 C# 指令碼呼叫第三方 SDK 原生方法

第三方廣告聯播網 SDK 可能有特殊規定，必須直接呼叫 Android 或 iOS 方法。直接呼叫這些方法的程序如下：

1. 定義平台用戶端的通用介面
2. 針對不支援的平台實作預設用戶端
3. 實作呼叫 Android 方法的 Android 用戶端
4. 實作 iOS 用戶端呼叫 iOS 方法
5. 實作用戶端工廠，有條件地在 iOS 和 Android 用戶端之間切換
6. 定義用於存取所有第三方廣告聯播網 SDK 功能的 API

下一節將示範如何在 C# API 中，為名為「AdPub」的某個假設廣告聯播網實作這些步驟，該聯播網可以呼叫 Android 和 iOS 上的方法：

Android

package com.adpub.android;

public class AdPubSdk
{
    public static void setHasUserConsent(boolean hasUserConsent);
}

iOS

@interface AdPubSdk : NSObject
+ (void)setHasUserConsent:(BOOL)hasUserConsent;
@end

定義平台用戶端的通用介面

使用代表基礎 Android 和 iOS API 的方法建立 IAdPubClient 介面。

Assets/AdPub/Common/IAdPubClient.cs

namespace AdPub.Common
{
    public interface IAdPubClient
    {
        ///<summary>
        /// Sets a flag indicating if the app has user consent for advertisement.
        ///</summary>
        void SetHasUserConsent(bool hasUserConsent);
    }
}

為不支援的平台定義預設用戶端

建立僅實作 IAdPubClient 介面的 DefaultClient 類別，該介面只會記錄方法名稱。此實作方式適用於 Unity 編輯器和 Android 或 iOS 以外的所有平台。

Assets/AdPub/Common/DefaultClient.cs

namespace AdPub.Common
{
    public class DefaultClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            Debug.Log("SetHasUserConsent was called.");
        }
    }
}

實作 iOS 平台用戶端

建立在 iOS 上實作 IAdPubClient 介面的 iOSAdPubClient 類別。此實作使用 InteropServices 呼叫 iOS AdPubSdk 類別中的 setHasUserConsent() 方法。

Assets/AdPub/Platforms/iOS/iOSAdPubClient.cs

// Wrap this class in a conditional operator to make sure it only runs on iOS.
#if UNITY_IOS

// Reference InteropServices to include the DLLImportAttribute type.
using System.Runtime.InteropServices;

using AdPub.Common;

namespace AdPub.Platforms.Android
{
    public class iOSAdPubClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            GADUAdPubSetHasUserConsent(hasUserConsent);
        }

        [DllImport("__Internal")]
        internal static extern void GADUAdPubSetHasUserConsent(bool hasUserConsent);
    }
}
#endif

接下來，請實作上述定義的 GADUAdPubSetHasUserConsent() 方法。使用 C 方法 GADUAdPubSetHasUserConsent() 建立 AdPubClientBridge.m，以便處理 Unity 的方法呼叫，並叫用 AdPubSDK。

AdPubClientBridge 是 iOS 來源檔案，必須如 Unity 的原生外掛程式指南所述，放置在 Plugins/iOS 資料夾中。

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

void GADUAdPubSetHasUserConsent(BOOL hasUserConsent) {
  [AdPubSDK setHasUserConsent:hasUserConsent];
}

實作 Android 平台用戶端

建立 AndroidAdPubCient 類別，在 Android 上實作 IAdPubClient 介面。此實作使用 Android Java 輔助類別呼叫 Android 靜態方法 setHasUserConsent()。

由於 Android Java 輔助類別只能在 Android 執行階段使用，因此您可以使用 UNITY_ANDROID 編譯器指令來避免編譯錯誤，如程式碼片段所示。您也可以在 Unity 2017.4 以上版本中使用組合定義來解決這個問題。

Assets/AdPub/Platforms/Android/AndroidAdPubClient.cs

// Wrap this class in a conditional operator to make sure it only runs on Android.
#if UNITY_ANDROID

// Reference the UnityEngine namespace which contains the JNI Helper classes.
using UnityEngine;

using AdPub.Common;

namespace AdPub.Platforms.Android
{
    public class AndroidAdPubClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
             // Make a reference to the com.adpub.AdPubSDK.
            AndroidJavaClass adPubSdk = new AndroidJavaClass("com.adpub.AdPubSdk");

            // Call the native setHasUserConsent method of com.adpub.AdPubSDK.
            adPubSdk.CallStatic("setHasUserConsent", hasUserConsent);
        }
    }
}
#endif

建立工廠方法，傳回正確的用戶端實作

現在您已為每個平台實作用戶端實作，請建立 AdPubClientFactory 類別，根據執行階段平台傳回 IAdPubClient 介面的正確實作。這個類別使用編譯器指令傳回正確的 IAdPubClient 用戶端。

Assets/AdPub/Common/AdPubClientFactory.cs

namespace AdPub.Common
{
    public class AdPubClientFactory
    {
        // Return the correct platform client.
        public static IAdPubClient GetClient()
        {
#if   !UNITY_EDITOR && UNITY_ANDROID
            return new AdPub.Platforms.Android.AndroidAdPubClient();
#elif !UNITY_EDITOR && UNITY_IOS
            return new AdPub.Platforms.iOS.iOSAdPubClient();
#else
            // Returned for the Unity Editor and unsupported platforms.
            return new DefaultClient();
#endif
        }
    }
}

為每個介面方法定義公用 API

建立 AdPubApi 類別，其中包含 IAdPubClient 介面中每個用戶端方法的方法呼叫。這個類別會使用 AdPubClientFactory 取得 IAdPubClient 的執行個體，並呼叫該用戶端來提供基礎 SDK 功能。

Assets/AdPub/AdPubApi.cs

using AdPub.Common;

namespace AdPub
{
    public class AdPubApi
    {
        private static readonly IAdPubClient client = GetAdPubClient();

        // Returns the correct client for the current runtime platform.
        private static IAdPubClient GetAdPubClient()
        {
            return AdPubClientFactory.GetClient();
        }

        // Sets the user consent using the underlying SDK functionality.
        public static void SetHasUserConsent(bool hasUserConsent)
        {
            client.SetHasUserConsent(hasUserConsent);
        }
    }
}

呼叫新定義的 API

如何呼叫上述定義的 API：

Assets/Scripts/AdPubController.cs

using UnityEngine;
using AdPub;

public class AdPubController : MonoBehaviour
{
    // TODO: Get consent from the user and update this userConsent field.
    public bool userConsent;

    // Called on startup of the GameObject it's assigned to.
    public void Start()
    {
        // Pass the user consent to AdPub.
        AdPubApi.SetHasUserConsent(userConsent);
    }
}

其他第三方廣告聯播網轉接程式範例

請前往 Google Mobile Ads Unity 外掛程式 GitHub 存放區，查看其他第三方中介服務轉接程式導入 C# API 以納入對 iOS 和 Android 方法發出的呼叫的範例。