Hive Adiz iOS

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

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

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

Installation

Add the GADApplicationIdentifier key to the Xcode project’s Info.plist file, and add the AdMobId value (the format in ca-app-pub-XXXXX~YYYYY) as the value for this key.

  

Additionally, on iOS 14 and above, refer to the Update your info.plist guide to add the SKAdNetwork list to your Info.plist file. 

 

After that, add the followings to the CocoaPods configuration (Podfile) of your project.

 

Run $pod install to apply CocoaPod settings.

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

Swift

Objective-C

Setting Hive Adiz AppID

Set the Hive Adiz AppID you registered in the Hive console AppCenter. If this is not configured, it will use the Bundle ID.

Swift

Objective-C

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: AdizZoneType.test
  • Hive sandbox console server: AdizZoneType.sandbox
  • Hive commercial console server: AdizZoneType.real
Swift

Objective-C

Exposing User-Specific Ads

With the introduction of ATT (App Tracking Transparency) in iOS 14.5+, privacy protection has been strengthened. As a result, user-specific ads can only be exposed if the user consents to activity tracking in the ATT consent popup. To maximize ad revenue by exposing user-specific ads, it is necessary to create an IDFA (Identifier for Advertisers) message.
Create and publish your IDFA message following the guide on the AdMob dashboard.

Once the IDFA message is published on the AdMob dashboard, it will automatically be displayed during the initialization of Hive Adiz in iOS 14.5+. Clicking “Continue” in the IDFA message window will display the ATT consent popup.

If the user clicks “Allow” in the ATT consent popup, IDFA is activated, and user-specific ads will be displayed.

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. To display the GDPR popup, you must create a GDPR message in the AdMob console and then initialize Hive Adiz. If you do not plan to serve your app in Europe or the UK, you may skip this step and proceed to initializing 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.
  3. Swift

    Objective-C

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:

  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:

    To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[B74F6468-1516-467C-99AD-CC5973C5DB52]

    Get the device ID (example: B74F6468-1516-467C-99AD-CC5973C5DB52).

  3. Copy the device ID.
  4. Add AdizGDPRManager.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.
Swift

Objective-C

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.

Swift

Objective-C

 

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(_ revenueData: 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
Swift

Objective-C

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 Success

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

Interstitial ads are full-screen ads that cover the interface of game.

Swift

Objective-C

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, based on the SafeArea PositionType.top
Bottom Alignment (Default) Specifies alignment at the bottom of the screen, based on the SafeArea PositionType.bottom
Swift

Objective-C

Native Ads

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.

Size Point (Width x Height) Template Alignment BannerSize Constant
355×91 (Aspect Ratio Adjusted) small size Top / Bottom BannerSize.normal
355×370 (Aspect Ratio Adjusted) medium size Center (fixed) BannerSize.medium,
BannerSize.large,
BannerSize.full

 

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 alignment selection and uses center alignment by default.

 

Swift

Objective-C

Rewarded Ads (Rewarded)

These are rewarded ads where users receive rewards for watching the ad for a certain amount of time. Once the reward is issued, you will receive the information about the reward item through the onRewarded() callback.

Swift

Objective-C

Rewarded Interstitial Ads (Rewarded Interstitial)

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

Swift

Objective-C

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 an ad is displayed at least once, it will not automatically be loaded afterwards.

Swift

Objective-C