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 解析器设置 中检查 使用 Jetifier。 （资源 > 外部依赖管理器 > Android 解析器 > 设置）。

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

在使用 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', '2.1.3
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)。在 DEVICE_ID 中输入复制的测试设备 ID。

using hiveAdiz;

public void Initialize() {

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

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

廣告檢查器使用¶

廣告檢查器是一個應用內的覆蓋工具，實時分析在測試設備上請求和顯示實際廣告的過程。它告知您加載廣告所需的時間，並提供任何顯示失敗的原因。您還可以指定特定的廣告網絡，以檢查廣告是否正確顯示，如果存在問題，您可以在代碼層面進行調試。整個過程與廣告檢查器 UI 一起進行。它包含在 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 和英國），則必須曝光 GDPR（一般數據保護條例）同意彈出窗口。只有當用戶的設備 IP 地址來自歐洲和英國（EEA 和英國）時，才會顯示 GDPR 同意彈出窗口。Adiz 通過 Google UMP（用戶消息平台）支持 GDPR 同意彈出窗口的曝光。在 AdMob 控制台中創建 GDPR 消息後，初始化 Adiz 以顯示 GDPR 彈出窗口給來自歐洲和英國的用戶。

撰寫 GDPR 訊息¶

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

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

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

如果您已經撰寫了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() {
    // 呼叫隱私選項表單
    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 測試設備設置¶

只有當設備的 IP 地址來自歐洲或英國時，GDPR 同意彈出窗口才會顯示。在開發階段，可以強制顯示 GDPR 同意彈出窗口，而不考慮 IP 地址，以測試彈出窗口的顯示，為此，您需要設置一個 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:2.1.3"/>
    <!-- AppLovin -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-applovin:2.1.3"/>
    <!-- Liftoff -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-liftoff:2.1.3"/>
    <!-- Meta -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-meta:2.1.3"/>
    <!-- Pangle -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-pangle:2.1.3"/>
    <!-- Unity Ads -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-unityads:2.1.3"/>
    <!-- ironSource -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-ironsource:2.1.3"/>    

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

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

  </iosPods>
</dependencies>

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

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()
{   
    // 這是在廣告顯示時被調用的。
    Debug.Log(TAG + "::OnAdShowCB");
}

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

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

private void OnAdClickCB()
{   
    // 這是在廣告被點擊時調用的。
    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) {
    // 設定橫幅廣告大小
    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) {
    // 設定橫幅大小
    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() {
    // Destroy 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() {
    // Destroy AdizRewardedInterstitial
    if(RewardedInterstitialAd != null) RewardedInterstitialAd.Destroy();
    RewardedInterstitialAd = null;
}

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

這是一個應用程式開啟廣告，當應用程式狀態從背景變為前景時，會顯示預先加載的 (load()) 廣告。如果在廣告加載後經過 3 小時後調用 show()，廣告將自動重新加載並顯示。一旦廣告至少顯示過一次，它將不會自動重新加載。

// 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)) {
        // 初始化默認的 AdizAppOpen 實例 (AdEventHandlers)
        AppOpenAd = AdizAppOpen.Initialize(eventHandlers);
    } else {
        // 初始化 AdizAppOpen 實例 (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)) {
        // 初始化默認的 AdizAppOpen 實例 (AdEventHandlers)
        AppOpenAd = AdizAppOpen.Initialize(eventHandlers);
    } else {
        // 初始化 AdizAppOpen 實例 (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_範例