Unity

Adiz Unity¶

Adiz Unity是Hive提供的Unity广告模块，旨在简化使用AdMob提供的广告曝光功能。Adiz Unity提供的广告类型如下。

• 插页广告
• 横幅广告
• 原生广告
• 激励广告
• 激励插页广告
• 应用打开广告

请参考下面的指南以安装和使用 Adiz Unity。

安装或更新¶

1. 设置Adiz Unity开发环境。
2. 从这里下载Adiz的最新版本并解压。
3. 在Unity中，选择资产 > 导入包 > 自定义包…选项，选择.unitypackage文件，然后点击导入。
4. 检查Assets文件夹下是否已创建Adiz文件和文件夹。
5. 下载并安装最新版本的EDM4U。Hive SDK v4包含EDM4U。如果您使用的是Hive SDK v4，则无需单独安装EDM4U。

要更新当前使用的 Adiz 版本，请通过点击 这里 卸载 Adiz，然后下载并安装最新版本。

Unity 设置¶

安卓¶

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

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

要显示视频广告，您需要启用硬件加速。在AndroidManifest.xml文件中添加硬件加速的设置。如果您将其添加到application标签中，整个应用程序将使用硬件加速。如果您将其添加到activity标签中，硬件加速将仅用于您想要显示广告的特定Activity。

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

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

玩家设置 > 玩家 > 构建 设置屏幕，请检查以下四项。

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

iOS¶

在资产 > 外部依赖管理器 > iOS 解析器 > 设置中，取消选中static_framework构建设置。

打开在 Unity 构建过程中生成的 Podfile 并按如下配置。

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

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

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

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

将 GADApplicationIdentifier 键添加到 Unity 构建过程中生成的 Xcode 项目的 Info.plist 文件中，并将 AdMobId 值（格式为 ca-app-pub-XXXXX~YYYYY）作为键值输入。或者，您可以通过取消注释 Assets/HiveAdiz/Editor/AdizPostProcess.cs 文件中的 GADApplicationIdentifier 设置行并添加 AdMobId 来自动设置它。

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

此外，对于 iOS 14 及以上版本，请参考更新您的 info.plist指南，将 SKAdNetwork 列表添加到Info.plist文件中。Assets/HiveAdiz/Editor/AdizPostProcess.cs 文件将在构建过程中自动将其添加到Info.plist文件中。

测试广告设置¶

Adiz 可以通过两种方式显示测试广告。 1. 激活测试模式：仅显示由 AdMob 发布的测试广告 2. 注册测试设备后显示广告：显示真实广告以进行测试，确保不会发生无效流量，并通过注册设备来显示测试广告

激活测试模式¶

在开发阶段，激活测试模式，以便点击测试广告不会向广告主收费。激活测试模式时，只会显示测试广告。在测试模式下，即使未在控制台中输入 AdMob 广告密钥，也会显示测试广告。商业分发期间，测试模式被禁用。

有两种方法可以激活测试模式。

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

使用 Adiz.SetTestMode() 方法¶

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

// 启用 Adiz 模块日志记录。日志记录仅应在测试模式下使用。生产部署时请注释掉下面的行。  
Adiz.SetLogEnable(true);

测试设备广告曝光¶

您需要注册一个测试设备，以在以下情况下显示测试广告。

• 测试在 Hive 控制台中注册的 AdMob 广告密钥是否正常工作
• 撰写一条 GDPR 消息，并检查 GDPR 同意弹窗是否正常工作
• 运行 广告检查器 以分析和调试广告请求
  

在测试设备上显示广告有两种方式。

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

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

横幅广告、插页广告或奖励广告

原生广告

使用 Adiz.setTestDevice() 方法¶

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

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

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

• 在调用 Adiz.Initialize() 之后，无论广告类型如何，调用 initialize() → load() 并检查 Logcat 日志：
  

  `I/Ads: 使用 RequestConfiguration.Builder.setTestDeviceIds(Arrays.asList("33BE2250B43518CCDA7DE426D04EE231")) 在此设备上获取测试广告。
  

在Unity引擎的iOS环境中，测试设备ID（例如，B74F6468-1516-467C-99AD-CC5973C5DB52）可以通过以下两种方式进行检查。

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

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

• 调用 Adiz.Initialize() 后，无论广告类型如何，调用 initialize() → load() 并检查 Logcat 日志：

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

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

using hiveAdiz;

public void Initialize() {

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

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

广告检查器使用¶

广告检查器是一个应用内覆盖工具，实时分析在测试设备上请求和显示实际广告的过程。它会告知您加载广告所需的时间，并提供任何显示失败的原因。您还可以指定特定的广告网络，以检查广告是否正确显示，如果出现问题，您可以在代码级别进行调试。整个过程与广告检查器用户界面一起进行。它包含在 Google Mobile Ads SDK Android 20.0.0 和 Google Mobile Ads SDK iOS 7.68.0 或更高版本中，可以通过调用 AdizDeveloperTool.OpenAdInspector 使用。

要使用广告检查器，您必须注册一个测试设备。

using hiveAdiz;

AdizDeveloperTool.OpenAdInspector();

Adiz AppID 设置¶

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

Adiz.SetAppId(appId);

Hive 控制台服务器设置¶

设置要使用的 Hive 控制台服务器。默认值为 REAL。即使您使用生产服务器，启用测试模式也只会显示测试广告。

• Hive 测试控制台服务器: ZoneType.TEST
• Hive 沙盒控制台服务器: ZoneType.SANDBOX
• Hive 生产控制台服务器: ZoneType.REAL

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

用户特定广告曝光¶

随着在 iOS 14.5+ 中引入的 ATT（应用追踪透明度），隐私得到了增强。因此，只有在用户同意在 ATT 同意弹窗中进行活动追踪的情况下，才能显示用户特定的广告。为了通过展示用户特定广告来最大化广告收入，您需要创建一个 IDFA（广告标识符）消息。

在 Google AdMob 控制面板上撰写并发布 IDFA 消息，如下所示。

编写IDFA消息时，可以参考下面的指南。

• IDFA 实施指南
• IDFA 消息创建指南
• 关于 IDFA 消息和 ATT 通知的解释

当您在 AdMob 控制面板上发布 IDFA 消息时，IDFA 消息将在 iOS 14.5+ 的 Adiz 初始化期间自动显示。当用户在 IDFA 消息窗口中点击“继续”时，将显示 ATT 同意弹出窗口。

当用户在 ATT 同意弹窗上点击“允许”时，IDFA 被激活，并显示用户特定的广告。

GDPR同意弹窗曝光（欧洲，英国）¶

如果您的游戏面向欧洲和英国（欧洲经济区和英国），您必须曝光GDPR（通用数据保护条例）同意弹窗。只有当用户的设备IP地址来自欧洲和英国（欧洲经济区和英国）时，GDPR同意弹窗才会显示。Adiz通过Google UMP（用户消息平台）支持GDPR同意弹窗的曝光。在AdMob控制台中创建GDPR消息后，初始化Adiz以向来自欧洲和英国的用户显示GDPR弹窗。

编写 GDPR 消息¶

访问 Google AdMob 控制台以编写 GDPR 消息。在编写 GDPR 消息之前，请参考GDPR 消息编写指南。

在创建GDPR消息时，您需要将要使用的调解添加到广告合作伙伴列表中。 以下是添加调解的方法。

1) 在 Google AdMob 仪表板中，转到 隐私与消息 > 欧洲法规 > 设置 选项卡，然后单击“广告合作伙伴审核 > 自定义广告合作伙伴”的编辑图标。 2) 选择所有根据 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初始化代码中，在执行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）来指定谷歌是否应将内容视为儿童导向。如果您希望其被视为儿童导向，必须在执行Adiz.initialize之前调用AdizConsentManager.SetUserPrivacySettings。在使用Adiz与Hive SDK时，儿童导向处理标签会自动应用，因此无需单独配置。

using hiveAdiz;

public void Initialize() {

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

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

    AdizConsentManager.SetUserPrivacySettings(settings);

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

添加广告调解¶

Adiz 可以使用 AdMob 调解显示广告。要添加 AdMob 调解，请按照以下步骤操作。

添加 AdMob 中介¶

我们将继续在 AdMob 控制台中集成广告源。请按照下面的表格进行操作。

添加 Adiz 适配器¶

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

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

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

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

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

  </iosPods>
</dependencies>

要检查Adiz适配器配置是否已正确应用，请运行应用程序并检查广告检查器屏幕上的配置列表。

Adiz 初始化是显示任何类型广告之前必须执行的步骤。初始化 Adiz 允许您接收显示广告所需的广告密钥。如果启用了测试模式，您将收到测试密钥。

using hiveAdiz;

public void Start() {
    /* omitted */

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

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

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

    if(error.isSuccess()) {

        JSONObject resJsonObject = new JSONObject (jsonString);

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

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

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

            List jsonList = jsonArray.list;

            foreach (JSONObject jsonItem in jsonList) {

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

                // 这是在游戏中直接输入广告键时构建一个is_default为false的键列表的示例。
                if(isDefault == false) {
                    string hiveAdKey = null;
                    jsonItem.GetField(ref hiveAdKey, "key");

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

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

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

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

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

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

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

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

在初始化期间作为回调接收的JSON文件包含一个广告键的列表。广告键列表具有以下格式。

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

在测试模式下初始化时，即使您尚未在 Hive 控制台中注册 AdMob 广告密钥，您也会收到测试广告密钥的列表。在生产模式下初始化时，您将收到在 Hive 控制台中注册的 AdMob 广告密钥的列表。

对于每种类型的广告（form），一个广告被用作默认广告（即"is_default":true的广告）。当任何类型的第一个广告被注册时，该广告将成为默认广告。创建广告实例（initialize()）时，不需要输入广告密钥（hiveAdKey）来使用默认广告。要更改默认广告，您需要从HiveHive 控制台中删除现有的默认广告，并注册一个新的广告。

设置广告回调监听器¶

通过在创建每个广告实例时实现AdizListener，您可以根据广告状态的变化接收回调。

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

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

    // AdizInterstitial 已加载并准备好显示
    // requestShowAd();
}

private void OnAdLoadFailedCB(AdizError error) {
    // 这是在广告加载失败或因其他原因无法显示时调用的。
    Debug.Log(TAG + "::OnAdLoadFailedCB errorCode "+error.errorCode);
    Debug.Log(TAG + "::OnAdLoadFailedCB errorMessage "+error.errorMessage);
}

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

private void OnAdCloseCB()
{   
    // 这是在广告关闭时调用的。
    Debug.Log(TAG + "::OnAdCloseCB");

    // 显示AdizInterstitial广告后移除
    // requestDestroyAd();
}

private void OnAdClickCB()
{   
    // 这是在广告被点击时调用的。
    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()。

插页广告¶

占据整个屏幕的全屏广告。

// 创建 AdizInterstitial 实例
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() {
    // 销毁 AdizInterstitial
    if(InterstitialAd != null) InterstitialAd.Destroy();
    InterstitialAd = null;
}

横幅广告¶

这是一个显示特定大小横幅的广告。横幅广告不会接收 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() {
    // 销毁 AdizBanner
    if(BannerAd != null) BannerAd.Destroy();
    BannerAd = null;
}

原生广告¶

这是一个原生广告，展示了特定大小的原生模板。原生广告经过优化，适合竖屏使用，因此建议在竖屏游戏（纵向屏幕游戏）中使用。原生广告不会接收 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() {
    // 设置位置类型
    private PositionType bannerPosition = PositionType.TOP;

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

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

奖励广告¶

这是一个奖励广告，用户观看广告一定时间后会获得奖励。一旦奖励被授予，奖励项目信息将通过OnAdReward()回调接收。

// 创建 AdizRewarded 实例
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;
}

奖励插页广告¶

这是一个奖励插页广告，用户在观看广告一定时间后会获得奖励。一旦奖励发放，奖励项目信息将通过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() {
    // 销毁 AdizRewardedInterstitial
    if(RewardedInterstitialAd != null) RewardedInterstitialAd.Destroy();
    RewardedInterstitialAd = null;
}

应用启动广告 (AppOpen)¶

应用程序打开广告在应用程序从后台切换到前台时显示，展示一个使用 load() 预加载的广告。如果自广告加载以来已经过去超过 3 小时，则该广告将不会显示，并将自动重新加载。然后，该广告将在应用程序下次移至前台时显示。广告显示一次后，将不会自动重新加载，因此您必须再次调用 load() 来准备下一个广告。

// Create AdizAppOpen Instance
private AdizAppOpen AppOpenAd = null;

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


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

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


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

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

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

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

卸载 HiveAdiz¶

要卸载 HiveAdiz，请在您的 Unity 项目中删除以下文件夹。

• 资产/HiveAdiz
• 资产/HiveAdiz_示例

额外功能¶

从 Android 主线程调用¶

与 Android JNI 相关的 API 必须从 Unity 的主线程调用。如果您从主线程外部调用它们，Adiz 功能可能无法正常工作。如果您必须从非主线程调用，请使用 Adiz.RunOnMainThread 确保逻辑在主线程上运行。

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