Unity

Adkit for AD(X): Unity¶

AdKit is an advertisement module which fixes errors occurred in processing AD(X) Unity package and supports user convenience. Read this page one by one for using AdKit as well as support SDK.

Installation¶

Access Hive Developers and download and apply AdKit.

1. Download the latest version of AdKit from Hive Developers and unzip it here.
2. In the Unity toolbar, select .unitypackage file under Assets > Import Package > Custom Package… and click Import.

1. After import completion, check if AdKit and AD(X) related files and folders are created under the Assets folder.

Update¶

Uninstall the AdKit you are using and install the latest version to update.

How to use¶

iOS (Unity 2019.4 and above)¶

When building an iOS project in Unity 2019.4 and above, a target called UnityFramework is created, which operates as a Dynamic Framework.

1. EDM4U Configuration (based on version 1.2.171) Ensure that the static_framework build setting is enabled in Unity's iOS Resolver Settings (Menu: Assets > External Dependency Manager > iOS Resolver > Settings).

2. Starting from version 1.5.0 of Hive AdKit, AppLovinSDK is provided as a Dynamic Framework. Therefore, if you are using static_framework, you must perform the following steps.
   
   In the Assets/HIVEAdKit/Editor/AdKitPostprocess.cs file, uncomment the dynamicFramework Import in the iOSAdd_DynamicFrameworks function. The comment location is as follows.

   (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"),
   }
   

   Warning

   You must only uncomment when static_framework is enabled and you are building. Uncommenting while using the Dynamic Framework can cause conflicts.

3. Build the project. Once the build is complete, open the Podfile in the generated project root path to check the file settings.

   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!
   

4. Proceed with Xcode configuration.

iOS: Resolving Conflicts Between Facebook SDK and Ad Modules¶

While the Facebook SDK only offers a Dynamic Framework, the ad module only offers a Static Framework, and the Podfile configuration supports only one of these methods. Therefore, to apply the Facebook SDK during the app build in Unity, you need to resolve conflicts between the Facebook SDK and the ad module as follows.

Remove the comment for the Facebook SDK you are using in the HIVEAdKit/Editor/AdKitPostprocess.cs file in the iOSAdd_DynamicFrameworks function to embed the Dynamic 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")
   };

Features¶

• Rewarded type
  • AD(X) does not provide an API for advertisement exposure but informs to follow the AdMob guide.
  • Sending log is determined depending on the called RewardVideo API if AdKit API and Hive SDK are in use. Log data is sent to Analytics server, and the minimum version which supports this feature is as follows.
    • Hive SDK v4.11.0
• Interstital type
• Adaptive banner type

For details how to use AdKit, read the following guide.

Initializing AdKit¶

Required step before initializing, loading and showing all types of advertisement (AD)

European and UK targeting¶

If your game targets Europe and the UK (EEA & UK), it is required to display a GDPR (General Data Protection Regulation) consent popup. Adkit supports Google's UMP (User Messaging Platform) for displaying the GDPR consent popup. To use Google UMP, first, refer to the GDPR Message Creation Guide to compose your GDPR message.

When using the Hive SDK, AuthV4.setup exposes the IDFA message, so crafting the IDFA message is fundamentally optional. However, if you are using the GDPR message, you must craft the IDFA message according to the detailed explanation about IDFA messages and ATT notifications.

If you have crafted both the GDPR message and the IDFA message, initialize Hive AdKit with InitializeWithShowADXConsent as shown below.

// 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
    */
});

When initializing Hive AdKit, if the targeted region is determined to be Europe and the UK (EEA & UK), the GDPR consent screen will be automatically displayed as shown below.

In the iOS environment, the IDFA explanation message is automatically displayed in regions outside Europe and the UK.

Advanced settings¶

// 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));

Rewarded type¶

// 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");
}

Interstitial type¶

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");
}

Adaptive banner type¶

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);

Supporting iOS 14¶

Following is SKAdNetwork list of AD(X) for supporting iOS 14 and later version. AdKitPostprocess is based on the update on January 29, 2021. Don't forget to check the latest update.

• SKAdNetwork update
  • https://github.com/adxcorp/ADXLibrary_Integration/wiki/SKAdNetwork-ID-List  

Supporting Android 11¶

A tag <queries> is added to the AndroidManifest.xml file of AD(X) library by supporting Android 11. If you check the error log as follows while building your project on Unity, refer to the guidelines to build with Unity-Android 11.

• Sample error log on Unity

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

• Guidelines to build with Unity-Android 11
  • https://developers.google.com/ar/develop/unity/android-11-build  

ADX Proguard setting¶

The library AAR file includes the rule of Proguard, so that the setting carries out automatically.  

Unity integrate notice

If the App ID on GoogleMobileAdsSettings is removed, go to Unity > Assets > Google Mobile Ads > Settings and select the Delay app measurement checkbox, then clear it again.

Gradle & Gradle Plug-in version configuration¶

We recommend Gradle 6.7.1 or a newer version for Adkit 1.4.4 or higher. If you use lower Gradle versions for Adkit 1.4.4 or higher, you may encounter "This feature requires ASM7" error from AdMob Unity plug-in, which can be resolved through one of the following solutions.

• Change Gradle and Gradle Plug-in version (the recommended solution)
• Update Unity engine
• Annotate android.enableDexingArtifactTransform=false

For how to change Gradle and Gradle Plug-in version (to Gradle 6.7.1+, to Gradle Plugin 4.2.0+), refer to the steps below.

1. Change to use Custom Base Gradle Template.
   • Check Build Settings > Project Settings > Player > Custom Base Gradle Template.
   • Assets/Plugins/Android/baseProjectTemplate.gradle will be generated.
2. Change Gradle Plug-in version. Open Assets/Plugins/Android/baseProjectTemplate.gradle file and change the version like this: com.android.tools.build:gradle:4.2.0
3. Download Gradle. Gradle 6.7.1 can be downloaded at here. After downloading it, unzip the downloaded file at the place you want (example: ~/Users/honggd/gradle-6.7.1).
4. Change the Gradle installation path in Unity.
   1. Uncheck Preferences > External Tools > Gradle Installed with Unity.
   2. Set the installation path to the direactory you unzipped the downloaded Gradle file (example: ~/Users/honggd/gradle-6.7.1).
5. Make sure that Player > Other Settings > Identification > Target API Level is 33 or higher, and build your project.

Test Ads¶

It is important for advertiser not to be charged when test ad is clicked in development. If you click ads too much out of test mode, it is regarded as invalid action. Therefore, be aware not to be a target account to report. Refer to the Google Developers to use a test ad.

Uninstallation¶

To uninstall AdKit for AD(X), delete the following list of files and folders.

• • Related to AdKit
    • /Assets/HIVEAdKit
    • /Assets/HIVEAdKit_Example
  • Related to AD(X)
    • /Assets/ADXLibrary
    • /Assets/GoogleMobilesAds
    • /Assets/MoPub
    • /Assets/Plugins/Android/GoogleMobileAdsPlugins