Unity

Adiz Unity¶

Adiz Unity 是 Hive 提供的 Unity 廣告模組，旨在簡化使用 AdMob 提供的廣告曝光功能。Adiz Unity 提供的廣告類型如下。

• 插頁廣告
• 橫幅廣告
• 原生廣告
• 獎勵廣告
• 獎勵插頁廣告
• 應用程式開啟廣告

請參考以下指南以安裝和使用 Adiz Unity。

安裝或更新¶

1. 設置Adiz Unity 開發環境。
2. 從這裡下載最新版本的 Adiz 並解壓。
3. 在 Unity 中，選擇資源 > 匯入包 > 自訂包…選項，選擇.unitypackage文件，然後點擊匯入。
4. 檢查 Adiz 文件和文件夾是否已在資源文件夾下創建。
5. 下載並安裝最新版本的 EDM4U。Hive SDK v4 包含 EDM4U。如果您使用的是 Hive SDK v4，則無需單獨安裝 EDM4U。

要更新目前使用的 Adiz 版本，請通過點擊 這裡 卸載 Adiz，然後下載並安裝最新版本。

Unity 設定¶

安卓¶

將 AdMobId 值以 ca-app-pub-XXXXX~YYYYY 的格式添加到在 Unity 項目中創建的 Assets/Plugins/Android/AndroidManifest.xml 文件中。

    <manifest>
        <application>
            <!-- Sample AdMob app ID: ca-app-pub-3940256099942544~3347511713 -->
            <meta-data
                    android:name="com.google.android.gms.ads.APPLICATION_ID"
                    android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
        </application>
    </manifest>

要顯示視頻廣告，您需要啟用硬體加速。在AndroidManifest.xml文件中添加硬體加速的設置。如果您將其添加到application標籤中，則整個應用程序將使用硬體加速。如果您將其添加到activity標籤中，則硬體加速僅會用於您希望顯示廣告的特定Activity。

    <application android:hardwareAccelerated="true">
            <!-- For activities that use ads, hardwareAcceleration should be true. -->
            <activity android:hardwareAccelerated="true" />
    </application>

在Unity的Android解析器设置（资产 > 外部依赖管理器 > Android解析器 > 设置）中检查使用Jetifier。。

玩家設定 > 玩家 > 建置 設定畫面，檢查以下四項。

使用 Proguard 时，Adiz 模块的 ProGuard 规则已包含在内。因此，无需向项目添加 ProGuard 规则。

iOS¶

在資產 > 外部依賴管理器 > iOS 解析器 > 設定中，取消勾選static_framework構建設置。

打開在 Unity 構建過程中生成的 Podfile，並按如下配置。

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/Com2uSPlatformCorp/HiveAdiz-iOS.git'
platform :ios, '12.0'

target 'UnityFramework' do
  pod 'HiveAdizUnityPlugin', '3.0.0
end
target 'Unity-iPhone' do
end
use_frameworks!

# fix for dyld issue in pods when using Project
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      # xcode 15 Toolchain Issue
      xcconfig_path = config.base_configuration_reference.real_path
      xcconfig = File.read(xcconfig_path)
      xcconfig_mod = xcconfig.gsub(/DT_TOOLCHAIN_DIR/, "TOOLCHAIN_DIR")
      File.open(xcconfig_path, "w") { |file| file << xcconfig_mod }
      # end

      config.build_settings["BUILD_LIBRARY_FOR_DISTRIBUTION"] = "YES"
      if config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'].to_f < 12.0
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
      end
    end
  end
end

將 GADApplicationIdentifier 鍵添加到 Unity 構建過程中生成的 Xcode 項目的 Info.plist 文件中，並將 AdMobId 值（格式為 ca-app-pub-XXXXX~YYYYY）作為鍵值輸入。或者，您可以通過取消註釋 Assets/HiveAdiz/Editor/AdizPostProcess.cs 文件中的 GADApplicationIdentifier 設置行並添加 AdMobId 來自動設置它。

\<key>GADApplicationIdentifier</key>
\<string>ca-app-pub-XXXXX~YYYYY</string>

此外，對於 iOS 14 及以上版本，請參考 更新您的 info.plist 指南，以將 SKAdNetwork 列表添加到 Info.plist 文件中。Assets/HiveAdiz/Editor/AdizPostProcess.cs 文件將在構建過程中自動將其添加到 Info.plist 文件中。

測試廣告設定¶

Adiz 可以以兩種方式顯示測試廣告。 1. 啟用測試模式：僅顯示由 AdMob 發佈的測試廣告 2. 註冊測試設備後顯示廣告：顯示真實廣告以進行測試，確保不會產生無效流量，並通過註冊設備來顯示測試廣告

啟用測試模式¶

在開發階段，啟用測試模式，以便點擊測試廣告不會向廣告主收費。啟用測試模式後，將僅顯示測試廣告。在測試模式下，即使未在控制台中輸入 AdMob 廣告金鑰，也會顯示測試廣告。商業發行期間將停用測試模式。

有兩種方法可以啟用測試模式。

• 在 Hive 控制台中注册测试设备后，请使用 演示广告 进行设置（推荐）：
  请参考控制台指南的 管理测试设备 部分。
• 使用 Adiz 类的 setTestMode() 方法：
  请参考 下面的示例代码。

使用 Adiz.SetTestMode() 方法¶

using hiveAdiz; // Activate test mode. Comment out the line below for production deployment.
Adiz.SetTestMode(true);

// 啟用 Adiz 模組日誌。日誌僅應在測試模式下使用。對於生產部署，請註釋掉下面的行。  
Adiz.SetLogEnable(true);

測試設備廣告曝光¶

您需要註冊一個測試設備，以在以下情況下顯示測試廣告。

• 測試在 Hive 控制台中註冊的 AdMob 廣告金鑰是否正常運作
• 撰寫一則 GDPR 訊息，並檢查 GDPR 同意彈出視窗是否正常運作
• 執行 廣告檢查器 以分析和調試廣告請求
  

在測試設備上顯示廣告有兩種方式。
<

• 在 Hive 控制台中注册测试设备后，将其设置为 使用广告单元 ID（推荐）：
  请参阅控制台指南中的 测试设备管理 部分。

• 使用Adiz类的setTestDevice()方法：
  请参阅下面的示例代码。

橫幅、插頁廣告或獎勵廣告

原生廣告

使用 Adiz.setTestDevice() 方法¶

要注册测试设备，您首先需要检查测试设备 ID。在 Unity 引擎的 Android 环境中，可以通过以下两种方式检查测试设备 ID（例如：33BE2250B43518CCDA7DE426D04EE231）。

• 在呼叫 Adiz.Initialize() 後檢查 Logcat 日誌：
  

  使用新的
  ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") 将其设置为调试设备。
  

• 在呼叫 Adiz.Initialize() 之後，無論廣告類型為何，請呼叫 initialize() → load() 並檢查 Logcat 日誌：
  

  `I/Ads: 使用 RequestConfiguration.Builder.setTestDeviceIds(Arrays.asList("33BE2250B43518CCDA7DE426D04EE231")) 在此設備上獲取測試廣告。
  

在Unity引擎的iOS環境中，測試設備ID（例如，B74F6468-1516-467C-99AD-CC5973C5DB52）可以通過以下兩種方式進行檢查。

• 在调用 Adiz.Initialize() 后检查 Logcat 日志：
  

  要為此設備啟用調試模式，請設置： UMPDebugSettings.testDeviceIdentifiers = @[B74F6468-1516-467C-99AD-CC5973C5DB52]
  

• 在呼叫 Adiz.Initialize() 之後，無論廣告類型如何，都要呼叫 initialize() → load() 並檢查 Logcat 日誌：

  GADMobileAds.sharedInstance().requestConfiguration.testDeviceIdentifiers = [ "B74F6468-1516-467C-99AD-CC5973C5DB52" ]
  

在检查测试设备 ID 后，在现有的 Adiz 初始化代码中执行 Adiz.initialize 之前添加行 Adiz.setTestDevice(DEVICE_ID)。将复制的测试设备 ID 输入到 DEVICE_ID 中。

using hiveAdiz;

public void Initialize() {

    // set test device
    Adiz.SetTestDevice("33BE2250B43518CCDA7DE426D04EE231");

    Adiz.Initialize(new CommonHandlers.Builder()
                                            .OnResult(InitResultCB)
                                            .Build());
}

廣告檢查器使用¶

廣告檢查器是一個應用內的疊加工具，實時分析在測試設備上請求和顯示實際廣告的過程。它告知您加載廣告所需的時間，並提供任何顯示失敗的原因。您還可以指定特定的廣告網絡，以檢查廣告是否正確顯示，如果存在問題，您可以在代碼層面進行調試。整個過程與廣告檢查器用戶界面一起進行。它包含在 Google Mobile Ads SDK Android 20.0.0 和 Google Mobile Ads SDK iOS 7.68.0 或更高版本中，並可以通過調用 AdizDeveloperTool.OpenAdInspector 使用。

要使用廣告檢查器，您必須註冊一個測試設備。

using hiveAdiz;

AdizDeveloperTool.OpenAdInspector();

Adiz AppID 設定¶

設定您在 Hive 控制台 AppCenter 中註冊的 Adiz AppID。如果未設定，將使用包名稱或捆綁 ID。

Adiz.SetAppId(appId);

Hive 控制台伺服器設定¶

設置 Hive 控制台伺服器以供使用。默認為 REAL。即使您使用生產伺服器，啟用測試模式也只會顯示測試廣告。

• Hive 測試控制台伺服器: ZoneType.TEST
• Hive 沙盒控制台伺服器: ZoneType.SANDBOX
• Hive 生產控制台伺服器: ZoneType.REAL

ZoneType selectZone = ZoneType.REAL;
Adiz.SetZone((int)selectZone);

用戶特定的廣告曝光¶

隨著在 iOS 14.5+ 中引入的 ATT（應用程式追蹤透明度），隱私得到了增強。因此，只有在用戶同意在 ATT 同意彈出窗口中進行活動追蹤的情況下，才能顯示用戶特定的廣告。要通過顯示用戶特定的廣告來最大化廣告收入，您需要創建一條 IDFA（廣告商識別碼）消息。

在 Google AdMob 儀表板上撰寫並發布 IDFA 訊息，如下所示。

撰寫 IDFA 訊息時，您可以參考以下指南。

• IDFA 實作指南
• IDFA 訊息創建指南
• 有關 IDFA 訊息和 ATT 通知的解釋

當您在 AdMob 儀表板上發佈 IDFA 訊息時，IDFA 訊息將在 iOS 14.5+ 的 Adiz 初始化期間自動顯示。當用戶在 IDFA 訊息窗口中點擊「繼續」時，將顯示 ATT 同意彈出窗口。

當用戶在ATT同意彈出窗口中點擊“允許”時，IDFA被激活，並顯示用戶特定的廣告。

GDPR 同意彈出窗口曝光 (歐洲，英國)¶

如果您的遊戲針對歐洲和英國 (EEA & UK)，您必須曝光 GDPR (一般數據保護條例) 同意彈出窗口。只有當用戶的設備 IP 地址來自歐洲和英國 (EEA & UK) 時，GDPR 同意彈出窗口才會顯示。Adiz 通過 Google UMP (用戶消息平台) 支持 GDPR 同意彈出窗口的曝光。在 AdMob 控制台中創建 GDPR 消息後，初始化 Adiz 以向來自歐洲和英國的用戶顯示 GDPR 彈出窗口。

撰寫 GDPR 訊息¶

訪問 Google AdMob 控制台以撰寫 GDPR 訊息。在撰寫 GDPR 訊息之前，請參考GDPR 訊息撰寫指南。

在創建GDPR消息時，您需要將要使用的中介添加到廣告合作夥伴列表中。 以下是添加中介的方法。

1) 前往 Google AdMob 儀表板中的 隱私與消息 > 歐洲法規 > 設定 標籤，然後點擊 '廣告合作夥伴審核 > 自訂廣告合作夥伴' 的編輯圖示。 2) 選擇所有根據 GDPR 認證的媒介合作夥伴以批量添加，或僅勾選所需的媒介合作夥伴並點擊 添加。

如果您已撰寫GDPR消息，GDPR同意彈出窗口將在Adiz初始化時自動出現。

GDPR 同意及撤回功能的實現¶

GDPR 同意彈出窗口中的項目應提供修改功能，以便用戶可以隨時更改其同意狀態。例如，用戶最初可能不會同意 GDPR，但後來希望再次同意以查看個性化廣告；或者，相反，用戶最初可能同意了 GDPR，但現在希望撤回其同意，因為他們不再想提供個人信息。為了解決這些情況，應用程序開發人員必須實現允許用戶重新同意每個項目或撤回其現有同意的功能。要實現 GDPR 同意/撤回功能，請按照以下步驟操作。

1. 在應用程式中實現一個按鈕 UI，可以重新打開 GDPR 同意彈出窗口。
2. 在實現 Adiz 初始化 時，調用 isPrivacyOptionsRequired() 以向來自歐洲和英國的用戶顯示上述按鈕 UI，否則不顯示。如果來自歐洲或英國的用戶點擊該按鈕，則調用 showPrivacyOptionsForm 以重新打開 GDPR 同意彈出窗口。之後，用戶可以隨時通過按下應用程式中的“管理選項”類似按鈕來修改他們對 GDPR 詳情的同意。下面的 showPrivacyOptionsForm 是為了示例目的而任意實現的方法，開發公司可以根據需要更改實現。

    // ....

private void InitResultCB(AdizError error, string jsonString) {
    // 初始化完成的回调函数
    Debug.Log(TAG + "::InitResultCB:: errorCode : "+error.errorCode+" errorMessage : "+error.errorMessage+" json : "+jsonString);

    if(error.isSuccess()) {
        bool isPrivacyOptionsRequired = AdizConsentManager.IsPrivacyOptionsRequired();
        if(isPrivacyOptionsRequired) {
            // Show privacy options button. Call ShowPrivacyOptionsForm on click
        } else {
            // Hide privacy options button
        }
    }
}


private void ShowPrivacyOptionsForm() {
    // Call privacy options form
    if(AdizConsentManager.IsPrivacyOptionsRequired()) {
        AdizConsentManager.ShowPrivacyOptionsForm(new CommonHandlers.Builder()
                                                .OnResult(CommonResultCB)
                                                .Build());
    }
}

// ....

為未滿GDPR同意年齡的用戶設置標籤 (TFUA)¶

您可以在进行广告请求时为未满同意年龄的用户设置标签（未满同意年龄标签，TFUA），以将居住在欧洲经济区（EEA）、英国和瑞士的用户视为有限数据处理的对象。对于面向儿童的应用程序，您可以使用 AdizConsentManager.setUserPrivacySettings 来设置用户未满同意年龄。虽然欧洲各国之间存在一些差异，但GDPR将16岁以下定义为需要父母同意的年龄。未成年同意设置必须在执行 Adiz.initialize 之前配置。

using hiveAdiz;

public void Initialize() {

    bool isTagForUnderAgeOfConsent = false; // 어린이인 경우 true로 변경

    PrivacySettings settings = new PrivacySettings.Builder()
                                .SetTagForUnderAgeOfConsent(isTagForUnderAgeOfConsent)
                                .Build();

    AdizConsentManager.SetUserPrivacySettings(settings);

    Adiz.Initialize(new CommonHandlers.Builder()
                                            .OnResult(InitResultCB)
                                            .Build());
}

GDPR 測試設備設置¶

GDPR 同意彈出窗口僅在設備的 IP 地址來自歐洲或英國時顯示。在開發階段，無論 IP 地址如何，都可以強制顯示 GDPR 同意彈出窗口以測試彈出窗口的顯示，為此，您需要設置一個 GDPR 測試設備。請按照以下步驟設置 GDPR 測試設備。以下內容與如何在測試設備上顯示廣告相同。

1. 通过初始化来初始化Adiz。此初始化是为了检查测试设备ID，不需要写入GDPR同意消息。

2. 输出Android Studio或Xcode日志以检查设备ID。示例日志如下。

• Android:

  使用新的 ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") 将其设置为调试设备。
  

  來自 33BE2250B43518CCDA7DE426D04EE231
• iOS:

  <UMP SDK>要為此設備啟用調試模式，請設置： UMPDebugSettings.testDeviceIdentifiers = @[B74F6468-1516-467C-99AD-CC5973C5DB52]
  

  在B74F6468-1516-467C-99AD-CC5973C5DB52
3. 複製設備 ID。
4. 在現有的 Adiz 初始化代碼中執行AdizGDPRManager.setTestDevice(DEVICE_ID)之前添加。
5. 撰寫 GDPR 同意消息並重新初始化 Adiz，以確保 GDPR 同意彈出窗口正確顯示。

       
           using hiveAdiz;
   
           public void Initialize() {
   
                   // GDPR 測試設備設定
                   AdizGDPRManager.SetTestDevice("33BE2250B43518CCDA7DE426D04EE231");
   
                   Adiz.Initialize(new CommonHandlers.Builder()
                                                                                                   .OnResult(InitResultCB)
                                                                                                   .Build());
           }
       
       

COPPA 兒童導向處理標籤設定¶

根據《兒童在線隱私保護法》（COPPA），應用程式開發者可以通過在請求廣告時設置兒童導向處理標籤（tagForChildDirectedTreatment, TFCD）來指定 Google 是否應將內容視為兒童導向。如果您希望它被視為兒童導向，您必須在執行 Adiz.initialize 之前調用 AdizConsentManager.SetUserPrivacySettings。當使用 Adiz 與 Hive SDK 時，兒童導向處理標籤會自動應用，因此不需要單獨配置。

using hiveAdiz;

public void Initialize() {

    bool isTagForChildDirectedTreatment = false; // Change to true if it is for children

    PrivacySettings settings = new PrivacySettings.Builder()
                                .SetTagForChildDirectedTreatment(isTagForChildDirectedTreatment)
                                .Build();

    AdizConsentManager.SetUserPrivacySettings(settings);

    Adiz.Initialize(new CommonHandlers.Builder()
                                            .OnResult(InitResultCB)
                                            .Build());
}

添加廣告調解¶

Adiz 可以使用 AdMob 調解顯示廣告。要添加 AdMob 調解，請按照以下步驟操作。

添加 AdMob 介面¶

我們將在 AdMob 控制台中進行廣告來源的整合。請按照下表進行操作。

添加 Adiz 适配器¶

Assets/HiveAdiz/Editor/Adiz_DefaultDependencies.xml 添加库依赖。

<dependencies>
  <androidPackages>
      <repositories>
        <repository>https://repo.maven.apache.org/maven2</repository>
        <repository>https://artifact.bytedance.com/repository/pangle/</repository>
      </repositories>

    <androidPackage spec="com.com2us.android.adiz:hive-adiz:3.0.0"/>
    <!-- AppLovin -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-applovin:3.0.0"/>
    <!-- Liftoff -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-liftoff:3.0.0"/>
    <!-- Meta -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-meta:3.0.0"/>
    <!-- Pangle -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-pangle:3.0.0"/>
    <!-- Unity Ads -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-unityads:3.0.0"/>
    <!-- ironSource -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-ironsource:3.0.0"/>     

  </androidPackages>
  <iosPods>
      <sources>
          <source>https://github.com/Com2uSPlatformCorp/HiveAdiz-iOS.git</source>
      </sources>

      <iosPod name="HiveAdizUnityPlugin" version="3.0.0"/>
      <iosPod name="HiveAdizAdapterAppLovin" version="3.0.0"/>
      <iosPod name="HiveAdizAdapterLiftoff" version="3.0.0"/>
      <iosPod name="HiveAdizAdapterMeta" version="3.0.0"/>
      <iosPod name="HiveAdizAdapterPangle" version="3.0.0"/>
      <iosPod name="HiveAdizAdapterUnityAds" version="3.0.0"/>
      <iosPod name="HiveAdizAdapterIronSource" version="3.0.0"/>

  </iosPods>
</dependencies>

要檢查 Adiz 轉接器配置是否已正確應用，請運行應用程序並檢查 Ad Inspector 屏幕上的配置列表。

Adiz 初始化是一個在顯示任何類型的廣告之前必須執行的步驟。初始化 Adiz 允許您接收顯示廣告所需的廣告密鑰。如果啟用了測試模式，您將收到測試密鑰。

using hiveAdiz;

public void Start() {
    /* omitted */

    // 要使用 HiveAdiz 回调，您必须将 AdizCallbackManager 注册为 GameObject。    
    Adiz.InitPlugin();
}

Adiz.Initialize(new CommonHandlers.Builder()
                        .OnResult(InitResultCB)
                        .Build());

// 初始化回调监听器
private void InitResultCB(AdizError error, string jsonString) {
    Debug.Log(TAG + "::InitResultCB:: errorCode : "+error.errorCode+" errorMessage : "+error.errorMessage+" json : "+jsonString);

    if(error.isSuccess()) {

        JSONObject resJsonObject = new JSONObject (jsonString);

        JSONObject jsonArray = resJsonObject.GetField ("keys");

        if (jsonArray != null && jsonArray.count > 0) {

            List interstitialKeyList = new List();
            List bannerKeyList = new List();
            List nativeKeyList = new List();
            List rewardedKeyList = new List();
            List rewardedInterstitialKeyList = new List();
            List appOpenKeyList = new List();

            List jsonList = jsonArray.list;

            foreach (JSONObject jsonItem in jsonList) {

                bool isDefault = false;
                jsonItem.GetField(ref isDefault, "is_default");

                // 這是一個構建鍵列表的示例，其中 is_default 為 false，當直接在遊戲中輸入廣告鍵時。
                if(isDefault == false) {
                    string hiveAdKey = null;
                    jsonItem.GetField(ref hiveAdKey, "key");

                    string form = null;
                    jsonItem.GetField(ref form, "form");

                    switch (form) {
                        case "interstitial":
                            interstitialKeyList.Add(hiveAdKey);
                            break;
                        case "banner":
                            bannerKeyList.Add(hiveAdKey);
                            break;
                        case "native":
                            nativeKeyList.Add(hiveAdKey);
                            break;
                        case "rewarded":
                            rewardedKeyList.Add(hiveAdKey);
                            break;
                        case "rewarded_interstitial":
                            rewardedInterstitialKeyList.Add(hiveAdKey);
                            break;
                        case "app_open":
                            appOpenKeyList.Add(hiveAdKey);
                            break;
                    }
                }
            }

            foreach(string hiveAdKey in interstitialKeyList) {
                Debug.Log("onSdkInitialize interstitialKeyList "+hiveAdKey);
            }

            foreach(string hiveAdKey in bannerKeyList) {
                Debug.Log("onSdkInitialize bannerKeyList "+hiveAdKey);
            }

            foreach(string hiveAdKey in nativeKeyList) {
                Debug.Log("onSdkInitialize nativeKeyList "+hiveAdKey);
            }

            foreach(string hiveAdKey in rewardedKeyList) {
                Debug.Log("onSdkInitialize rewardedKeyList "+hiveAdKey);
            }

            foreach(string hiveAdKey in rewardedInterstitialKeyList) {
                Debug.Log("onSdkInitialize rewardedInterstitialKeyList "+hiveAdKey);
            }

            foreach(string hiveAdKey in appOpenKeyList) {
                Debug.Log("onSdkInitialize appOpenKeyList "+hiveAdKey);
            }
        }
    }
}

在初始化期間收到的 JSON 文件包含一個廣告鍵的列表。廣告鍵列表的格式如下。

 
    {
        "keys":[
            {
                "mediation_id":5,
                "key":"ca-app-pub-3940256099942544/5354046379",
                "form":"rewarded_interstitial",
                "is_default":true,
                "placement_id":"lobby01"
            },
            {
                "mediation_id":4,
                "key":"ca-app-pub-3940256099942544/5224354917",
                "form":"rewarded",
                "is_default":true,
                "placement_id":"game02"
            },
            {
                "mediation_id":3,
                "key":"ca-app-pub-3940256099942544/2247696110",
                "form":"native",
                "is_default":true,
                "placement_id":"event01"
            },
            {
                "mediation_id":1,
                "key":"ca-app-pub-3940256099942544/1033173712",
                "form":"interstitial",
                "is_default":true,
                "placement_id":"mission01"
            },
            {
                "mediation_id":2,
                "key":"ca-app-pub-3940256099942544/6300978111",
                "form":"banner",
                "is_default":true,
                "placement_id":"main01"
            },
            {
                "mediation_id":6,
                "key":"ca-app-pub-3940256099942544/9257395921",
                "form":"app_open",
                "is_default":true,
                "placement_id":"appopen01"
            }
        ]
    }

在測試模式下初始化時，即使您尚未在 Hive 控制台中註冊 AdMob 廣告鍵，您仍會收到測試廣告鍵的列表。在生產模式下初始化時，您將收到在 Hive 控制台中註冊的 AdMob 廣告鍵的列表。

對於每種類型的廣告（form），一個廣告被用作預設廣告（標記為"is_default":true的廣告）。當任何類型的第一個廣告被註冊時，該廣告將成為預設廣告。創建廣告實例（initialize()）時，預設廣告不需要輸入廣告金鑰（hiveAdKey）。要更改預設廣告，您需要從HiveHive 控制台中刪除現有的預設廣告並註冊一個新的廣告。

設置廣告回調監聽器¶

通過在創建每個廣告實例時實現AdizListener，您可以根據廣告狀態的變化接收回調。

private void OnAdLoadCB()
{   
    // This will be called when the ad is loaded.
    // If the ad load is successful, you should call the ad instance's .show() at the desired time to display the ad.

    Debug.Log(TAG + "::OnAdLoadCB");

    // AdizInterstitial 已加載並準備顯示
    // requestShowAd();
}

private void OnAdLoadFailedCB(AdizError error) {
    // 這是在廣告加載失敗或因其他原因無法顯示時調用的。
    Debug.Log(TAG + "::OnAdLoadFailedCB errorCode "+error.errorCode);
    Debug.Log(TAG + "::OnAdLoadFailedCB errorMessage "+error.errorMessage);
}

private void OnAdShowCB()
{   
    // This is called when the ad is displayed.
    Debug.Log(TAG + "::OnAdShowCB");
}

private void OnAdCloseCB()
{   
    // 這是在廣告關閉時被調用的。
    Debug.Log(TAG + "::OnAdCloseCB");

    // 移除顯示 AdizInterstitial 廣告後
    // requestDestroyAd();
}

private void OnAdClickCB()
{   
    // This is called when the ad is clicked.
    Debug.Log(TAG + "::OnAdClickCB");
}

private void OnAdRewardCB(RewardItem rewardItem)
{   
    // 這是在觀看獎勵廣告或獎勵插頁廣告時給予獎勵時調用的。
    Debug.Log(TAG + "::OnAdRewardCB:: rewardItem.itemType : " + rewardItem.getItemType() + " rewardItem.itemAmount : " + rewardItem.getItemAmount());
    // 只在獎勵和獎勵插頁廣告中傳遞
}

private void OnAdPaidEventCB(AdRevenueData adRevenueData)
{   
    // 這是在廣告產生收入時被呼叫的。
    Debug.Log(TAG + "::OnAdPaidEventCB:: adRevenueData.revenue : " + adRevenueData.getRevenue() + " adRevenueData.currency : " + adRevenueData.getCurrency());
}

錯誤代碼¶

當從 Adiz.Initialize 和 AdizListener 接收到 OnAdFail() 時，AdizError 錯誤代碼和錯誤消息如下。

常見代碼¶

Adiz 錯誤代碼¶

廣告平台錯誤代碼¶

廣告顯示和廣告終止¶

按照以下步驟顯示和終止廣告。

1. 為您想要顯示的每種類型的廣告在廣告類別中創建廣告實例。如果您想顯示的廣告不是預設廣告，則需要輸入從初始化中獲得的廣告金鑰或放置 ID。如果您不輸入廣告金鑰（hiveAdKey）或放置 ID（placementId），將創建一個預設廣告實例。放置 ID 可以在 Hive 控制台中設置，更多詳細信息請參考控制台指南中的Admob 設定頁面。
2. 加載您想要顯示的廣告（load()）。
3. 加載您想要顯示的廣告（load()）。
4. 顯示已加載的廣告（show()）。要再次顯示廣告，您必須再次調用load()，然後調用show()。
5. 要結束廣告，請調用destroy()。

插播廣告¶

佔據整個螢幕的全螢幕廣告。

// Create AdizInterstitial Instance
private AdizInterstitial InterstitialAd = null;

public void requestInitAd(string interstitialAdKey) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(interstitialAdKey)) {
        // 初始化默認的 AdizInterstitial 實例 (AdEventHandlers)
        InterstitialAd = AdizInterstitial.Initialize(eventHandlers);
    } else {
        // 初始化 AdizInterstitial 實例 (hiveAdKey, AdEventHandlers)
        InterstitialAd = AdizInterstitial.Initialize(interstitialAdKey, eventHandlers);
    }
}

public void requestInitAdWithPlacementId(string interstitialPlacementId) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(interstitialPlacementId)) {
        // 初始化默認的 AdizInterstitial 實例 (AdEventHandlers)
        InterstitialAd = AdizInterstitial.Initialize(eventHandlers);
    } else {
        // 初始化 AdizInterstitial 實例 (placementId, AdEventHandlers)
        InterstitialAd = AdizInterstitial.InitializeWithPlacementId(interstitialPlacementId, eventHandlers);
    }
}

public void requestLoadAd() {
    // Load AdizInterstitial
    if(InterstitialAd != null && InterstitialAd.IsInitialized()) InterstitialAd.Load();
}

public void requestShowAd() {
    // Show AdizInterstitial
    if(InterstitialAd != null && InterstitialAd.IsLoaded()) InterstitialAd.Show();
}

public void requestDestroyAd() {
    // Destroy AdizInterstitial
    if(InterstitialAd != null) InterstitialAd.Destroy();
    InterstitialAd = null;
}

橫幅廣告¶

這是一個顯示特定大小橫幅的橫幅廣告。該橫幅廣告不會接收 OnAdClose() 回調。因此，您需要從其他位置調用 destroy() 來終止廣告。

BannerSize 遵循標準橫幅大小。

PositionType 是最上面或最下面的。默認值是最下面的。

// Create AdizBanner Instance
private AdizBanner BannerAd = null;

public void requestInitAd(string bannerAdKey) {
    // Set banner size
    private BannerSize bannerSize = BannerSize.NORMAL;

    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(bannerAdKey)) {
        // 初始化默認的 AdizBanner 實例 (AdEventHandlers)
        BannerAd = AdizBanner.Initialize(bannerSize, eventHandlers);
    } else {
        // 初始化 AdizBanner 實例 (hiveAdKey, AdEventHandlers)
        BannerAd = AdizBanner.Initialize(bannerAdKey, bannerSize, eventHandlers);
    }
}

public void requestInitAdWithPlacementId(string bannerPlacementId) {
    // 設定橫幅大小
    private BannerSize bannerSize = BannerSize.NORMAL;

    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(bannerPlacementId)) {
        // 初始化默認的 AdizBanner 實例 (AdEventHandlers)
        BannerAd = AdizBanner.Initialize(bannerSize, eventHandlers);
    } else {
        // 初始化 AdizBanner 實例 (placementId, AdEventHandlers)
        BannerAd = AdizBanner.InitializeWithPlacementId(bannerPlacementId, bannerSize, eventHandlers);
    }
}

public void requestLoadAd() {
    // Load AdizBanner
    if(BannerAd != null && BannerAd.IsInitialized()) BannerAd.Load();
}

public void requestShowAd() {
    // Set position type
    private PositionType bannerPosition = PositionType.TOP;

    // 顯示 AdizBanner
    if(BannerAd != null && BannerAd.IsLoaded()) BannerAd.Show(bannerPosition);
}

public void requestDestroyAd() {
    // Destroy AdizBanner
    if(BannerAd != null) BannerAd.Destroy();
    BannerAd = null;
}

原生廣告¶

這是一個原生廣告，展示了一個特定大小的原生模板。原生廣告針對垂直螢幕進行了優化，因此建議在垂直遊戲（豎屏遊戲）中使用它們。原生廣告不會接收 OnAdClose() 回調。因此，您需要從其他位置調用 destroy() 來關閉廣告。

當前模板支持 small 或 medium 尺寸。

在 small 模板中，PositionType 可以是最上面或最下面，默认为最下面。

medium 模板不允許選擇對齊方式，並默認使用居中對齊。

// Create AdizNative Instance
private AdizNative NativeAd = null;

public void requestInitAd(string nativeAdKey) {
    // 設定橫幅大小
    private BannerSize bannerSize = BannerSize.NORMAL;

    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(nativeAdKey)) {
        // 初始化默认的 AdizNative 实例 (AdEventHandlers)
        NativeAd = AdizNative.Initialize(bannerSize, eventHandlers);
    } else {
        // 初始化 AdizNative 实例 (hiveAdKey, AdEventHandlers)
        NativeAd = AdizNative.Initialize(nativeAdKey, bannerSize, eventHandlers);
    }
}

public void requestInitAdWithPlacementId(string nativePlacementId) {
    // Set banner size
    private BannerSize bannerSize = BannerSize.NORMAL;

    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(nativePlacementId)) {
        // 初始化默認的 AdizNative 實例 (AdEventHandlers)
        NativeAd = AdizNative.Initialize(bannerSize, eventHandlers);
    } else {
        // 初始化 AdizNative 實例 (placementId, AdEventHandlers)
        NativeAd = AdizNative.InitializeWithPlacementId(nativePlacementId, bannerSize, eventHandlers);
    }
}

public void requestLoadAd() {
    // Load AdizNative
    if(NativeAd != null && NativeAd.IsInitialized()) NativeAd.Load();
}

public void requestShowAd() {
    // Set position type
    private PositionType bannerPosition = PositionType.TOP;

    // 顯示 AdizNative
    if(NativeAd != null && NativeAd.IsLoaded()) NativeAd.Show(bannerPosition);
}

public void requestDestroyAd() {
    // 銷毀 AdizNative
    if(NativeAd != null) NativeAd.Destroy();
    NativeAd = null;
}

獎勵廣告¶

這是一個獎勵廣告，使用者在觀看廣告一段時間後會獲得獎勵。一旦獎勵被授予，獎勵項目的信息將通過 OnAdReward() 回調接收。

// Create AdizRewarded Instance
private AdizRewarded RewardVideoAd = null;

public void requestInitAd(string rewardedAdKey) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdReward(OnAdRewardCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(rewardedAdKey)) {
        // 初始化默認的 AdizRewarded 實例 (AdEventHandlers)
        RewardVideoAd = AdizRewarded.Initialize(eventHandlers);
    } else {
        // 初始化 AdizRewarded 實例 (hiveAdKey, AdEventHandlers)
        RewardVideoAd = AdizRewarded.Initialize(rewardedAdKey, eventHandlers);
    }
}

public void requestInitAdWithPlacementId(string rewardedPlacementId) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdReward(OnAdRewardCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(rewardedPlacementId)) {
        // 初始化默認的 AdizRewarded 實例 (AdEventHandlers)
        RewardVideoAd = AdizRewarded.Initialize(eventHandlers);
    } else {
        // 初始化 AdizRewarded 實例 (placementId, AdEventHandlers)
        RewardVideoAd = AdizRewarded.InitializeWithPlacementId(rewardedPlacementId, eventHandlers);
    }
}

public void requestLoadAd() {
    // Load AdizRewarded
    if(RewardVideoAd != null && RewardVideoAd.IsInitialized()) RewardVideoAd.Load();
}

public void requestShowAd() {
    // Show AdizRewarded
    if(RewardVideoAd != null && RewardVideoAd.IsLoaded()) RewardVideoAd.Show();
}

public void requestDestroyAd() {
    // Destroy AdizRewarded
    if(RewardVideoAd != null) RewardVideoAd.Destroy();
    RewardVideoAd = null;
}

獎勵插頁廣告¶

這是一個獎勵插頁廣告，使用者在觀看廣告一定時間後會獲得獎勵。一旦獎勵被授予，獎勵項目資訊將通過 OnAdReward() 回調接收。

// Create AdizRewardedInterstitial Instance
private AdizRewardedInterstitial RewardedInterstitialAd = null;

public void requestInitAd(string rewardedInterstitialAdKey) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdReward(OnAdRewardCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(rewardedInterstitialAdKey)) {
        // 初始化默認的 AdizRewardedInterstitial 實例 (AdEventHandlers)
        RewardedInterstitialAd = AdizRewardedInterstitial.Initialize(eventHandlers);
    } else {
        // 初始化 AdizRewardedInterstitial 實例 (hiveAdKey, AdEventHandlers)
        RewardedInterstitialAd = AdizRewardedInterstitial.Initialize(rewardedInterstitialAdKey, eventHandlers);
    }
}

public void requestInitAdWithPlacementId(string rewardedInterstitialPlacementId) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdReward(OnAdRewardCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(rewardedInterstitialPlacementId)) {
        // 初始化默認的 AdizRewardedInterstitial 實例 (AdEventHandlers)
        RewardedInterstitialAd = AdizRewardedInterstitial.Initialize(eventHandlers);
    } else {
        // 初始化 AdizRewardedInterstitial 實例 (placementId, AdEventHandlers)
        RewardedInterstitialAd = AdizRewardedInterstitial.InitializeWithPlacementId(rewardedInterstitialPlacementId, eventHandlers);
    }
}

public void requestLoadAd() {
    // Load AdizRewardedInterstitial
    if(RewardedInterstitialAd != null && RewardedInterstitialAd.IsInitialized()) RewardedInterstitialAd.Load();
}

public void requestShowAd() {
    // Show AdizRewardedInterstitial
    if(RewardedInterstitialAd != null && RewardedInterstitialAd.IsLoaded()) RewardedInterstitialAd.Show();
}

public void requestDestroyAd() {
    // 銷毀 AdizRewardedInterstitial
    if(RewardedInterstitialAd != null) RewardedInterstitialAd.Destroy();
    RewardedInterstitialAd = null;
}

應用程式開啟廣告 (AppOpen)¶

應用程式開啟廣告在應用程式從背景轉換到前景時顯示，顯示的是使用 load() 預加載的廣告。如果自廣告加載以來已經過了 3 小時，則不會顯示該廣告，並將自動重新加載。然後，廣告將在應用程式再次移至前景時顯示。在廣告顯示一次後，將不會自動重新加載，因此您必須再次調用 load() 來準備下一個廣告。

// Create AdizAppOpen Instance
private AdizAppOpen AppOpenAd = null;

public void requestInitAd(string appOpenAdKey) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(appOpenAdKey)) {
        // Initialize Default AdizAppOpen Instance (AdEventHandlers)
        AppOpenAd = AdizAppOpen.Initialize(eventHandlers);
    } else {
        // Initialize AdizAppOpen Instance (hiveAdKey, AdEventHandlers)
        AppOpenAd = AdizAppOpen.Initialize(appOpenAdKey, eventHandlers);
    }
}

public void requestInitAdWithPlacementId(string appOpenPlacementId) {
    AdEventHandlers eventHandlers = new AdEventHandlers.Builder()
                                                    .OnAdLoad(OnAdLoadCB)
                                                    .OnAdShow(OnAdShowCB)
                                                    .OnAdClose(OnAdCloseCB)
                                                    .OnAdFail(OnAdLoadFailedCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnAdPaidEvent(OnAdPaidEventCB)
                                                    .Build();


    if(string.IsNullOrEmpty(appOpenPlacementId)) {
        // Initialize Default AdizAppOpen Instance (AdEventHandlers)
        AppOpenAd = AdizAppOpen.Initialize(eventHandlers);
    } else {
        // Initialize AdizAppOpen Instance (placementId, AdEventHandlers)
        AppOpenAd = AdizAppOpen.InitializeWithPlacementId(appOpenPlacementId, eventHandlers);
    }
}

public void requestLoadAd() {
    // Load AdizAppOpen
    if(AppOpenAd != null && AppOpenAd.IsInitialized()) AppOpenAd.Load();
}

public void requestShowAd() {
    // Show AdizAppOpen
    Debug.Log("[appOpenAd] appOpenAd don't request Show");
}

public void requestDestroyAd() {
    // Destroy AdizAppOpen
    if(AppOpenAd != null) AppOpenAd.Destroy();
    AppOpenAd = null;
}

卸載 HiveAdiz¶

要卸載 HiveAdiz，請刪除您 Unity 專案中的以下資料夾。

• 資產/HiveAdiz
• 資產/HiveAdiz_範例

附加功能¶

從 Android 主執行緒呼叫¶

與 Android JNI 相關的 API 必須從 Unity 的主執行緒呼叫。如果您從主執行緒以外的地方呼叫它們，Adiz 功能可能無法正常運作。如果您必須從非主執行緒呼叫，請使用 Adiz.RunOnMainThread 以確保邏輯在主執行緒上運行。

Adiz.RunOnMainThread(() => {
    // Execute on the main thread
    Adiz.Initialize(new CommonHandlers.Builder()
                            .OnResult(InitResultCB)
                            .Build());
});