Skip to content

Unity

Adkit for AD(X): Unity

AdKit is an advertising module designed to help users of SDKs and individual modules resolve errors that may occur when applying the Unity package provided by AD(X), and to improve ease of use.

This guide explains how to apply AdKit according to the supported SDK versions and provides instructions on how to call APIs for each available feature.

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.

Warning

When testing AdKit during development, you must apply the test ad key.

Update

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

How to use

iOS (Unity 2019.4 or later)

When you build an iOS project with Unity 2019.4 or later, a UnityFramework target that operates as a Dynamic Framework is created.

  1. Configure EDM4U. In Unity's iOS Resolver Settings (Assets > External Dependency Manager > iOS Resolver > Settings), check the static_framework build setting (Link frameworks statically). (1.2.171) Facebook SDK is available only as a Dynamic Framework, while Podfile configuration supports only one of the two framework types. Therefore, when Link frameworks statically is enabled, uncomment the entries below for the Facebook SDK you use. 

    string[] frameworksToEmbed = {
    ...
    "FBAudienceNetwork.xcframework",

    // If you use Facebook SDK, uncomment the entry for the SDK you use.
    // "FBAEMKit.xcframework",
    // ...
};

    Warning
    • Uncomment only the Facebook SDK currently in use.
    • If Link frameworks statically is disabled, uncommenting these entries while using Dynamic Frameworks may cause conflicts.

  2. Build the project.

    Warning

    If pod install fails while generating the Xcode project and Link frameworks statically was enabled above, do not run pod install directly in the generated project path. Rebuild the project in the Unity Editor.

Features

  • Rewarded ads
    • When using the AdKit API and SDK together, or using individual modules, whether log information is sent depends on the RewardVideo API called. Log information is sent to the analytics server. The minimum versions that support this feature are as follows:
      • SDK v4.11.0
      • SDK v1.17.2
      • Individual module ModuleManager v2.6.0
      • Individual module CommonModule v1.5.0
  • Interstitial ads
  • Adaptive banner ads

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.

Important

If you are using the Hive SDK, you must execute AuthV4.setup after completing the initialization of Hive AdKit. If the GDPR consent screen appears after displaying the ATT (APP Tracking Transparency) consent notification, your app may be rejected during Apple's app review.

// 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.

Targeting Other Regions

When targeting regions outside Europe and the UK, initialize with InitializeWithSetConsentState.

/*
 * Set the 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
 */
int consentState = 1;
HIVEAdKit.InitializeWithSetConsentState(appId, consentState);

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.

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>.

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.

 

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.

 

Error Codes

You can find the codes and messages for ad failures in AD(X)'s Ad Error.

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/GoogleMobileAds
      • /Assets/Plugins/Android/GoogleMobileAdsPlugins
Note

The list of files related to AD(X) may vary depending on the AD(X) version included in AdKit.