Unity

Adkit for AD(X): Unity¶

AdKit 是一個廣告模組，修正了在處理 AD(X) Unity 套件時發生的錯誤，並支持用戶便利性。逐步閱讀此頁面以使用 AdKit 以及支持 SDK。

安裝¶

訪問 Hive 開發者並下載和應用 AdKit。

從 Hive 開發者下載最新版本的 AdKit 並在這裡解壓縮。
在 Unity 工具欄中，選擇 .unitypackage 文件，位於 資產 > 匯入包 > 自訂包…，然後點擊匯入。

匯入完成後，檢查是否在 Assets 資料夾下創建了與 AdKit 和 AD(X) 相關的檔案和資料夾。

Warning

在開發期間測試 AdKit 時，您必須應用測試廣告金鑰。

更新¶

卸載您正在使用的 AdKit，並安裝最新版本以進行更新。

如何使用¶

iOS (Unity 2019.4 及以上版本)¶

在 Unity 2019.4 及以上版本中构建 iOS 项目时，会创建一个名为 UnityFramework 的目标，它作为动态框架运行。

EDM4U 配置（基于版本 1.2.171）确保在 Unity 的 iOS Resolver Settings 中启用了 static_framework 构建设置（菜单：Assets > External Dependency Manager > iOS Resolver > Settings）。
從 Hive AdKit 的 1.5.0 版本開始，AppLovinSDK 作為動態框架提供。因此，如果您使用 static_framework，則必須執行以下步驟。

在 Assets/HIVEAdKit/Editor/AdKitPostprocess.cs 文件中，取消註解 iOSAdd_DynamicFrameworks 函數中的 dynamicFramework Import。註解位置如下。
```
(string Name, string Source) [] dynamicFrameworks = {
    // 如果您從 Hive AdKit 的 1.5.0 版本開始使用 AppLovinSDK 並已設置 Pod Static，請取消註解下面的 AppLovinSDK 行。
    // ("AppLovinSDK.xcframework", "Pods/AppLovinSDK/applovin-ios-sdk-12.6.1"),
}
```
Warning

只有在static_framework启用并且您正在构建时，才可以取消注释。在使用动态框架时取消注释可能会导致冲突。

建立專案。建置完成後，打開生成的專案根路徑中的 Podfile 以檢查檔案設定。

source 'https://github.com/adxcorp/AdxLibrary_iOS_Release.git'
source 'https://cdn.cocoapods.org/'

platform :ios, '12.0'

target 'UnityFramework' do
    pod 'ADXLibrary', '2.6.2'
    pod 'Google-Mobile-Ads-SDK', '~> 11.8.0'
end
target 'Unity-iPhone' do
end
use_frameworks!

继续进行 Xcode 配置。

iOS: 解決 Facebook SDK 與廣告模組之間的衝突¶

雖然 Facebook SDK 只提供動態框架，但廣告模組僅提供靜態框架，而 Podfile 配置僅支持這兩種方法中的一種。因此，為了在 Unity 中的應用程序構建期間應用 Facebook SDK，您需要解決 Facebook SDK 和廣告模組之間的衝突，如下所示。

<

在HIVEAdKit/Editor/AdKitPostprocess.cs文件中的iOSAdd_DynamicFrameworks函数中取消对您正在使用的Facebook SDK的注释，以嵌入动态SDK。

   (string Name, string Source) [] dynamicFrameworks = {
       // If you are using AppLovinSDK starting from version 1.5.0 of Hive AdKit and have set Pod Static, uncomment the AppLovinSDK line below.
       // ("AppLovinSDK.xcframework", "Pods/AppLovinSDK/applovin-ios-sdk-12.6.1"),

       // If you are using the Facebook SDK, uncomment the lines below according to the SDK type you are using.
       // ("FBAEMKit.xcframework","Pods/FBAEMKit/XCFrameworks"),
       // ("FBSDKCoreKit_Basics.xcframework","Pods/FBSDKCoreKit_Basics/XCFrameworks"),
       // ("FBSDKCoreKit.xcframework","Pods/FBSDKCoreKit/XCFrameworks"),
       // ("FBSDKLoginKit.xcframework","Pods/FBSDKLoginKit/XCFrameworks"),
       // ("FBSDKShareKit.xcframework","Pods/FBSDKShareKit/XCFrameworks"),
       // ("FBSDKGamingServicesKit.xcframework","Pods/FBSDKGamingServicesKit/XCFrameworks")
   };

Warning

您必須僅取消註解您當前正在使用的 Facebook SDK。

特點¶

獎勵類型
- AD(X) 不提供廣告曝光的 API，但通知遵循AdMob 指南。
- 發送日誌取決於調用的 RewardVideo API，如果使用 AdKit API 和 Hive SDK。日誌數據將發送到分析伺服器，支持此功能的最低版本如下。
  - Hive SDK v4.11.0
插頁式廣告類型
自適應橫幅類型

有關如何使用 AdKit 的詳細資訊，請閱讀以下指南。

初始化 AdKit¶

初始化、加載和顯示所有類型廣告（AD）之前的必要步驟

歐洲和英國目標¶

如果您的游戏面向欧洲和英国（EEA和英国），则必须显示GDPR（通用数据保护条例）同意弹出窗口。Adkit支持谷歌的UMP（用户消息平台）来显示GDPR同意弹出窗口。要使用谷歌UMP，请首先参考GDPR消息创建指南来编写您的GDPR消息。

使用 Hive SDK 时，AuthV4.setup 会暴露 IDFA 消息，因此构建 IDFA 消息在根本上是可选的。然而，如果您使用的是 GDPR 消息，则必须根据有关 IDFA 消息和 ATT 通知的详细说明构建 IDFA 消息。

如果您已經製作了GDPR消息和IDFA消息，請使用InitializeWithShowADXConsent初始化Hive AdKit，如下所示。

Important

如果您正在使用Hive SDK，則必須在完成Hive AdKit的初始化後執行AuthV4.setup。如果在顯示ATT（應用程序跟踪透明度）同意通知後出現GDPR同意屏幕，則您的應用可能會在Apple的應用審核中被拒絕。

// When targeting Europe & the UK for commercial distribution
int debugState = 0;
HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, null, adkitConsentState =>
{
    /*
    * adkitConsentState : User's personal information usage and collection status for AD(X)
    * - 0 : No consent status exists
    * - 1 : Region where consent is not required
    * - 2 : User has refused the usage and collection of personal information
    * - 3 : User has consented to the usage and collection of personal information
    */
});

/* 
 * To test the GDPR consent popup, set debugState to 1 and configure testDeviceId to display the GDPR test popup.
 * The device ID for the Test Device (testDeviceId) can be found in the Android Logcat and Xcode console logs.
 * The testDeviceId is used only for testing. You must specify testDeviceId as null during commercial distribution.
 * Example Android log: Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("ABCDEFGHIJKLMNOPQRSTUVWXYZ") to set this as a debug device.
 * Example Xcode log: To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[ABCDEFGHIJKLMNOPQRSTUVWXYZ]
 */

int debugState = 1;
string testDeviceId = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
List testDevices = new List();
testDevices.Add(testDeviceId);

HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, testDevices, adkitConsentState =>
{
    /*
    * adkitConsentState : User's personal information usage and collection status for AD(X)
    * - 0 : No consent status exists
    * - 1 : Region where consent is not required
    * - 2 : User has refused the usage and collection of personal information
    * - 3 : User has consented to the usage and collection of personal information
    */
});

當初始化 Hive AdKit 時，如果目標區域被確定為歐洲和英國（EEA 和 UK），則將自動顯示 GDPR 同意屏幕，如下所示。

在iOS環境中，IDFA解釋信息會在歐洲和英國以外的地區自動顯示。

高級設定¶

// GameData Example
[Serializable]
public class SendInfo 
{
    public int level;
    public int gold;
}
SendInfo addtionalInfo = new SendInfo();
addtionalInfo.level = 1;
addtionalInfo.gold = 100;

// Send as a JSON Obejct format
HIVEAdKit.SetAdditionalInfo(JsonUtility.ToJson(addtionalInfo));

獎勵類型¶

// Initialize Rewarded AD
// Initialize Rewarded AD
EventHandlers eventHandlers = new EventHandlers.Builder()
                                                .OnAdLoaded(OnAdLoadedCB)
                                                .OnAdOpening(OnAdOpeningCB)
                                                .OnAdClosed(OnAdClosedCB)
                                                .OnAdFailedToLoad(OnAdFailedToLoadCB)
                                                .OnAdFailedToShow(OnAdFailedToShowCB)
                                                .OnAdReward(OnAdRewardCB)
                                                .OnPaidEvent(OnPaidEventCB)
                                                .Build();
// Generate an instance
RewardVideoAd = HIVEAdKit.RewardVideo.Initialize(rewardVideoUnitId, eventHandlers);

// Load Rewarded AD
// Send AD loading information to Analytics
if( HIVEAdKit.RewardVideo.IsInitialzed(RewardVideoAd) ) {
    HIVEAdKit.RewardVideo.LoadAd(RewardVideoAd, "Unity-AdaptiveBanner-Show-AdditionalInfo");
}

// Show RewardVideo type
// Send AD loading information to Analytics
if( HIVEAdKit.RewardVideo.IsLoaded(RewardVideoAd) ) {
    HIVEAdKit.RewardVideo.Show(RewardVideoAd, "Unity-AdaptiveBanner-Show-AdditionalInfo");
}

插頁類型¶

EventHandlers eventHandlers = new EventHandlers.Builder()
                                                .OnAdLoaded(OnAdLoadedCB)
                                                .OnAdOpening(OnAdOpeningCB)
                                                .OnAdClosed(OnAdClosedCB)
                                                .OnAdFailedToLoad(OnAdFailedToLoadCB)
                                                .OnAdClick(OnAdClickCB)
                                                .OnPaidEvent(OnPaidEventCB)
                                                .Build();
// Generate an instance
InterstitialAd = HIVEAdKit.Interstitial.Initialize(InterstitialAdUnitId, eventHandlers);

// Load
// Send AD loading information to Analytics
if( HIVEAdKit.Interstitial.IsInitialzed(InterstitialAd) ) {
     HIVEAdKit.Interstitial.Load(InterstitialAd, "Unity-AdaptiveBanner-Show-AdditionalInfo");
}

// Show
// Send AD loading information to Analytics
if( HIVEAdKit.Interstitial.IsLoaded(InterstitialAd) ) {
     HIVEAdKit.Interstitial.Show(InterstitialAd, "Unity-AdaptiveBanner-Show-AdditionalInfo");
}

自適應橫幅類型¶

EventHandlers eventHandlers = new EventHandlers.Builder()
                                                            .OnAdLoaded(OnBannerAdLoadedCB)
                                                            .OnAdOpening(OnAdOpeningCB)
                                                            .OnAdClosed(OnAdClosedCB)
                                                            .OnAdFailedToLoad(OnAdFailedToLoadCB)
                                                            .OnAdClick(OnAdClickCB)
                                                            .OnPaidEvent(OnPaidEventCB)
                                                            .Build();
HIVEAdKit.AdaptiveBanner.AdPosition bannerPosition = HIVEAdKit.AdaptiveBanner.AdPosition.Top;
HIVEAdKit.AdaptiveBanner.AdSize adaptiveSize = HIVEAdKit.AdaptiveBanner.AdSize.AD_SIZE_320x50;

// Generate an instance
AdaptiveBannerAd = HIVEAdKit.AdaptiveBanner.Initialize(AdaptiveBannerAdUnitId, adaptiveSize, bannerPosition, eventHandlers);

// Load and show
// Send AD loading information to Analytics
HIVEAdKit.AdaptiveBanner.LoadAd(AdaptiveBannerAd, "Unity-AdaptiveBanner-Show-AdditionalInfo");

// Hide
HIVEAdKit.AdaptiveBanner.Destroy(AdaptiveBannerAd);

支援 iOS 14¶

以下是支持 iOS 14 及更高版本的 SKAdNetwork AD(X) 列表。AdKitPostprocess 基于 2021 年 1 月 29 日的更新。别忘了查看最新更新。

SKAdNetwork 更新
- https://github.com/adxcorp/ADXLibrary_Integration/wiki/SKAdNetwork-ID-List

支援 Android 11¶

一個標籤 <queries> 被添加到 AD(X) 庫的 AndroidManifest.xml 文件中，以支持 Android 11。如果您在 Unity 上構建項目時查看以下錯誤日誌，請參考與 Unity-Android 11 一起構建的指南。

Unity上的範例錯誤日誌

  AndroidManifest.xml: AAPT: error: unexpected element <queries> found in <manifest>.

使用 Unity-Android 11 建立的指導方針
- https://developers.google.com/ar/develop/unity/android-11-build

ADX Proguard 設定¶

該庫的AAR文件包含Proguard的規則，因此設置會自動執行。

Unity 整合通知

¶

如果在 GoogleMobileAdsSettings 上移除了 App ID，请前往 Unity > Assets > Google Mobile Ads > Settings，然后选择 延迟应用测量 复选框，再次清除它。

Gradle 和 Gradle 插件版本配置¶

我們建議使用 Gradle 6.7.1 或更新版本來搭配 Adkit 1.4.4 或更高版本。如果您使用較低版本的 Gradle 來搭配 Adkit 1.4.4 或更高版本，您可能會遇到來自 AdMob Unity 插件的 "此功能需要 ASM7" 錯誤，這可以通過以下解決方案之一來解決。

更改 Gradle 和 Gradle 插件版本（推荐解决方案）
更新 Unity 引擎
注释 android.enableDexingArtifactTransform=false

如何更改Gradle和Gradle插件版本（至Gradle 6.7.1+，至Gradle插件4.2.0+），請參考以下步驟。

更改為使用自定義基礎Gradle模板。
- 檢查構建設置 > 項目設置 > 播放器 > 自定義基礎Gradle模板。
- Assets/Plugins/Android/baseProjectTemplate.gradle將會生成。
更改Gradle插件版本。打開Assets/Plugins/Android/baseProjectTemplate.gradle文件並將版本更改為：com.android.tools.build:gradle:4.2.0
下載Gradle。Gradle 6.7.1可以在這裡下載。下載後，將下載的文件解壓縮到您想要的位置（例如：~/Users/honggd/gradle-6.7.1）。
在Unity中更改Gradle安裝路徑。
1. 取消選中首選項 > 外部工具 > 與Unity一起安裝的Gradle。
2. 將安裝路徑設置為您解壓縮下載的Gradle文件的目錄（例如：~/Users/honggd/gradle-6.7.1）。
確保播放器 > 其他設置 > 識別 > 目標API級別為33或更高，然後構建您的項目。

測試廣告¶

對於廣告商來說，在開發過程中測試廣告被點擊時不被收費是很重要的。如果您在測試模式之外過多地點擊廣告，將被視為無效行為。因此，請注意不要成為被報告的目標帳戶。請參考Google Developers以使用測試廣告。

卸載¶

要卸載 AdKit for AD(X)，請刪除以下文件和文件夾列表。

- 與 AdKit 相關
  - /Assets/HIVEAdKit
  - /Assets/HIVEAdKit_Example
- 與 AD(X) 相關
  - /Assets/ADXLibrary
  - /Assets/GoogleMobilesAds
  - /Assets/MoPub
  - /Assets/Plugins/Android/GoogleMobileAdsPlugins

Note

與 AD(X) 相關的文件列表可能會根據 AdKit 中包含的 AD(X) 版本而有所不同。