Guides & References

Get the latest guides and references for the Ad Kit in the HMS Unity Plugin.

The Ads Kit allows you to monetize your app by displaying various types of ads, such as banner, interstitial, rewarded, and native ads.

Prerequisites

Before we begin, ensure you have the following:

• Unity 2018 or later.

• HMS Unity Plugin.

• A registered Huawei AppGallery Connect account.

• Ad IDs from Petal Publisher Service (for real ads, check this documentation).

Petal Ads Publisher Service

Petal Ads Publisher Service is a monetization service that leverages Huawei's extensive data capabilities to display high-quality ad content in your apps to the vast user base of Huawei devices. To integrate the Petal Ads Publisher Service, refer to this document.

Installation and Configuration

1. Download the HMS Unity Plugin from the official GitHub repository and import it into your Unity project.

2. There is a custom editor in Huawei > Kit Settings. You should enable the Ads Kit.

3. Next, go to Huawei > Kit Settings > Ads tab.

First, you can choose which ads to enable or disable according to your preferences. Next, input your Ad ID into the provided text boxes within the Unity Editor. If you're interested in using test ads, simply tick the "UseTestAds" checkbox, which will automatically replace all ad IDs with test ads.

In order to display real ads, the game must be published. Before the game's release, you can use a test ID to test it. Be mindful that if you include a rewarded ad button that fails to load an ad, and the review team clicks on the button without any results, your game may be rejected during the review process.

Once you have completed these steps, you can call specific functions for the ad type you want to display.

Banner Ads

Banner ads are simple, rectangular ads found on websites and apps. They showcase products, services, or brands and encourage users to click on them. By displaying these ads, website and app developers can earn money through user engagement.

These two lines of code shown below are used to control the display of a banner ad within an app using the Huawei Ads Kit. ShowBannerAd(); is responsible for showing the banner ad on the screen, while HideBannerAd(); is used to hide the banner ad from view. By incorporating these commands in your app's script, you can easily manage when and where the banner ad appears to users.

    HMSAdsKitManager.Instance.ShowBannerAd();
    HMSAdsKitManager.Instance.HideBannerAd();
    

Banner Positions

POSITION_CUSTOM

POSITION_TOP

POSITION_BOTTOM

POSITION_TOP_LEFT

POSITION_TOP_RIGHT

POSITION_BOTTOM_LEFT

POSITION_BOTTOM_RIGHT

POSITION_CENTER

Standard Banner Ad Dimensions

The following table lists the standard banner ad dimensions.

Type	Dimensions in dp (W x H)
BANNER_SIZE_320_50	320 x 50
BANNER_SIZE_320_100	320 x 100
BANNER_SIZE_300_250	300 x 250
BANNER_SIZE_360_57	360 x 57
BANNER_SIZE_360_144	360 x 144
BANNER_SIZE_468_60	468 x 60
BANNER_SIZE_728_90	728 x 90
BANNER_SIZE_SMART	Screen width x 32|50|90
CustomBannerSize(int widht, int height)	Please refer to Custom size BannerAds.

NOTE:

• Only BANNER_SIZE_360_57 and BANNER_SIZE_360_144 are supported in the Chinese mainland.

• You are advised to use BANNER_SIZE_320_50 and BANNER_SIZE_300_250 in areas outside the Chinese mainland.

• CustomBannerSize is not advised to use.

Custom Banner Ad Dimension

Custom Banner Ad Dimensions allow you to create banner ads in specific sizes that suit your app's layout and design. Instead of using predefined sizes, you can define your own width and height for the banner ad. For beginners, the provided code helps you load a custom-sized banner ad using the Huawei Ads Kit:

HMSAdsKitManager.Instance.LoadBannerAd(
HuaweiConstants.UnityBannerAdPositionCode.UnityBannerAdPositionCodeType.POSITION_BOTTOM, 
HuaweiConstants.UnityBannerAdSize.CustomBannerSize(100, 30));

This code loads a custom-sized banner ad with a width of 100 and a height of 30. The ad is positioned at the bottom of the screen. By using this code, you can easily create and display banner ads that fit your app's unique design and requirements.

Interstitial Ads

Interstitial ads are full-screen advertisements that appear during natural breaks or transitions within an app or game. They cover the entire screen, capturing the user's attention. Users can typically close these ads after a few seconds by tapping on an "X" or "Close" button.

To display an interstitial ad in your app using the Huawei Ads Kit, you can use the code;

HMSAdsKitManager.Instance.ShowInterstitialAd();

This command will show the interstitial ad when you want it to appear during your app's experience.

Rewarded Ads

Rewarded ads are a type of advertisement that offers users in-app rewards, such as virtual currency, extra lives, or premium content, in exchange for watching a short video or engaging with the ad. They are popular in games and apps, as they provide benefits to both users and developers. The code provided below helps you implement rewarded ads using Huawei Ads Kit:

HMSAdsKitManager.Instance.OnRewarded = OnRewarded;
HMSAdsKitManager.Instance.ShowRewardedAd();

This code sets up a callback function OnRewarded that will be executed when the user receives a reward after watching the ad. It also displays the rewarded ad when needed. The OnRewarded function, defined as follows, contains the logic to handle the reward:

public void OnRewarded(Reward reward){
    // Add code here to grant the user their reward.
}

In this function, you can add the code that grants the user their reward after successfully engaging with the rewarded ad.

Splash Ads

Splash ads are full-screen advertisements that appear when an app is launched, typically displaying for a few seconds before transitioning to the app's main content. They are designed to capture the user's attention right away.

The code below helps you implement splash ads using the Huawei Ads Kit:

HMSAdsKitManager.Instance.OnSplashAdClicked += OnSplashAdClicked;

private void OnSplashAdClicked()
{
     // Add code here to handle the ad click event.
}

This code sets up a callback function OnSplashAdClicked that will be executed when the user clicks on the splash ad. For more details about Splash Ad and its configuration, please check this article written by @sametguzeldev here.

Devices Without HMS Core Installed

Even if the device is a non-Huawei device, you do not need to make any changes if Hms Core is installed. But if you are going to present your game to devices that do not have Hms Core installed. You need to modify Assets/Huawei/Editor/Utils/HMSGradleWorker.

com.huawei.hms:ads-lite:13.4.58.304 => com.huawei.hms:ads-prime:3.4.58.304

If we have a different version than 13.4.58.304 please refer to version changes and use the prime version which is related to our version.

Consent

Consent, in the context of app development and advertising, refers to the process of obtaining a user's permission to collect, store, or use their personal data for targeted advertising or other purposes. It's important to obtain consent to comply with data protection regulations like GDPR (General Data Protection Regulation) and to respect user privacy.

For Using the Consent SDK, please refer to Consent.

To use consent in your project you can refer to our Demo Scene.

Native Ads

Native ads are a type of advertisement that seamlessly blend in with the content and design of the app or website where they appear. Instead of standing out like traditional banner ads or interstitial ads, native ads are designed to match the look and feel of the surrounding content, making them less intrusive and more engaging for users.

To use Native Ads please refer to:

pageNative Ads