Unity

功能描述

Bees Ads SDK 开发包（简称：SDK）主要⽤来向第三⽅应⽤程序提供广告竞价服务。本⽂主要描述 SDK 集成至 Unity 平台的⽅法，供合作伙伴的开发者接⼊使⽤。

接入前准备

接⼊前期准备⼯作包括在 Bees 后台创建应用，已完成商户可略过。 需要获取的参数包括：

参数名称	参数说明
app_id	Bees 后台创建的应用 id
application_id	Google Admob 或 Google Ad Manager 后台的应用 id

这些参数请通过不同平台获取

• app_id 通过 Bees Ads 后台获取

• application_id 通过 Google 后台获取，具体方式详见：文档地址

SDK 快速接入

基础环境

本文档适⽤于 Unity 开发⼯具，如果您没有以上开发⼯具，可以到官⽹下载

SDK 导入

1. 完成 SDK 下载
2. 接入 SDK

打开 Unity 项目中，依次转到 Assets > Import Package > Custom Package ，选择下载好的 ads.xxx.unitypackage 文件，在 Import Unity Package 窗口中，点击 Import，完成 Unity SDK 导入。说明： SDK 中包含了 Demo 脚本，建议接入开发者阅读该文件代码，从而全面了解我方 SDK 调用。

SDK 配置

在 Unity 开发工具的 Project Settings > Player > Publishing Settings > Build 中完成 SDK 以下配置：

1. 勾选 Custom Launcher Manifest 项，在 Assets > Plugins > Android 下生成的 LauncherManifest.xml文件中增加以下配置，并完成 Google Ads 参数配置

    <!-- Google Ads 配置 -->
    <!-- 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" />

最终文件内容如下图：

1. 勾选 Custom Launcher Gradle Template 项，在 Assets > Plugins > Android 下生成的 gradleTemplate.properties 文件中增加以下配置：

dependencies {
    implementation project(':unityLibrary')
    // 增加 Android sdk 依赖
    implementation "io.github.beesads:unity:1.0.1"
    // 增加 Google sdk 依赖
    implementation "com.google.android.gms:play-services-ads:23.1.0"
}

最终文件内容如下图：

1. 勾选 Custom Gradle Properties Template 项，在 Assets > Plugins > Android 下生成的 launcherTemplate.gradle 文件中增加以下配置：

android.useAndroidX=true

最终文件内容如下图：

SDK 初始化

初始化接⼝调⽤⽅式有如下两种，初始化可以使用 快速初始化 动态初始化 其中的一种进行接入。

务必在初始化接⼝回调后再调⽤其它接⼝调用如下初始化接口：

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

参数说明如下:

参数名称	参数说明
appId	BeesAds 后台应用 id
sdkInitializationCallback	该方法在 SDK 初始化完成后被调用。回调方法有两个参数：isSuccess：类型为 bool，表示 SDK 是否成功初始化。true 表示成功，false 表示失败。message：类型为 string，包含初始化过程中的相关信息或错误信息。

代码示例：

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

SDK 接口介绍

横幅广告

1. 请求广告

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

参数：

参数名称	参数含义
adUnitId	广告 id
adPosition	广告位置：Top: 页面顶部区域Bottom: 页面底部区域TopLeft: 页面左上区域TopRight: 页面右上区域BottomLeft: 页面左下区域BottomRight: 页面右下区域Center: 页面中心区域
adLoadCallback	该方法在广告加载完成后被调用。回调方法有两个参数：ad：类型为 BannerAd，表示广告加载成功。error：类型为 string，包含加载广告失败的错误信息。

1. 检查广告是否可用

bool isReady = BannerAd.IsAdReady();

1. 展示广告

// 调用展示前先判断是否有广告
bool isReady = BannerAd.IsAdReady();
if(isReady)
{
    // 展示广告
    BannerAd.ShowAd();
}

// 隐藏广告
BannerAd.HideAd();

1. 监听回调

参数名称	参数含义
OnAdImpression	广告展示成功
OnAdClicked	广告被点击
OnAdClosed	广告被关闭时触发
OnAdOpened	广告被用户打开时触发

1. 销毁

// 隐藏广告
BannerAd.DestroyAd();

代码示例：

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."); 
    };
    
});

原生广告

1. 请求广告

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

参数：

参数名称	参数含义
context	上下⽂
adUnitId	广告 id
adLoadCallback	该方法在广告加载完成后被调用。回调方法有两个参数：ad：类型为 NativeAd，表示广告加载成功。error：类型为 string，包含加载广告失败的错误信息。

1. 检查广告是否可用

bool isReady = NativeAd.IsAdReady();

1. 渲染广告

void Render (NativeTemplateStyle nativeTemplateStyle, AdPosition adPosition);

参数：

参数名称	参数含义
nativeTemplateStyle	模版样式
adPosition	广告位置：Top: 页面顶部区域Bottom: 页面底部区域TopLeft: 页面左上区域TopRight: 页面右上区域BottomLeft: 页面左下区域BottomRight: 页面右下区域Center: 页面中心区域

1. 展示广告

// 调用展示前先判断是否有广告
bool isReady = NativeAd.IsAdReady();
if(isReady)
{
    // 渲染广告
    NativeAd.Render();
    // 展示广告
    NativeAd.ShowAd();
}

// 隐藏广告
NativeAd.HideAd();

1. 监听回调

参数名称	参数含义
OnAdImpression	广告展示成功
OnAdClicked	广告被点击
OnAdShowed	广告显示
OnAdDismissed	广告消失
OnAdShowFailed	广告显示失败

1. 销毁

// 隐藏广告
NativeAd.DestroyAd();

代码示例：

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."); 
    };
});

开屏广告

1. 请求广告

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

参数：

参数名称	参数含义
context	上下⽂
adUnitId	广告 id
adLoadCallback	该方法在广告加载完成后被调用。回调方法有两个参数：ad：类型为 SplashAd，表示广告加载成功。error：类型为 string，包含加载广告失败的错误信息。

1. 检查广告是否可用

bool isReady = SplashAd.IsAdReady();

1. 展示广告

// 调用展示前先判断是否有广告
bool isReady = SplashAd.IsAdReady();
if(isReady)
{
    // 展示广告
    SplashAd.ShowAd();
}

1. 监听回调

参数名称	参数含义
OnAdImpression	广告展示成功
OnAdClicked	广告被点击
OnAdShowed	广告显示
OnAdDismissed	广告消失
OnAdShowFailed	广告显示失败

1. 销毁

// 隐藏广告
SplashAd.DestroyAd();

代码示例：

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); 
    };
});

插屏广告

1. 请求广告

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

参数：

参数名称	参数含义
context	上下⽂
adUnitId	广告 id
adLoadCallback	该方法在广告加载完成后被调用。回调方法有两个参数：ad：类型为 InterstitialAd，表示广告加载成功。error：类型为 string，包含加载广告失败的错误信息。

1. 检查广告是否可用

bool isReady = InterstitialAd.IsAdReady();

1. 展示广告

// 调用展示前先判断是否有广告
bool isReady = InterstitialAd.IsAdReady();
if(isReady)
{
    // 展示广告
    InterstitialAd.ShowAd();
}

1. 监听回调

参数名称	参数含义
OnAdImpression	广告展示成功
OnAdClicked	广告被点击
OnAdShowed	广告显示
OnAdDismissed	广告消失
OnAdShowFailed	广告显示失败

1. 销毁

// 隐藏广告
InterstitialAd.DestroyAd();

代码示例：

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); 
    };
});

激励广告

1. 请求广告

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

参数：

参数名称	参数含义
context	上下⽂
adUnitId	广告 id
adLoadCallback	该方法在广告加载完成后被调用。回调方法有两个参数：ad：类型为 RewaredAd，表示广告加载成功。error：类型为 string，包含加载广告失败的错误信息。

1. 检查广告是否可用

bool isReady = RewaredAd.IsAdReady();

1. 展示广告

// 调用展示前先判断是否有广告
bool isReady = RewaredAd.IsAdReady();
if(isReady)
{
    // 展示广告，并监听奖励回调
    RewaredAd.ShowAd(Action<RewardItem> userRewardEarnedCallback);
}

参数：

参数名称	参数含义
userRewardEarnedCallback	该方法在广告播放完成后奖励发放时被调用。回调方法有一个参数：rewared：类型为 RewardItem，表示广告奖励发放成功

1. 监听回调

参数名称	参数含义
OnAdImpression	广告展示成功
OnAdClicked	广告被点击
OnAdShowed	广告显示
OnAdDismissed	广告消失
OnAdShowFailed	广告显示失败

1. 销毁

// 隐藏广告
RewaredAd.DestroyAd();

代码示例：

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); 
    };
});

插页式激励广告

1. 请求广告

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

参数：

参数名称	参数含义
context	上下⽂
adUnitId	广告 id
adLoadCallback	该方法在广告加载完成后被调用。回调方法有两个参数：ad：类型为 RewaredInterstitialAd，表示广告加载成功。error：类型为 string，包含加载广告失败的错误信息。

1. 检查广告是否可用

bool isReady = RewaredInterstitialAd.IsAdReady();

1. 展示广告

// 调用展示前先判断是否有广告
bool isReady = RewaredInterstitialAd.IsAdReady();
if(isReady)
{
    // 展示广告，并监听奖励回调
    RewaredInterstitialAd.ShowAd(Action<RewardItem> userRewardEarnedCallback);
}

参数：

参数名称	参数含义
userRewardEarnedCallback	该方法在广告播放完成后奖励发放时被调用。回调方法有一个参数：rewared：类型为 RewardItem，表示广告奖励发放成功

1. 监听回调

参数名称	参数含义
OnAdImpression	广告展示成功
OnAdClicked	广告被点击
OnAdShowed	广告显示
OnAdDismissed	广告消失
OnAdShowFailed	广告显示失败

1. 销毁

// 隐藏广告
RewaredInterstitialAd.DestroyAd();

代码示例：

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); 
    };
});

隐私合规

1. GDPR

《通用数据保护条例》（General Data Protection Regulation，GDPR）是针对欧盟（EU）和欧洲经济区（EEA）所有公民的数据保护和隐私法的法规。

void SetUserConsent (bool userConsent);

参数：

参数名称	参数含义
userConsent	true: 用户同意 false: 用户不同意

1. CCPA

加州消费者隐私法案 (CCPA) 是美国第一项全面隐私法。 它于 2018 年 6 月末签署成为法律，向加州消费者提供各种各样的隐私权利。 受到 CCPA 管制的企业将对这些消费者履行多项义务，包括信息披露、与欧盟一般数据保护条例 (GDPR) 类似的消费者权利、“选择退出”特定数据传输的权利，以及“选择加入”未成年人要求的权利。

void SetDoNotSell (bool doNotSell);

参数：

参数名称	参数含义
doNotSell	true: 不上报数据 false: 上报数据

1. COPPA、GDPR Child

美国儿童在线隐私权保护法（Children’s Online Privacy Protection Act，）主要针对在线收集 13 岁以下儿童个人信息的行为。

void SetIsAgeRestrictedUser (bool isAgeRestrictedUser);

参数：

参数名称	参数含义
isAgeRestrictedUser	true: 是年龄受限用户 false: 不是年龄受限用户

1. 谷歌广告内容分级

void SetMaxAdContentRating (MaxAdContentRating maxContentRating);

参数：

参数名称	参数含义
maxContentRating	所有受众: MaxAdContentRating.G青少年: MaxAdContentRating.T成人: MaxAdContentRating.MA需要由父母陪同观看: MaxAdContentRating.PG

更新日志

v1.0.0（2024.06.11）

1. 完成广告加载 API

2. 完成隐私 API

v1.0.1（2024.06.25）

1. 优化已知问题

接入流程 FAQ

若在使用 SDK 过程中遇到问题，可参考以下内容尝试解决。

1. 如何申请 app Id 等平台参数

在我方平台创建应用成功后即可获取

1. 进⾏打包时 targetSDKVersion 应该为多少？

建议使用 33 及以上

1. 如何判断 Bees SDK 初始化状态？

当使用广告请求时，根据 tag: bees-sdk 查看初始化相关日志

• 当初始化成功时，会出现下图所示日志：

• 当初始化失败时，会出现下图所示日志：

技术问题反馈

若本接⼊⽂档不能解决您的疑惑，或有其他技术问题咨询，请发送邮件⾄：[e-mail]