Unity

Adiz Unity¶

Adiz Unity是Hive提供的Unity广告模块，旨在更方便地使用AdMob提供的广告展示功能。Adiz Unity提供的广告形式如下。

• 全屏廣告（Interstitial）
• 橫幅廣告（Banner）
• 原生廣告（Native）
• 獎勵廣告（Rewarded）
• 獎勵全屏廣告（Rewarded Interstitial）
• 應用開啟廣告（AppOpen）

請按照以下指南的順序安裝和使用Adiz Unity。

安裝或更新¶

1. 配置 Adiz Unity 開發環境。
2. 下載 Adiz 的最新版本並解壓縮。
3. 在 Unity 中，選擇 Assets > Import Package > Custom Package…，然後選擇 .unitypackage 文件並點擊 Import。
4. 確認 Assets 文件夾下是否生成了 Adiz 文件和文件夾。
5. 下載並安裝 EDM4U 的最新版本。Hive SDK v4 包含 EDM4U。如果您使用 Hive SDK v4，則無需單獨安裝 EDM4U。

要更新当前使用的 Adiz 版本，请先卸载 Adiz，然后下载并安装最新版本。

Unity 設定¶

Android¶

請在 Unity 專案中生成的 Assets/Plugins/Android/AndroidManifest.xml 文件中添加 ca-app-pub-XXXXX~YYYYY 格式的 AdMobId 值。

    <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(Assets > External Dependency Manager > Android Resolver > Settings)中勾選Use Jetifier.。

玩家設定 > 玩家 > 建置 設定畫面中勾選以下四個項目。

使用Proguard時，Adiz模組已包含ProGuard規則。因此，無需將ProGuard規則添加到項目中。

iOS¶

在Assets > External Dependency Manager > iOS Resolver > Settings中取消勾選 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.0
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

<

在Unity构建时生成的Xcode项目的Info.plist文件中，添加如下GADApplicationIdentifier键，并将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; // 啟用測試模式。商業發佈時請註解掉以下行。
Adiz.SetTestMode(true);

// 啟用 Adiz 模組的日誌記錄。日誌記錄僅應在測試模式下使用。在商業發佈時，請註解掉以下行。  
Adiz.SetLogEnable(true);

測試設備的廣告曝光¶

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

• Hive 在控制台注册的 AdMob 广告密钥是否正常工作进行测试的情况
• 编写 GDPR 消息 并确认 GDPR 同意弹出窗口是否正常工作
• 运行 广告检查器 以分析和调试广告请求的情况
  

在測試設備上顯示廣告的方法有兩種。

• 在哈伊夫控制台注册测试设备后，设置为 广告单元 ID 使用（推荐）：
  请参考控制台指南中的 测试设备管理 内容。

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

橫幅、全屏廣告或獎勵廣告

原生廣告

使用 Adiz.setTestDevice() 方法¶

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

• 確認 Logcat 日誌，調用 Adiz.Initialize() 後:
  

  使用新的
  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() {

    // 테스트 디바이스 설정
    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。未設定時將使用 Package Name 或 Bundle 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消息後，在iOS 14.5+中，Adiz初始化時將自動顯示IDFA消息。當用戶在IDFA消息窗口中點擊“繼續”時，將顯示ATT同意彈出窗口。

當使用者在 ATT 同意彈出窗口中點擊「允許」時，IDFA 將被啟用，並顯示針對用戶的廣告。

GDPR 同意彈出窗口顯示（歐洲，英國）¶

當遊戲針對歐洲和英國（EEA & UK）時，必須顯示 GDPR（歐盟一般數據保護條例）同意彈出窗口。GDPR 同意彈出窗口僅在用戶設備的 IP 地址為歐洲和英國（EEA & UK）IP 地址時顯示。Adiz 支持使用 Google UMP（用戶消息平台）來顯示 GDPR 同意彈出窗口。在 AdMob 控制台中編寫 GDPR 消息後，初始化 Adiz，則來自歐洲和英國地區的用戶將看到 GDPR 彈出窗口。

GDPR 訊息撰寫¶

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

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

GDPR 同意及撤回功能實現¶

GDPR 同意彈出窗口中的項目應提供用戶隨時修改同意狀態的功能。例如，用戶最初可能不同意 GDPR，但希望為了查看定制廣告而重新同意；或者相反，最初同意了 GDPR，但不再希望提供個人信息而要求撤回同意。為了應對這些情況，應用開發者需要為每個項目實現重新同意或撤回現有同意的功能。要實現 GDPR 同意/撤回功能，請遵循以下步驟。

1. 在應用程式中實現可以重新調出GDPR同意彈出窗口的按鈕UI。
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) 設定¶

GDPR 同意年齡以下的使用者標籤（Tag For Under the Age of Consent, 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 初始化代碼中，在執行 Adiz.initialize 之前添加 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; // 若為兒童則更改為 true

    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.0"/>
    <!-- AppLovin -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-applovin:2.1.0"/>
    <!-- Pangle -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-pangle:2.1.0"/>
    <!-- Unity Ads -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-unityads:2.1.0"/>
    <!-- Meta -->
    <androidPackage spec="com.com2us.android.adiz:hive-adiz-adapter-meta:2.1.0"/>

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

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

  </iosPods>
</dependencies>

為了確認 Adiz 轉接器的配置是否正確，請在運行應用程序後，在廣告檢查器畫面中檢查配置列表。

Adiz 初始化¶

在显示所有类型的广告之前，必须执行的步骤。进行 Adiz 初始化后，可以获得显示广告所需的广告密钥。如果处于测试模式，则会收到测试密钥。如果使用 Hive SDK，则在调用 AuthV4.setup 之后进行 Adiz 初始化。

using hiveAdiz;

public void Start() {
    /* 생략 */

    // 要使用 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()
{   
    // 广告加载完成时调用。
    // 如果广告加载成功，则应在适当的时机调用广告实例的 .show() 来展示广告。


    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()。

全屏廣告 (Interstitial)¶

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

// 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() {
    // 顯示 AdizInterstitial
    if(InterstitialAd != null && InterstitialAd.IsLoaded()) InterstitialAd.Show();
}

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

橫幅廣告 (Banner)¶

這是一個顯示特定尺寸橫幅的橫幅廣告。橫幅廣告不會接收 OnAdClose() 回調。因此，必須在其他位置調用 destroy() 來結束廣告。

BannerSize遵循標準橫幅大小。

PositionType是最上面或最下面。默认值是最下面。

// 创建 AdizBanner 实例
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) {
    // 设置横幅大小
    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;
}

獎勵型廣告 (Rewarded)¶

用戶在觀看廣告超過一定時間後會獲得獎勵的獎勵型廣告。完成獎勵發放後，將通過 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() {
    // 顯示 AdizRewarded
    if(RewardVideoAd != null && RewardVideoAd.IsLoaded()) RewardVideoAd.Show();
}

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

獎勵型插頁廣告 (Rewarded Interstitial)¶

用戶在觀看廣告超過一定時間後會獲得獎勵的獎勵型插頁廣告。完成獎勵發放後，將通過 OnAdReward() 回調獲得獎勵項目信息。

// 创建 AdizRewardedInterstitial 实例
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() {
    // 顯示 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() {
    // 銷毀 AdizAppOpen
    if(AppOpenAd != null) AppOpenAd.Destroy();
    AppOpenAd = null;
}

移除 HiveAdiz¶

要移除 HiveAdiz，请删除 Unity 项目内的以下文件夹。

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