Unity

Functional Description

Bees Ads SDK (SDK for short) is mainly used to provide advertising bidding services to third-party applications. This article mainly describes how to integrate the SDK into the Unity platform for partner developers to access and use.

Preparation before access

The preparatory work for access includes creating an application in the Bees backend. Merchants who have completed this step can skip this step. The parameters that need to be obtained include:

Parameter name

Parameter Description

app_id

Application id created by Bees backend

application_id

The app ID of Google Admob or Google Ad Manager backend

Please obtain these parameters through different platforms

  • app_id is obtained through the BeesAds backend

  • application_id is obtained through the Google backend, for details, see: Document address

SDK Quick Access

Basic Environment

This document is applicable to Unity development tools. If you do not have the above development tools, you can download them from the official website.

SDK Import

  1. Complete SDK download

  2. Connect to SDK

Open the Unity project, go to Assets > Import Package > Custom Package, select the downloaded ads.xxx.unitypackage file, and in the Import Unity Package window, click Import to complete the Unity SDK import. Note: The SDK contains a Demo script. It is recommended that developers read the file code to fully understand our SDK calls.

SDK Configuration

In Unity development tools, go to Project Settings > Player > Publishing Settings > Build and complete the following SDK configuration:

  1. Check the Custom Launcher Manifest option, add the following configuration to the LauncherManifest.xml file generated under Assets > Plugins > Android, and complete the Google Ads parameter configuration

    <!-- Google Ads Configuration -->
    <!-- Sample Ad Manager app ID: ca-app-pub-3940256099942544~3347511713 -->
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />

The final file content is as follows:

  1. Check the Custom Launcher Gradle Template option and add the following configuration to the gradleTemplate.properties file generated under Assets > Plugins > Android:

dependencies {
    implementation project(':unityLibrary')
    // Add Android SDK dependency
    implementation "io.github.beesads:unity:1.0.1"
    // Add Google SDK dependency
    implementation "com.google.android.gms:play-services-ads:23.1.0"
}

The final file content is as follows:

  1. Check the Custom Gradle Properties Template option and add the following configuration to the launcherTemplate.gradle file generated under Assets > Plugins > Android:

android.useAndroidX=true

The final file content is as follows:

SDK Initialization

There are two ways to call the initialization interface. You can use either fast initialization or dynamic initialization to access.

Be sure to call other interfaces after the initialization interface callback. Call the following initialization interface:

static void Initialize (string appId, Action<bool, string> sdkInitializationCallback);

The parameters are described as follows:

Parameter name

Parameter Description

appId

BeesAds background application id

sdkInitializationCallback

This method is called after the SDK is initialized. The callback method has two parameters: isSuccess: bool type, indicating whether the SDK is initialized successfully. true indicates success, false indicates failure. message: string type, containing relevant information or error information during the initialization process

Code example:

AdSDK.Initialize(SDK_APP_ID, (bool isSuccess, string message) =>
{
    Debug.Log("sdk initialization status: " + isSuccess + ", message: " + message);
});

SDK interface introduction

  1. Request Ads

void LoadBannerAd (string adUnitId, AdPosition adPosition, Action<BannerAd, string> adLoadCallback)

parameter：

Parameter name

Parameter Description

adUnitId

advertise id

adPosition

Advertisement location: Top: top area of ​​the pageBottom: bottom area of ​​the pageTopLeft: top left area of ​​the pageTopRight: top right area of ​​the pageBottomLeft: bottom left area of ​​the pageBottomRight: bottom right area of ​​the pageCenter: center area of ​​the page

adLoadCallback

This method is called after the ad is loaded. The callback method has two parameters: ad: type is BannerAd, indicating that the ad is loaded successfully. error: type is string, containing the error message of the ad loading failure.

  1. Check if the ad is available

bool isReady = BannerAd.IsAdReady();

  1. Display ads

// Determine whether there is an ad before calling display
bool isReady = BannerAd.IsAdReady();
if(isReady)
{
    //Display ads 
    BannerAd.ShowAd();
}

// Hide ads
BannerAd.HideAd();

  1. Listening callback

Parameter name

Parameter Description

OnAdImpression

Advertisement display success

OnAdClicked

Ad clicked

OnAdClosed

Fired when the ad is closed

OnAdOpened

Triggered when the ad is opened by the user

  1. destroy

// Hide ads
BannerAd.DestroyAd();

Code Sample：

AdSDK.Instance.LoadBannerAd(BannerAdUnitId, AdPosition.Center, (BannerAd ad, string error) =>
{
    if (error != null || ad == null)
    {
      Debug.LogError("Banner ad failed to load an ad with error : " + error);
      return
    }
    Debug.Log("Banner ad loaded.");
        
    if (ad != null && ad.IsAdReady())
    {
        Debug.Log("Banner ad show");
        ad?.ShowAd();
    }

    ad.OnAdClicked += () => 
    { 
        Debug.Log("Banner ad was clicked."); 
    };
    ad.OnAdImpression += () => 
    { 
        Debug.Log("Banner ad recorded an impression."); 
    };
    ad.OnAdClosed += () => 
    { 
        Debug.Log("Banner ad was closed."); 
    };
    ad.OnAdOpened += () => 
    { 
        Debug.Log("Banner ad was opened."); 
    };
    
});

Native Advertising

  1. Request Ads

void LoadNativeAd (string adUnitId, Action<NativeAd, string> adLoadCallback);

parameter：

Parameter name

Parameter Description

context

Context

adUnitId

Advertisement ID

adLoadCallback

This method is called after the ad is loaded. The callback method has two parameters: ad: of type NativeAd, indicating that the ad is loaded successfully. error: of type string, containing the error message of the ad loading failure.

  1. Check if the ad is available

bool isReady = NativeAd.IsAdReady();

  1. Rendering Ads

void Render (NativeTemplateStyle nativeTemplateStyle, AdPosition adPosition);

Parameter：

Parameter name

Parameter Description

nativeTemplateStyle

Template Style

adPosition

Advertisement location: Top: top area of ​​the pageBottom: bottom area of ​​the pageTopLeft: top left area of ​​the pageTopRight: top right area of ​​the pageBottomLeft: bottom left area of ​​the pageBottomRight: bottom right area of ​​the pageCenter: center area of ​​the page

  1. Display ads

// Determine whether there is an ad before calling display
bool isReady = NativeAd.IsAdReady();
if(isReady)
{
    // Rendering Ads
    NativeAd.Render();
    // Display ads
    NativeAd.ShowAd();
}

// Hide ads
NativeAd.HideAd();

  1. Listening callback

Parameter name

Parameter Description

OnAdImpression

Advertisement display success

OnAdClicked

Ad clicked

OnAdShowed

Advertisement display

OnAdDismissed

Ads disappear

OnAdShowFailed

Ad display failed

  1. destroy

// Hide ads
NativeAd.DestroyAd();

Code Sample：

AdSDK.Instance.LoadNativeAd(NativeAdUnitId, (NativeAd ad, string error) =>
{
    if (error != null || ad == null)
    {
      Debug.LogError("Native ad failed to load an ad with error : " + error);
      return
    }
    Debug.Log("Native ad loaded.");
        
    if (ad != null && ad.IsAdReady())
    {
        var style = new NativeTemplateStyle
        {
            TemplateId = NativeTemplateId.Small,
            MainBackgroundColor = Color.red,
            CallToActionText = new NativeTemplateTextStyle
            {
                BackgroundColor = Color.black,
                TextColor = Color.magenta,
                FontSize = 18,
                Style = NativeTemplateFontStyle.Normal,
            },
            PrimaryText = new NativeTemplateTextStyle
            {
                BackgroundColor = Color.blue,
                TextColor = Color.black,
                FontSize = 16,
                Style = NativeTemplateFontStyle.Bold,
            },
            SecondaryText = new NativeTemplateTextStyle
            {
                BackgroundColor = Color.yellow,
                TextColor = Color.red,
                FontSize = 12,
                Style = NativeTemplateFontStyle.Italic,
            },
            TertiaryText = new NativeTemplateTextStyle
            {
                BackgroundColor = Color.gray,
                TextColor = Color.magenta,
                FontSize = 4,
                Style = NativeTemplateFontStyle.Monospace,
            },
        };
        ad.Render(style, AdPosition.Bottom);
        ad.ShowAd();
    }

    ad.OnAdClicked += () => 
    { 
        Debug.Log("Native ad was clicked."); 
    };
    ad.OnAdImpression += () => 
    { 
        Debug.Log("Native ad recorded an impression."); 
    };
    ad.OnAdShowed += () => 
    { 
        Debug.Log("Native ad was showed."); 
    };
    ad.OnAdDismissed += () => 
    { 
        Debug.Log("Native ad was dismissed."); 
    };
});

Splash screen ads

  1. Request Ads

void LoadSplashAd (string adUnitId, Action<SplashAd, string> adLoadCallback);

parameter：

Parameter name

Parameter Description

context

Context

adUnitId

Advertisement ID

adLoadCallback

This method is called after the ad is loaded. The callback method has two parameters: ad: type is SplashAd, indicating that the ad is loaded successfully. error: type is string, containing the error message of the ad loading failure.

  1. Check if the ad is available

bool isReady = SplashAd.IsAdReady();

  1. Display ads

// Determine whether there is an ad before calling display
bool isReady = SplashAd.IsAdReady();
if(isReady)
{
    // Display ads
    SplashAd.ShowAd();
}

  1. Listening callback

Parameter name

Parameter Description

OnAdImpression

Advertisement display success

OnAdClicked

Ad clicked

OnAdShowed

Advertisement display

OnAdDismissed

Ads disappear

OnAdShowFailed

Ad display failed

  1. destroy

// Hide ads
SplashAd.DestroyAd();

Code Sample：

AdSDK.Instance.LoadSplashAd(SplashAdUnitId, (SplashAd ad, string error) =>
{
    if (error != null || ad == null)
    {
      Debug.LogError("Splash ad failed to load an ad with error : " + error);
      return
    }
    Debug.Log("Splash ad loaded.");
        
    if (ad != null && ad.IsAdReady())
    {
        Debug.Log("Splash ad show");
        ad?.ShowAd();
    }

    ad.OnAdClicked += () => 
    { 
        Debug.Log("Splash ad was clicked."); 
    };
    ad.OnAdImpression += () => 
    { 
        Debug.Log("Splash ad recorded an impression."); 
    };
    ad.OnAdShowed += () => 
    { 
        Debug.Log("Splash ad was showed."); 
    };
    ad.OnAdDismissed += () => 
    { 
        Debug.Log("Splash ad was dismissed."); 
    };
    ad.OnAdShowFailed += (string error) => 
    { 
        Debug.LogError("Splash ad failed to show with error: " + error); 
    };
});

Interstitial Ads

  1. Request Ads

void LoadInterstitialAd (string adUnitId, Action<InterstitialAd, string> adLoadCallback);

parameter：

Parameter name

Parameter Description

context

Context

adUnitId

Advertisement ID

adLoadCallback

This method is called after the ad is loaded. The callback method has two parameters: ad: type is InterstitialAd, indicating that the ad is loaded successfully. error: type is string, containing the error message of the ad loading failure.

  1. Check if the ad is available

bool isReady = InterstitialAd.IsAdReady();

  1. Display ads

// Determine whether there is an ad before calling display
bool isReady = InterstitialAd.IsAdReady();
if(isReady)
{
    // Display ads
    InterstitialAd.ShowAd();
}

  1. Listening callback

Parameter name

Parameter Description

OnAdImpression

Advertisement display success

OnAdClicked

Ad clicked

OnAdShowed

Advertisement display

OnAdDismissed

Ads disappear

OnAdShowFailed

Ad display failed

  1. destroy

// Hide ads
InterstitialAd.DestroyAd();

Code Sample：

AdSDK.Instance.LoadInterstitialAd(InterstitialAdUnitId, (InterstitialAd ad, string error) =>
{
    if (error != null || ad == null)
    {
      Debug.LogError("Interstitial ad failed to load an ad with error : " + error);
      return
    }
    Debug.Log("Interstitial ad loaded.");
        
    if (ad != null && ad.IsAdReady())
    {
        Debug.Log("Interstitial ad show");
        ad.ShowAd();
    }

    ad.OnAdClicked += () => 
    { 
        Debug.Log("Interstitial ad was clicked."); 
    };
    ad.OnAdImpression += () => 
    { 
        Debug.Log("Interstitial ad recorded an impression."); 
    };
    ad.OnAdShowed += () => 
    { 
        Debug.Log("Interstitial ad was showed."); 
    };
    ad.OnAdDismissed += () => 
    { 
        Debug.Log("Interstitial ad was dismissed."); 
    };
    ad.OnAdShowFailed += (string error) => 
    { 
        Debug.LogError("Interstitial ad failed to show with error: " + error); 
    };
});

Rewarded ads

  1. Request Ads

void LoadRewaredAd (string adUnitId, Action<RewaredAd, string> adLoadCallback);

parameter：

Parameter name

Parameter Description

context

Context

adUnitId

Advertisement ID

adLoadCallback

This method is called after the ad is loaded. The callback method has two parameters: ad: type is RewaredAd, indicating that the ad is loaded successfully. error: type is string, containing the error message of the ad loading failure.

  1. Check if the ad is available

bool isReady = RewaredAd.IsAdReady();

  1. Display ads

// Determine whether there is an ad before calling display
bool isReady = RewaredAd.IsAdReady();
if(isReady)
{
    // Display ads and listen for reward callbacks
    RewaredAd.ShowAd(Action<RewardItem> userRewardEarnedCallback);
}

parameter：

Parameter name

Parameter Description

userRewardEarnedCallback

This method is called when the reward is issued after the ad is played. The callback method has one parameter: rewared: type is RewardItem, indicating that the ad reward is issued successfully

  1. Listening callback

Parameter name

Parameter Description

OnAdImpression

Advertisement display success

OnAdClicked

Ad clicked

OnAdShowed

Advertisement display

OnAdDismissed

Ads disappear

OnAdShowFailed

Ad display failed

  1. destroy

// Hide ads
RewaredAd.DestroyAd();

Code Sample：

AdSDK.Instance.LoadRewaredAd(RewardedAdUnitId, (RewaredAd ad, string error) =>
{
    if (error != null || ad == null)
    {
      Debug.LogError("Rewarded ad failed to load an ad with error : " + error);
      return
    }
    Debug.Log("Rewarded ad loaded.");
        
    if (ad != null && ad.IsAdReady())
    {
        Debug.Log("Rewarded ad show");
        ad.ShowAd((RewardItem rewared) =>
        {
            Debug.Log("Rewarded onUserEarnedReward, type: " + rewared.Type + ", amount: " + rewared.Amount);
        });
    }

    ad.OnAdClicked += () => 
    { 
        Debug.Log("Rewarded ad was clicked."); 
    };
    ad.OnAdImpression += () => 
    { 
        Debug.Log("Rewarded ad recorded an impression."); 
    };
    ad.OnAdShowed += () => 
    { 
        Debug.Log("Rewarded ad was showed."); 
    };
    ad.OnAdDismissed += () => 
    { 
        Debug.Log("Rewarded ad was dismissed."); 
    };
    ad.OnAdShowFailed += (string error) => 
    { 
        Debug.LogError("Rewarded ad failed to show with error: " + error); 
    };
});

Rewarded interstitial ads

  1. Request Ads

void LoadRewaredInterstitialAd (string adUnitId, Action<RewaredInterstitialAd, string> adLoadCallback);

parameter：

Parameter name

Parameter Description

context

Context

adUnitId

Advertisement ID

adLoadCallback

This method is called after the ad is loaded. The callback method has two parameters: ad: of type RewaredInterstitialAd, indicating that the ad is loaded successfully. error: of type string, containing the error message of the ad loading failure.

  1. Check if the ad is available

bool isReady = RewaredInterstitialAd.IsAdReady();

  1. Display ads

// Determine whether there is an ad before calling display
bool isReady = RewaredInterstitialAd.IsAdReady();
if(isReady)
{
    // Display ads and listen for reward callbacks
    RewaredInterstitialAd.ShowAd(Action<RewardItem> userRewardEarnedCallback);
}

parameter：

Parameter name

Parameter Description

userRewardEarnedCallback

This method is called when the reward is issued after the ad is played. The callback method has one parameter: rewared: type is RewardItem, indicating that the ad reward is issued successfully

  1. Listening callback

Parameter name

Parameter Description

OnAdImpression

Advertisement display success

OnAdClicked

Ad clicked

OnAdShowed

Advertisement display

OnAdDismissed

Ads disappear

OnAdShowFailed

Ad display failed

  1. destroy

// Hide ads
RewaredInterstitialAd.DestroyAd();

Code Sample：

AdSDK.Instance.LoadRewaredInterstitialAd(RewardedInterstitialAdUnitId, (RewaredInterstitialAd ad, string error) =>
{
    if (error != null || ad == null)
    {
      Debug.LogError("RewaredInterstitial ad failed to load an ad with error : " + error);
      return
    }
    Debug.Log("RewaredInterstitial ad loaded.");
    
    if (ad != null && ad.IsAdReady())
    {
        Debug.Log("RewardedInterstitial ad show");
        ad.ShowAd((RewardItem rewared) =>
        {
            Debug.Log("RewardedInterstitial onUserEarnedReward, type: " + rewared.Type + ", amount: " + rewared.Amount);
        });
    }

    ad.OnAdClicked += () => 
    { 
        Debug.Log("RewaredInterstitial ad was clicked."); 
    };
    ad.OnAdImpression += () => 
    { 
        Debug.Log("RewaredInterstitial ad recorded an impression."); 
    };
    ad.OnAdShowed += () => 
    { 
        Debug.Log("RewaredInterstitial ad was showed."); 
    };
    ad.OnAdDismissed += () => 
    { 
        Debug.Log("RewaredInterstitial ad was dismissed."); 
    };
    ad.OnAdShowFailed += (string error) => 
    { 
        Debug.LogError("RewaredInterstitial ad failed to show with error: " + error); 
    };
});

Privacy Compliance

  1. GDPR

The General Data Protection Regulation (GDPR) is a set of data protection and privacy laws for all citizens of the European Union (EU) and the European Economic Area (EEA).

void SetUserConsent (bool userConsent);

parameter：

Parameter name

Parameter Description

userConsent

true: user agrees false: user disagrees

  1. CCPA

The California Consumer Privacy Act (CCPA) is the first comprehensive privacy law in the United States. It was signed into law in late June 2018 and provides a wide range of privacy rights to California consumers. Businesses governed by the CCPA will have a number of obligations to those consumers, including disclosures, consumer rights similar to the EU General Data Protection Regulation (GDPR), the right to “opt-out” of certain data transfers, and the right to “opt-in” for requests from minors.

void SetDoNotSell (bool doNotSell);

parameter：

Parameter name

Parameter Description

doNotSell

true: do not report data false: report data

  1. COPPA、GDPR Child

The U.S. Children’s Online Privacy Protection Act (COPPA) targets the online collection of personal information from children under the age of 13.

void SetIsAgeRestrictedUser (bool isAgeRestrictedUser);

parameter:

Parameter name

Parameter Description

isAgeRestrictedUser

true: is an age-restricted user false: is not an age-restricted user

  1. Google Ads Content Ratings

void SetMaxAdContentRating (MaxAdContentRating maxContentRating);

parameter：

Parameter name

Parameter Description

maxContentRating

All audiences: MaxAdContentRating.G Teens: MaxAdContentRating.T Adults: MaxAdContentRating.MA Parental supervision required: MaxAdContentRating.PG

Changelog

v1.0.0（2024.06.11）

  1. Completed ad loading API

  2. Completed privacy API

v1.0.1（2024.06.25）

  1. Optimize known issues

Access process FAQ

If you encounter problems when using the SDK, you can refer to the following content to try to solve it

  1. How to apply for app ID and other platform parameters You can obtain it after successfully creating an application on our platform

  2. What should the targetSDKVersion be when packaging? 33 and above are recommended

  3. How to determine the initialization status of Bees SDK? When using ad requests, check the initialization related logs according to tag: bees-sdk

  • When initialization is successful, the log shown in the figure below will appear：

  • When initialization fails, the following log will appear:

Technical feedback

If this access document cannot solve your doubts, or you have other technical questions, please send an email to: rick.wei@eclicktech.com.cn

PreviousNon-SDK accessNextGame SDK

Last updated