跳轉至

Unity

Adiz Unity

Adiz Unity 是一個由 Hive SDK 提供的 Unity 廣告模組,使使用 AdMob 提供的廣告功能變得更加簡單。Adiz Unity 提供的廣告類型如下:

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

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

安裝或更新

  1. 配置 Adiz Unity 開發環境
  2. 這裡 下載最新版本的 Adiz 並解壓縮。
  3. 在 Unity 中,轉到 Assets > 匯入包 > 自訂包…,選擇 .unitypackage 文件,然後點擊匯入。

    4. 檢查是否在資產資料夾下創建了 Adiz 文件和資料夾。

    5. 下載並安裝最新版本的 EDM4U。EDM4U 包含在 Hive SDK v4 中。如果您使用的是 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時,AdizProguard規則已經包含在Adiz模組中。因此,無需將Proguard規則添加到您的項目中。

檢查您當前的 Gradle 版本。對於穩定的 Android 構建,Gradle 版本應為 6.7.1 或更高,Gradle 插件版本應為 4.2.0 或更高。以下是如何更改 Gradle 版本和 Gradle 插件版本的方法:

  1. 使用自訂基底 Gradle 模板。

    • 檢查建置設定 > 專案設定 > 玩家 > 自訂基底 Gradle 模板。
    • 將會創建 Assets/Plugins/Android/baseProjectTemplate.gradle。
  2. 更改 Gradle 插件版本。 打开文件 Assets/Plugins/Android/baseProjectTemplate.gradle* 并将版本更改为 com.android.tools.build:gradle:4.2.0

  3. 下载所需版本的 Gradle,然后将其解压到您想要的路径。
  4. 在 Unity 中更改 Gradle 安装路径。
    • 取消选中 Preferences > External Tools > Gradle Installed with Unity。
    • 设置您解压 Gradle 的路径。
  5. 在构建之前,检查 Player > Other Settings > Identification > Target API Level 中的目标 API 级别是否为 33 或更高。

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.0.1'
    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 以自動設置它。

    GADApplicationIdentifier
    ca-app-pub-XXXXX~YYYYY

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

設定測試廣告

Adiz 允許您以兩種方式顯示測試廣告。

  1. 啟用測試模式:僅顯示由 AdMob 發佈的測試廣告。
  2. 註冊測試設備並顯示廣告:為測試目的顯示真實廣告。註冊設備以顯示測試廣告,以確保在測試期間不會發生無效流量。

啟用測試模式

在開發階段,啟用測試模式以防止在測試廣告被點擊時向廣告商收費。當測試模式啟用時,僅顯示測試廣告。在測試模式下,您可以在 Hive 控制台中顯示測試廣告,而無需輸入 AdMob 廣告密鑰。對於商業發行,請禁用測試模式。

Note

在開發階段,如果在非測試模式下過度點擊廣告,可能會被視為無效流量,並可能導致您的 AdMob 帳戶被舉報,無法顯示廣告。

    using hiveAdiz;
    // Enable test mode. Comment out the below line when distributing commercially.
    Adiz.SetTestMode(true);
    // Enable logging for the Adiz module. Logging should only be used in test mode. Comment out the below line when distributing commercially.
    Adiz.SetLogEnable(true);

在測試設備上顯示廣告

在以下情況下,必須註冊測試設備以顯示測試廣告:

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

如果您在未注册测试设备的情况下测试显示真实广告,可能会被视为无效流量,从而导致您的 AdMob 账户被封锁,广告将不再显示。当您注册测试设备时,显示广告时将显示“测试模式”或“测试广告”(针对原生广告)。确保在商业发布时禁用测试设备。

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

原生廣告

要註冊測試設備,首先要識別測試設備 ID。在 Android 上,測試設備 ID(例如,33BE2250B43518CCDA7DE426D04EE231)可以使用以下兩種方法識別:

  1. 在调用 Adiz.Initialize() 后检查 Logcat 日志: 使用新的 ConsentDebugSettings.Builder().addTestDeviceHashedI ("33BE2250B43518CCDA7DE426D04EE231") 将其设置为调试设备。
  2. 在调用 initialize()load() 后检查 Logcat 日志,无论广告类型如何。

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

在 iOS 上,可以使用以下两种方法识别测试设备 ID(例如,B74F6468-1516-467C-99AD-CC5973C5DB52):

  1. 在调用 Adiz.Initialize() 后检查 Logcat 日志: 要为此设备启用调试模式,请设置: UMPDebugSettings.testDeviceIdentifiers = @[B74F6468-1516-467C-99AD-CC5973C5DB52]
  2. 在调用 initialize()load() 后检查 Logcat 日志,无论广告类型如何,在调用 Adiz.Initialize() 后: GADMobileAds.sharedInstance().requestConfiguration.testDeviceIdentifiers = [ "B74F6468-1516-467C-99AD-CC5973C5DB52" ]

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

using hiveAdiz;

public void Initialize() {

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

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

使用廣告檢查器

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

要使用廣告檢查器,您需要滿足以下兩個條件:

Adiz AppID 配置

在 Hive 控制台 AppCenter 中设置注册的 Adiz AppID。如果未设置,将使用包名称或捆绑 ID。

    Adiz.SetAppId(appId);

Hive 控制台伺服器配置

配置您想要使用的 Hive 控制台伺服器。默認為 REAL。即使您使用商業伺服器,如果啟用測試模式,僅會顯示測試廣告。

  • 測試控制台伺服器: ZoneType.TEST
  • 沙盒控制台伺服器: ZoneType.SANDBOX
  • 商業控制台伺服器: ZoneType.REAL
    ZoneType selectZone = ZoneType.REAL;    
    Adiz.SetZone((int)selectZone);

曝露用戶特定廣告

隨著 iOS 14.5+ 中引入的 ATT(應用程序追蹤透明度),隱私保護得到了加強。因此,只有在用戶同意在 ATT 同意彈出窗口中進行活動追蹤的情況下,才能曝露用戶特定廣告。為了通過曝露用戶特定廣告來最大化廣告收入,必須創建 IDFA(廣告商標識符)消息。 按照 AdMob 儀表板上的指南創建並發布您的 IDFA 消息。

一旦在 AdMob 控制台上发布 IDFA 消息,它将在 iOS 14.5+ 中自动显示在 Adiz 的初始化过程中。点击 IDFA 消息窗口中的“继续”将显示 ATT 同意弹出窗口。

如果用户在 ATT 同意弹出窗口中点击“允许”,则 IDFA 将被激活,并将显示用户特定的广告。

Note

在歐洲和英國,GDPR 同意彈出窗口會顯示給用戶。如果用戶從未同意過 GDPR 詳情,則 ATT 同意彈出窗口會在 GDPR 同意彈出窗口後立即顯示,而不顯示 IDFA 消息。如果已經同意了 GDPR 詳情,則通常會顯示 IDFA 消息,然後是 ATT 同意彈出窗口。

如果您的遊戲針對歐洲和英國 (EEAUK), 則必須顯示GDPR (一般數據保護條例) 同意彈出窗口。只有當用戶的設備IP 地址來自歐洲或英國 (EEAUK) 時,才會顯示GDPR 同意彈出窗口。 Adiz 支持GoogleUMP (用戶 消息 平台) 來顯示GDPR 同意彈出窗口。

AdMob 控制台中创建 GDPR 消息 后,当您 初始化 Adiz 时,GDPR 弹出窗口将显示给来自欧洲和英国的用户。

Warning

即使您瞄准的是欧洲和英国以外的地区,您仍然必须在AdMob 控制台中创建GDPR 消息,以便 Adiz 的初始化能够正确执行。

創建 GDPR 訊息

訪問 Google AdMob 控制台以創建 GDPR 訊息。在創建 GDPR 訊息之前,請參考 GDPR 訊息創建指南

在創建GDPR消息後,GDPR同意彈出窗口將在Adiz的初始化期間自動顯示。

實施GDPR同意/撤回選項

GDPR同意彈出窗口應允許用戶隨時修改他們的同意。例如,最初不願意同意GDPR的用戶如果希望接收個性化廣告,可能會想要同意,反之亦然。為了適應這種情況,開發人員必須實施功能,使用戶能夠再次同意或撤回他們之前的同意。要實施GDPR同意/撤回功能,請按照以下步驟操作:

  1. 在您的應用中實現一個按鈕 UI 以重新加載 GDPR 同意彈出窗口。
  2. 在實現 Adiz 的初始化 時,調用 isPrivacyOptionsRequired() 以顯示上述按鈕 UI 給來自歐洲和英國的用戶,否則不顯示。如果來自歐洲和英國的用戶按下按鈕,則調用 showPrivacyOptionsForm 以重新加載 GDPR 同意彈出窗口,允許用戶隨時通過應用中的“管理選項”按鈕或類似按鈕修改其 GDPR 詳細信息的同意。下面提供的 showPrivacyOptionsForm 方法僅作為示例,開發者可以以任何所需的形式實現。

    using hiveAdiz;
    
    public void Initialize() {
            // ... skipped
    
            // 初始化 Adiz
            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()) {
                    bool isPrivacyOptionsRequired = AdizConsentManager.IsPrivacyOptionsRequired();
                    if(isPrivacyOptionsRequired) {
                            // 顯示隱私選項按鈕。點擊時,調用 ShowPrivacyOptionsForm
                    } else {
                            // 隱藏隱私選項按鈕
                    }
            }
    }
    
    private void ShowPrivacyOptionsForm() {
            // 呼叫隱私選項表單
            if(AdizConsentManager.IsPrivacyOptionsRequired()) {
                    AdizConsentManager.ShowPrivacyOptionsForm(new CommonHandlers.Builder()
                                                                                                    .OnResult(CommonResultCB)
                                                                                                    .Build());
            }
    }
    
    private void CommonResultCB(AdizError error, string jsonString) {
            // 隱私選項表單調用完成回調。無需額外的錯誤處理
            Debug.Log(TAG + "::CommonResultCB:: errorCode : "+error.errorCode+" errorMessage : "+error.errorMessage);
    }
    

未滿 同意 年齡用戶設定標籤 (TFUA)

您可以使用Tag来处理居住在欧洲经济区(EEA)、英国(UK)和瑞士的用户,将其视为有限数据处理的对象,前提是他们未满ConsentTFUA)时发出广告请求。对于服务儿童的应用程序,您可以使用AdizConsentManager.SetUserPrivacySettings将用户设置为未满同意年龄。尽管欧洲各国之间存在一些差异,但GDPR将16岁以下定义为需要父母同意。under-age-of-consent设置必须在执行Adiz.initialize之前进行配置。

Warning

如果同時將GDPR 未成年同意 標籤SetTagForUnderAgeOfConsentCOPPA 兒童導向處理設置SetTagForChildDirectedTreatment都設置為true,則COPPA 兒童導向處理設置SetTagForChildDirectedTreatment將優先。因此,請不要同時將它們都設置為true

Note

當使用 Hive SDK v4 24.2.0 或更高版本與 Adiz 2.0.1 或更高版本時,Hive SDK 將根據用戶的年齡自動為未滿同意年齡的用戶應用標籤。因此,無需調用 AdizConsentManager.SetUserPrivacySettings

 


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地址來自歐洲或英國時顯示。在開發過程中,您可以通過設置GDPR測試設備來強制顯示GDPR同意彈出窗口,而不管設備的IP地址,這是為了測試目的。請按照以下步驟設置GDPR測試設備。以下內容與在測試設備上顯示廣告相同

  1. 初始化 Adiz。這個初始化的目的是檢查測試設備ID,因此您不需要提前創建GDPR同意消息。
  2. 打印Android Studio日誌或Xcode日誌以獲取設備ID。以下日誌是一個示例。

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

    iOS: B74F6468-1516-467C-99AD-CC5973C5DB52要为此设备启用调试模式,请设置: UMPDebugSettings.testDeviceIdentifiers = @[B74F6468-1516-467C-99AD-CC5973C5DB52]

  3. 複製設備 ID。

  4. 在現有的 Adiz 初始化代碼中,在執行 Adiz.initialize 之前添加 Adiz.setTestDevice(DEVICE_ID)
  5. 創建 GDPR 同意消息 並重新初始化 Adiz,以確保 GDPR 同意彈出窗口正確顯示。

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

設定 COPPA tag 以便針對兒童的處理

根據《兒童在線隱私保護法》(COPPA),應用程序開發者可以通過設置tagForChildDirectedTreatmentTFCD)來指定在進行廣告請求時,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());
}

添加 ad 中介

Adiz 可以使用 AdMob 中介投放广告。请按照以下步骤添加 AdMob 中介。

添加AdMob 中介

按照下表在AdMob 控制台中集成广告来源。

AppLovin Pangle Unity Ads Meta
步驟 1:設置 Android iOS Android iOS Android iOS Android iOS
步驟 2:添加廣告來源 Android iOS Android iOS Android iOS Android iOS
步驟 3 添加 Adiz 適配器

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

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

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

    </iosPods>
    </dependencies>

 

要驗證Adiz適配器配置是否正確應用,請運行應用程序並檢查Ad Inspector螢幕上的配置列表。

Adiz 初始化

Adiz的初始化是展示任何類型廣告之前的必要步驟。初始化Adiz允許您接收顯示廣告所需的廣告金鑰。如果啟用了測試模式,您將收到一個測試金鑰。如果您使用的是Hive SDK,請在調用AuthV4.setup後進行Adiz初始化。

using hiveAdiz;

public void Start() {
    /* omitted */

    // To use Adiz callbacks, you need to register AdizCallbackManager as a GameObject.    
    Adiz.InitPlugin();
}

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

// Initialize Callback listener
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");

                // This is an example of constructing a list of keys where is_default is false, in case you want to enter the ad keys directly in the game.
                if(isDefault) {
                    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
            },
            {
                "mediation_id":4,
                "key":"ca-app-pub-3940256099942544/5224354917",
                "form":"rewarded",
                "is_default":true
            },
            {
                "mediation_id":3,
                "key":"ca-app-pub-3940256099942544/2247696110",
                "form":"native",
                "is_default":true
            },
            {
                "mediation_id":1,
                "key":"ca-app-pub-3940256099942544/1033173712",
                "form":"interstitial",
                "is_default":true
            },
            {
                "mediation_id":2,
                "key":"ca-app-pub-3940256099942544/6300978111",
                "form":"banner",
                "is_default":true
            },
            {
                "mediation_id":6,
                "key":"ca-app-pub-3940256099942544/9257395921",
                "form":"app_open",
                "is_default":true
            }
        ]
    }

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

對於每種類型的廣告(form),一個廣告被用作默認廣告(廣告的 "is_default":true)。當您首次註冊任何廣告類型時,第一個註冊的廣告將成為默認廣告。創建默認廣告的廣告實例(initialize())時,您不需要輸入廣告鍵(hiveAdKey)。要更改默認廣告,您必須在 Hive 控制台中刪除現有的默認廣告並註冊一個新廣告。

廣告回調監聽器配置

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

名稱 描述 必需
.OnAdLoad(OnAdLoadCB) 廣告加載成功 O
.OnAdFail(OnAdLoadFailedCB) 失敗(您可以通過 error.errorCode()error.errorMessage() 知道失敗的原因) O
.OnAdShow(OnAdShowCB) 廣告曝光成功 O
.OnAdClick(OnAdClickCB) 廣告點擊 O
.OnAdPaidEvent(OnAdPaidEventCB) 廣告曝光後收到付費事件的瞬間,廣告收入信息被傳遞 O
.OnAdClose(OnAdCloseCB) 廣告關閉
* 廣告關閉後,要重新曝光相同的廣告實例,必須再次調用 load() 然後 show()
* 如果您不再希望曝光廣告,請調用 destroy() 以移除廣告實例。
X
.OnAdReward(OnAdRewardCB) 用戶在獎勵廣告(rewarded, rewarded interstitial)中曝光後獲得獎勵的瞬間 X
private void OnAdLoadCB()
{   
    // Called when the ad is loaded.
    // If the ad load is successful, you should call .show() of the ad instance at the desired moment to display the ad.
    Debug.Log(TAG + "::OnAdLoadCB");

    // Expose after AdizInterstitial is loaded
    // requestShowAd();
}

private void OnAdLoadFailedCB(AdizError error) {
    // Called when the ad load fails or the ad exposure fails for another reason.
    Debug.Log(TAG + "::OnAdLoadFailedCB errorCode " + error.errorCode);
    Debug.Log(TAG + "::OnAdLoadFailedCB errorMessage " + error.errorMessage);
}

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

private void OnAdCloseCB()
{   
    // Called when the ad is closed.
    Debug.Log(TAG + "::OnAdCloseCB");

    // Remove AdizInterstitial ad after exposure
    // requestDestroyAd();
}

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

private void OnAdRewardCB(RewardItem rewardItem)
{   
    // Called when a reward is granted for watching an ad in rewarded or rewarded interstitial ads.
    Debug.Log(TAG + "::OnAdRewardCB:: rewardItem.itemType : " + rewardItem.getItemType() + " rewardItem.itemAmount : " + rewardItem.getItemAmount());
    // Delivered only in rewarded, rewardedInterstitial ads
}

private void OnAdPaidEventCB(AdRevenueData adRevenueData)
{   
    // Called when revenue is generated for the ad.
    Debug.Log(TAG + "::OnAdPaidEventCB:: adRevenueData.revenue : " + adRevenueData.getRevenue() + " adRevenueData.currency : " + adRevenueData.getCurrency());
}

錯誤代碼

Adiz.InitializeAdizListener接收到的OnAdFail()AdizError錯誤代碼和消息如下:

常見代碼

編號 案例 解釋
0 成功 成功

Adiz 錯誤代碼

數字 案例 解釋
-1 InvalidParam 無效的參數
-2 NotSupported 不支持
-3 InProgress 處理中
-4 Network 網絡錯誤
-5 NeedInitialize 需要初始化
-6 ResponseFail 響應失敗
-7 Timeout 網絡超時
-99 Unknown 未知錯誤

廣告平台錯誤代碼

編號 案例 說明
-101 需要加載 廣告未加載
-102 需要重新加載 由於廣告曝光時間到期,需要重新加載
-103 庫存不足 中介回應成功,但由於庫存不足未填充廣告
-104 缺少AppId 中介請求的AppID錯誤
-105 內部網絡錯誤 與中介網絡相關的錯誤
-106 無效的單位ID 無效的單位ID
-107 中介未填充 中介適配器無法處理廣告請求
-108 已經加載 已經處於加載狀態
-109 無法請求廣告 無法請求廣告
-201 GDPR同意錯誤 GDPR同意錯誤
-202 不需要隱私選項 無需顯示或無法顯示GDPR同意彈出窗口

廣告顯示與終止

要顯示和終止廣告,請遵循以下步驟:

  1. 為您想要顯示的每種廣告類型從廣告類別創建廣告實例。如果您想顯示的廣告不是默認廣告,則必須輸入從初始化中獲得的廣告密鑰。如果您不輸入廣告密鑰(hiveAdKey),則會創建一個默認廣告實例。
  2. 加載(load())您想要顯示的廣告。
  3. 顯示(show())已加載的廣告。要重新顯示廣告,您必須再次調用load(),然後調用show()
  4. 要終止廣告,請調用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)) {
        // Initialize Default AdizInterstitial Instance (AdEventHandlers)
        InterstitialAd = AdizInterstitial.Initialize(eventHandlers);
    } else {
        // Initialize AdizInterstitial Instance (hiveAdKey, AdEventHandlers)
        InterstitialAd = AdizInterstitial.Initialize(interstitialAdKey, eventHandlers);
    }
}

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

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

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

橫幅廣告顯示特定大小的橫幅。橫幅廣告不會接收 OnAdClose() 回調。因此,您必須從其他位置調用 destroy() 來終止廣告。

BannerSize 遵循標準橫幅大小。

尺寸點 (寬 x 高) 描述 支援設備 橫幅尺寸常數
320x50 橫幅 手機和平板 BannerSize.NORMAL
320x100 大橫幅 手機和平板 BannerSize.MEDIUM
300x250 IAB 中型矩形 手機和平板 BannerSize.LARGE
468x60 IAB 全尺寸橫幅 平板 BannerSize.FULL
 

PositionType 是上或下。默認為下。

對齊方式 描述 位置類型常數
頂部對齊 指定在螢幕頂部的對齊方式(對於iOS,根據SafeArea指定頂部對齊) PositionType.TOP
底部對齊(預設) 指定在螢幕底部的對齊方式(對於iOS,根據SafeArea指定底部對齊) PositionType.BOTTOM
// Create AdizBanner Instance
private AdizBanner BannerAd = null;

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

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


    if(string.IsNullOrEmpty(bannerAdKey)) {
        // Initialize Default AdizBanner Instance (AdEventHandlers)
        BannerAd = AdizBanner.Initialize(bannerSize, eventHandlers);
    } else {
        // Initialize AdizBanner Instance (hiveAdKey, AdEventHandlers)
        BannerAd = AdizBanner.Initialize(bannerAdKey, bannerSize, eventHandlers);
    }
}

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

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

    // Show AdizBanner
    if(BannerAd != null) BannerAd.Show(bannerPosition);
}

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

原生廣告 (Native)

本地廣告顯示特定尺寸的本地模板。 本地廣告針對垂直屏幕進行了優化,因此建議在豎屏模式的遊戲(垂直屏幕遊戲)中使用它們。 本地廣告不會接收 OnAdClose() 回調。 因此,您必須在不同的位置調用 destroy() 來終止廣告。

目前,模板支持 smallmedium 尺寸。

尺寸點 (寬 x 高) 模板 對齊 橫幅尺寸常數
355x91 (比例調整) 小尺寸 上 / 下 BannerSize.NORMAL
355x370 (比例調整) 中尺寸 中心 (固定) BannerSize.MEDIUM, BannerSize.LARGE, BannerSize.FULL

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

對齊 描述 位置類型常數
頂部對齊 指定對齊到螢幕的頂部(iOS 對齊到 SafeArea 的頂部) PositionType.TOP
底部對齊(默認) 指定對齊到螢幕的底部(iOS 對齊到 SafeArea 的底部) PositionType.BOTTOM

medium 模板不允許選擇對齊方式,並且默認情況下是居中對齊的。

// Create AdizNative Instance
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)) {
        // Initialize Default AdizNative Instance (AdEventHandlers)
        NativeAd = AdizNative.Initialize(bannerSize, eventHandlers);
    } else {
        // Initialize AdizNative Instance (hiveAdKey, AdEventHandlers)
        NativeAd = AdizNative.Initialize(nativeAdKey, bannerSize, eventHandlers);
    }
}

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

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

    // Show AdizNative
    if(NativeAd != null) 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)) {
        // Initialize Default AdizRewarded Instance (AdEventHandlers)
        RewardVideoAd = AdizRewarded.Initialize(eventHandlers);
    } else {
        // Initialize AdizRewarded Instance (hiveAdKey, AdEventHandlers)
        RewardVideoAd = AdizRewarded.Initialize(rewardedAdKey, eventHandlers);
    }
}

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

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

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

獎勵插頁廣告 (Rewarded interstitial)

獎勵插頁廣告是用戶在觀看廣告一段時間後獲得獎勵的插頁廣告。一旦獎勵發放,您將通過 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)) {
        // Initialize Default AdizRewardedInterstitial Instance (AdEventHandlers)
        RewardedInterstitialAd = AdizRewardedInterstitial.Initialize(eventHandlers);
    } else {
        // Initialize AdizRewardedInterstitial Instance (hiveAdKey, AdEventHandlers)
        RewardedInterstitialAd = AdizRewardedInterstitial.Initialize(rewardedInterstitialAdKey, eventHandlers);
    }
}

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

public void requestShowAd() {
    // Show AdizRewardedInterstitial
    if(RewardedInterstitialAd != null) 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)) {
        // Initialize Default AdizAppOpen Instance (AdEventHandlers)
        AppOpenAd = AdizAppOpen.Initialize(eventHandlers);
    } else {
        // Initialize AdizAppOpen Instance (hiveAdKey, AdEventHandlers)
        AppOpenAd = AdizAppOpen.Initialize(appOpenAdKey, eventHandlers);
    }
}

public void requestLoadAd() {
    // Load AdizAppOpen
    if(AppOpenAd != null) 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;
}

卸載

要卸載 Adiz,請從您的 Unity 專案中移除以下資料夾:

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