Hive Adiz Android

Hive Adiz Android is an advertising module for Android provided by Hive to make it easier to use the advertising exposure features offered by AdMob. The types of advertisements provided by Hive Adiz Android are as follows:

• Interstitial ads
• Banner ads
• Native ads
• Rewarded ads
• Rewarded Interstitial ads
• App Opening ads

To install and use Hive Adiz Android, please refer to the guide below in order.

Installation

Add the Hive Adiz library item to the app-level Gradle file (app/build.gradle) of your module.

 

To support Java 8 features, add the following to your module’s app-level Gradle file with the android setting.

 

Enter your AdMobId (in the format ca-app-pub-XXXXX~YYYYY) in the AndroidManifest.xml file.

 

When using Proguard, the Proguard rules for the Hive Adiz are already included in the Adiz module. Therefore, there is no need to add Proguard rules to your project.

 

To display video ads, hardware acceleration must be enabled. Add the following settings for hardware acceleration in the AndroidManifest.xml file. Adding to the application tag will use hardware acceleration for the entire application. Adding to the activity tag will use hardware acceleration only for the specific Activity where you want to display ads.

Setup Test Ads

Hive Adiz allows you to display test ads in two ways.

1. Enable test mode: Only display test ads issued by AdMob.
2. Register test devices and display ads: Display real ads for testing purposes. Register the devices to display test ads to ensure no invalid traffic occurs during testing.

Enable Test Mode

During the development phase, enable test mode so that clicks on test ads do not incur charges to advertisers. When test mode is enabled, only AdMob test ads are displayed. In test mode, you do not need to enter the AdMob ad key in the Hive console to display test ads. Disable test mode for commercial distribution.

Setting up test devices for ad display

You should register a test device to display test ads in the following situations:

• When testing if the AdMob ad key registered in the Hive console works properly
• When you want to ensure the GDPR consent popup is working correctly after you wrote a GDPR message
• When you need to run the Ad Inspector to analyze and debug ad requests

Testing with real ads without registering a test device may be considered invalid traffic, leading to your AdMob account being blocked and no longer being able to display ads. When you register a test device, “Test Mode” or “Test Ad” (for native ads) will be displayed during ad display. Test devices should be disabled for production deployment.

 

Banner, Interstitial, or Rewarded Ad

 

Native Ad

 

To register a test device, first, identify your test device ID. You can find the test device ID (e.g., 33BE2250B43518CCDA7DE426D04EE231) using the following two methods:

1. After calling Adiz.Initialize(), check the Logcat log:
   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
2. After calling Adiz.Initialize(), regardless of the ad type, call initialize() → load(), then check the Logcat log:
   I/Ads: Use RequestConfiguration.Builder.setTestDeviceIds(Arrays.asList("33BE2250B43518CCDA7DE426D04EE231")) to get test ads on this device."

 

After identifying the test device ID, add the line Adiz.setTestDevice(DEVICE_ID) before executing Adiz.initialize in the existing Hive Adiz initialization code. Replace DEVICE_ID with the copied test device ID.

 

Using the Ad Inspector

The Ad Inspector is an in-app overlay tool that analyzes the process of requesting and displaying real ads on a test device in real-time. It informs you of the time it took to load the ad and, if the display failed, provides the reason for the failure. Additionally, you can specify a certain ad network to check if ads are being displayed correctly, and if there are issues, you can debug at the code level. All these processes are conducted with the Ad Inspector UI. It is included in Google Mobile Ads SDK Android 20.0.0 and above, and can be used by calling AdizDeveloperTool.openAdInspector.

 

To use the Ad Inspector, the following two conditions must be met:

• Set up the test device with Adiz.setTestDevice as per Setting up test devices
• Complete initialization with Adiz.Initialize as per Initialization

Setting Hive Adiz AppID

Set the Hive Adiz AppID you registered in the Hive console AppCenter. If not set, the AndroidManifest.xml package name is used.

Setting Hive Console Server

Set the Hive console server you want to use. The default is REAL. Even if you use the commercial server, test ads are displayed if test mode is enabled.

• Hive test console server: ZoneType.TEST
• Hive sandbox console server: ZoneType.SANDBOX
• Hive commercial console server: ZoneType.REAL

GDPR Consent Popup Display (Europe and UK)

If your game targets Europe and the UK (EEA & UK), it is required to display a GDPR (General Data Protection Regulation) consent popup. The GDPR consent popup will only be shown if the user’s device IP address is from Europe or the UK (EEA & UK). Hive Adiz supports Google‘s UMP (User Messaging Platform) for displaying the GDPR consent popup.

After creating the GDPR message in the AdMob console, the GDPR popup will be displayed to users accessing from Europe and the UK when you initialize Hive Adiz.

Creating GDPR Message

Access the Google AdMob console to create the GDPR message. Before creating the GDPR message, refer to the GDPR message creation guide.

After creating the GDPR message, the GDPR consent popup will automatically be displayed during the initialization of Hive Adiz.

Implementing Options for GDPR Consent/Withdrawal

The GDPR consent popup should allow users to modify their consent at any time. For instance, users who initially did not consent to GDPR but wish to receive personalized ads may want to consent, or vice versa. To accommodate such scenarios, developers must implement functionality for users to either consent again or withdraw their previous consent. To implement GDPR consent/withdrawal functionality, follow these steps:

1. Implement a button UI in your app to reload the GDPR consent popup window.
2. When implementing the initialization of Hive Adiz, call isPrivacyOptionsRequired() to display the button UI above for users accessing from Europe and the UK, and not display it otherwise. If users from Europe and the UK press the button, call showPrivacyOptionsForm to reload the GDPR consent popup, allowing users to modify their consent for GDPR details at any time through a “Manage Options” button or similar within the app. The showPrivacyOptionsForm method provided below is for illustration purposes only and can be implemented in any form desired by the developer.
Kotlin

import com.hive.Adiz import com.hive.adiz.AdizError import com.hive.AdizConsentManager import org.json.JSONObject fun initialize() { // ... Adiz.initialize(activity, object : Adiz.SdkInitializationListener { override fun onComplete(error: AdizError, jsonData: JSONObject?) { if(error.isSuccess) { // ... Skipped // Determine whether to display a button on the app UI to show the GDPR consent popup again var isPrivacyOptionsRequired = AdizConsentManager.isPrivacyOptionsRequired() if(isPrivacyOptionsRequired) { // Display the button in the app. (When the button is clicked, call showPrivacyOptionsForm() to display the GDPR consent popup) showGDPRConsentPopupButton() } else { // Will not display the button in the app. // Perform other desired actions within the app. } } } }) } fun showPrivacyOptionsForm(activity: Activity) { // Call the GDPR consent popup if(AdizConsentManager.isPrivacyOptionsRequired()) { AdizConsentManager.showPrivacyOptionsForm(activity, object : AdizConsentManager.ConsentListener { override fun onResult(error: AdizError) { addLog("AdizConsentManager.showPrivacyOptionsForm() errorCode : ${error.getCode()}, errorMessage : ${error.getMessage()}}\n") // No need to do any error handling. } }) } }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

import com.hive.Adiz import com.hive.adiz.AdizError import com.hive.AdizConsentManager import org.json.JSONObject      fun initialize() {     // ...     Adiz.initialize(activity, object : Adiz.SdkInitializationListener {         override fun onComplete(error: AdizError, jsonData: JSONObject?) {                  if(error.isSuccess) {                 // ... Skipped                 // Determine whether to display a button on the app UI to show the GDPR consent popup again                 var isPrivacyOptionsRequired = AdizConsentManager.isPrivacyOptionsRequired()                 if(isPrivacyOptionsRequired) {                     // Display the button in the app. (When the button is clicked, call showPrivacyOptionsForm() to display the GDPR consent popup)                     showGDPRConsentPopupButton()                 } else {                     // Will not display the button in the app.                     // Perform other desired actions within the app.                 }             }         }     }) }           fun showPrivacyOptionsForm(activity: Activity) {          // Call the GDPR consent popup     if(AdizConsentManager.isPrivacyOptionsRequired()) {         AdizConsentManager.showPrivacyOptionsForm(activity, object : AdizConsentManager.ConsentListener {             override fun onResult(error: AdizError) {                 addLog("AdizConsentManager.showPrivacyOptionsForm() errorCode : ${error.getCode()}, errorMessage : ${error.getMessage()}}\n")                 // No need to do any error handling.             }         })     } }

Java

import com.hive.Adiz; import com.hive.adiz.AdizError; import com.hive.AdizConsentManager; import org.json.JSONObject; public void initialize() { Adiz.initialize(activity, new Adiz.SdkInitializationListener() { @Override public void onComplete(@NonNull AdizError error, @Nullable JSONObject jsonData) { if(error.isSuccess()) { // ... Skipped // Determine whether to display a button on the app UI to show the GDPR consent popup again boolean isPrivacyOptionsRequired = AdizConsentManager.isPrivacyOptionsRequired(); if(isPrivacyOptionsRequired) { // Display the button in the app. (When the button is clicked, call showPrivacyOptionsForm() to display the GDPR consent popup) showGDPRConsentPopupButton() } else { // Will not display the button in the app. // Perform other desired actions within the app. } } } }); } public void showPrivacyOptionsForm(Activity activity) { // Call the GDPR consent popup if(AdizConsentManager.isPrivacyOptionsRequired()) { AdizConsentManager.showPrivacyOptionsForm(activity, new AdizConsentManager.ConsentListener() { @Override public void onResult(@NonNull AdizError error) { // No need to do any error handling. } }); } }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

import com.hive.Adiz; import com.hive.adiz.AdizError; import com.hive.AdizConsentManager; import org.json.JSONObject;           public void initialize() {     Adiz.initialize(activity, new Adiz.SdkInitializationListener() {         @Override         public void onComplete(@NonNull AdizError error, @Nullable JSONObject jsonData) {                  if(error.isSuccess()) {                 // ... Skipped                 // Determine whether to display a button on the app UI to show the GDPR consent popup again                 boolean isPrivacyOptionsRequired = AdizConsentManager.isPrivacyOptionsRequired();                 if(isPrivacyOptionsRequired) {                     // Display the button in the app. (When the button is clicked, call showPrivacyOptionsForm() to display the GDPR consent popup)                     showGDPRConsentPopupButton()                 } else {                     // Will not display the button in the app.                     // Perform other desired actions within the app.                 }             }         }     }); }           public void showPrivacyOptionsForm(Activity activity) {     // Call the GDPR consent popup     if(AdizConsentManager.isPrivacyOptionsRequired()) {         AdizConsentManager.showPrivacyOptionsForm(activity, new AdizConsentManager.ConsentListener() {             @Override             public void onResult(@NonNull AdizError error) {                 // No need to do any error handling.             }         });     } }

Setting Tag For Under the Age of Consent

Using the Tag For Under the Age of Consent (TFUA), you can configure ad requests to treat users residing in the European Economic Area (EEA), the United Kingdom, and Switzerland as subjects to limited data processing. For apps that serve children, you can set that the user is under the age of consent using AdizConsentManager.setUserPrivacySettings. While there are some differences between European countries, GDPR defines the age requiring parental consent as under 16. The age of consent setting must be configured before executing Adiz.initialize.

 

Setting up GDPR Test Devices

The GDPR consent popup is displayed only if the device’s IP address is from Europe or the UK. During development, you can force the GDPR consent popup to display regardless of the device IP address for testing purposes by setting up GDPR test devices. Follow the steps below to set up GDPR test devices. The following content is the same as Displaying ads on a test device.

1. Initialize Hive Adiz. The purpose of this initialization is to check the test device ID, so you don’t need to create a GDPR consent message in advance.
2. Find the device ID in the Logcat log output. Here’s an example message:

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.

   Get the device ID (example: 33BE2250B43518CCDA7DE426D04EE231).

3. Copy the device ID.
4. Add Adiz.setTestDevice(DEVICE_ID) before executing Adiz.initialize in the existing Hive Adiz initialization code.
5. Create a GDPR consent message and reinitialize Hive Adiz to ensure the GDPR consent popup appears correctly.

Setting the Tag for Child-Directed Treatment

In accordance with the Children’s Online Privacy Protection Act (COPPA), app developers can specify whether Google should treat content as child-directed during ad requests by setting the tagForChildDirectedTreatment (TFCD). If you wish the content to be treated as directed towards children, you must call AdizConsentManager.setUserPrivacySettings before executing Adiz.initialize. When using Hive Adiz with the Hive SDK, the tag for child-directed treatment is automatically applied, so no additional settings are required.

Add mediation for ads

Hive Adiz allows displaying ads using AdMob mediation. To add AdMob mediation, follow the steps below.

Add AdMob mediation

Proceed with integrating the ad sources in the AdMob console. Follow the table below.

	AppLovin	Pangle	Unity Ads	Meta
Step 1	Set up AppLovin configuration	Set up Pangle configuration	Set up Unity Ads configuration	Set up Meta configuration
Step 2	Add AppLovin ad source to AdMob	Add Pangle ad source to AdMob	Add Unity Ads ad source to AdMob	Add Meta ad source to AdMob
Step 3	Add Adiz adapter

Add Adiz Adapter

Add the library dependency to your app-level build.gradle.

 

When integrating with Pangle, add the following settings. If you are using Gradle 7.0 or above, add the repository settings in the dependencyResolutionManagement section of your project-level settings.gradle.

 

If you are using Gradle version less than 7.0, add the repository settings in the allprojects section of your project-level build.gradle.

 

To verify if the Adiz adapter configuration has been properly applied, run your app and check the configuration list on the Ad Inspector screen.

Initializing Hive Adiz

The initialization of Hive Adiz is the essential step before exposing any type of advertisement. When you initialize Hive Adiz, you can receive the necessary ad keys to display ads. If test mode is enabled, you will receive a test key. If you are using the Hive SDK, proceed with Adiz initialization after calling AuthV4.setup.

 

When initializing, the JSON file received as a callback includes a list of ad keys. The format of the ad key list is as follows:

 

If you initialize in test mode, you will receive a list of test ad keys even if you have not registered an AdMob ad key in the Hive console. If you initialize in commercial mode, you will receive a list of AdMob ad keys registered in the Hive console.

Each ad format has one ad as the default ad (an ad with "is_default":true). The first ad registered becomes the default ad for that ad format. You do not need to enter the ad key (hiveAdKey) when creating the ad instance (initialize()) for the default ad. To change the default ad, you must delete the existing default ad in the Hive console and re-register the ad.

Setting Up Ad Callback Listeners

You can receive callbacks based on the state changes of an ad by implementing the AdizListener when creating each ad instance.

Name	Description	Required
onLoad()	Ad load successful	O
onFail(error: AdizError)	Failure (you can understand the reason for failure through error.getCode() and error.getMessage())	O
onShow()	Ad display successful	O
onClick()	Ad clicked	O
onPaidEvent(adRevenueData: AdRevenueData)	This is a point at which a paid event is received after the ad is displayed. At this point, the ad revenue information is delivered.	O
onClose()	Ad closed After the ad is closed, to display the same ad instance again, you need to call load() and then call show(). If you no longer wish to display the ad, call destroy() to remove the ad instance.	X
onRewarded(rewardItem: RewardItem)	The point at which the user receives a reward after an ad display for rewarded (rewarded, rewarded interstitial) ads	X

Error Codes

The error codes and error messages for Adiz.Initialize and AdizListener when onFail() is received are as follows:

Common Codes

Number	Case	Explanation
0	Success	Successful

Adiz Error Codes

Number	Case	Explanation
-1	InvalidParam	Invalid parameter
-2	NotSupported	Not supported
-3	InProgress	Process in progress
-4	Network	Network error
-5	NeedInitialize	Initialization needed
-6	ResponseFail	Response failed
-7	Timeout	Network timeout
-99	Unknown	Unknown error

Ad Platform Error Codes

Number	Case	Explanation
-101	NeedLoad	Ad not loaded
-102	NeedReload	Need to reload due to ad display time expiration
-103	NotEnoughInventory	Mediation response was successful, but no filled ads due to insufficient inventory
-104	MissingAppId	AppID error for mediation request
-105	InternalNetworkError	Mediation network-related error
-106	InvalidUnitId	Invalid Unit Id
-107	MediationNoFill	Mediation adapter failed to handle ad request
-108	AlreadyLoaded	Already loaded
-109	CannotRequestAds	Cannot request ads
-201	GdprConsentError	GDPR consent error
-202	IsNotPrivacyOptionsRequired	No need to display or unable to display the GDPR consent popup

Ad Exposure and Termination

To expose and terminate ads, follow these steps:

1. Create ad instances from the ad class for each type of ad you want to expose. If the ad you want to expose is not a default ad, you need to enter the ad key obtained from initialization. If you do not enter the ad key (hiveAdKey), a default ad instance is created.
2. Load (load()) the ad you want to expose.
3. Expose (show()) the loaded ad. To re-expose the ad, you must call load() again followed by show().
4. To terminate the ad, call destroy().

Interstitial Ads

These are full-screen ads that take up the entire screen.

Banner Ads (Banner)

Banner ads expose a banner of a specific size. Banner ads do not receive the onClose() callback. Therefore, you must call destroy() from another location to terminate the ad.

 

BannerSize follows standard banner sizes.

Size Point (Width x Height)	Description	Supported Devices	BannerSize Constant
320×50	Banner	Mobile phones and tablets	BannerSize.NORMAL
320×100	Large Banner	Mobile phones and tablets	BannerSize.MEDIUM
300×250	IAB Medium Rectangle	Mobile phones and tablets	BannerSize.LARGE
468×60	IAB Full-Size Banner	Tablets	BannerSize.FULL

 

PositionType is either top or bottom. The default is bottom.

Alignment	Description	PositionType Constant
Top Alignment	Specifies alignment at the top of the screen	PositionType.TOP
Bottom Alignment (Default)	Specifies alignment at the bottom of the screen	PositionType.BOTTOM

Native Ads (Native)

Native ads display a specific size of the native template. Native ads are optimized for portrait screens, so it is recommended to use them in portrait games (vertical screen games). Native ads do not receive the onClose() callback. Therefore, you must call destroy() from another location to terminate the ad.

 

Currently, the templates support small or medium sizes.

Template	Alignment	BannerSize Constant
small size	Top / Bottom	BannerSize.NORMAL
medium size	Center (fixed)	BannerSize.MEDIUM

 

For the small template, PositionType is either top or bottom, with the default being bottom.

Alignment	Description	PositionType Constant
Top Alignment	Specifies alignment at the top of the screen	PositionType.TOP
Bottom Alignment (default)	Specifies alignment at the bottom of the screen	PositionType.BOTTOM

 

The medium template does not allow for selection of alignment and defaults to center alignment.

 

Rewarded Ads (Rewarded)

These are rewarded ads where users receive rewards for watching the ad for a certain amount of time. When the reward is successfully provided, reward item information is received through the onRewarded() callback.

Rewarded Interstitial Ads (Rewarded Interstitial)

Rewarded interstitial ads allow users to receive rewards after watching ads for a certain period. Once the reward is granted, the reward item information is received through the onRewarded() callback.

Here’s the translated content:

App Opening Ads (AppOpen)

App opening ads display pre-loaded (load()) ads when the app status changes from background to foreground. If show() is called 3 hours after the ad is loaded, the ad will be automatically reloaded before being displayed. Once the ad is displayed at least once, it will not be automatically reloaded.