建立自訂事件

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

必要條件

• 完成「開始使用」。Unity 應用程式應已匯入 Google 行動廣告 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 Getting Started」一文。以下程式碼片段包含 Android 和 iOS SDK，以及假設的「AdPub」廣告聯播網的自訂事件程式庫。

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 依附元件：範例

外部依附元件管理工具會自動監控設定變更，並解析依附元件。您也可以使用下列選單指令執行手動解析度：

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. 定義 API，以便存取所有第三方廣告聯播網 SDK 功能

以下章節將說明如何在 C# API 中，針對名為「AdPub」的假想廣告聯播網實作這些步驟，以便在 Android 和 iOS 上呼叫方法：

AndroidiOS

package com.adpub.android;

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

@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 來源檔案，必須放置在 Plugins/iOS 資料夾中，如 Unity 的原生外掛程式指南所述。

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

實作 Android 平台用戶端

建立在 Android 上實作 IAdPubClient 介面的 AndroidAdPubCient 類別。這個實作會使用 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);
    }
}

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

如需第三方中介服務轉接器實作 C# API 的其他範例，請前往 Google 行動廣告 Unity 外掛程式 Github 存放區。這些範例可用來包裝對 iOS 和 Android 方法的呼叫。