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 設定¶

Android¶

將 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 Resolver Settings 中检查 使用 Jetifier。 (Assets > External Dependency Manager > Android Resolver > Settings)。

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

使用 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.1
end
target 'Unity-iPhone' do
end
use_frameworks!

# 修正使用项目时在 pods 中的 dyld 问题
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      # xcode 15 工具链问题
      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 }
      # 结束

      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 this line 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() {

    // 테스트 디바이스 설정
    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（廣告商標識符）消息。

AdMob 請遵循儀表板上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消息，則在Adiz初始化時，GDPR同意彈出窗口將自動出現。

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) {
            // 顯示隱私選項按鈕。點擊時調用ShowPrivacyOptionsForm
        } else {
            // 隱藏隱私選項按鈕
        }
    }
}


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)之前添加Adiz.initialize。
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.1"/>
    <!-- AppLovin -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-applovin:2.1.1"/>
        <!-- Liftoff -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-liftoff:2.1.1"/>
    <!-- Meta -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-meta:2.1.1"/>
    <!-- Pangle -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-pangle:2.1.1"/>
    <!-- Unity Ads -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-unityads:2.1.1"/>
  </androidPackages>
  <iosPods>
      <sources>
          <source>https://github.com/Com2uSPlatformCorp/HiveAdiz-iOS.git</source>
      </sources>

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

  </iosPods>
</dependencies>

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

Adiz 初始化¶

這是一個在顯示所有類型廣告之前必須執行的步驟。通過初始化 Adiz，您將獲得顯示廣告所需的廣告密鑰。如果您處於測試模式，您將獲得測試密鑰。如果您使用的是 Hive SDK，請在調用 AuthV4.setup 後進行 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()
{   
    // This is called when the ad is closed.
    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;
}

橫幅廣告 (Banner)¶

這是一個顯示特定大小橫幅的橫幅廣告。橫幅廣告不會接收 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;
}

原生廣告 (Native)¶

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

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

在 small 模板中，PositionType 可以是顶部或底部，默认值是底部。

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

// 创建 AdizNative 实例
private AdizNative NativeAd = null;

public void requestInitAd(string nativeAdKey) {
    // 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(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() {
    // 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_範例