U8SDK—聚合SDK文档

Appearance

UE(虚幻引擎)接入 ​

IMPORTANT

在接入SDK之前， 建议先请仔细阅读：接入流程。
U8提供了一个UE插件，屏蔽了不同平台的差异，对UE提供了一套统一的API和回调接口（支持蓝图或C++调用）。 但本文档仅供参考，游戏层也可以自行实现Android/iOS原生接口的调用逻辑。
U8提供的Demo（UE5.6.1版本）中，是通过蓝图方式调用的， C++调用方式请参考本文档。

基础配置 ​

1、将U8SDKDemo5/Plugins/U8PlatformBridge目录拷贝到游戏工程的Plugins目录下， 如果游戏层不存在Plugins目录，可以创建一个Plugins目录。

2、如果在蓝图中调用， 直接在蓝图中搜U8SDK关键字，所有API都在U8SDK类目下。

3、C++中调用时，请添加头文件引用：

c++
#include "U8PlatformBridgeBPLibrary.h"
#include "U8PlatformBridgeSubsystem.h"

初始化 ​

游戏层应尽快调用初始化接口， 后续所有的接口，都需要在初始化接口调用之后调用。

WARNING

Android平台的SDK初始化在引擎Activity的onCreate中调用的，实际调用的时机，要早于引擎层的InitSDK接口。但是游戏层只有调用InitSDK后，才会收到初始化回调结果。

c++
UU8PlatformBridgeBPLibrary::InitSDK();

初始化成功或失败， 插件会通过广播的形式触发结果通知：UU8PlatformBridgeSubsystem::OnInitSuc或UU8PlatformBridgeSubsystem::OnInitFailed:

c++

// 在你的接入类头文件中，定义处理成功/失败事件的句柄
void Handle_InitSuc();
void Handle_InitFailed(const FString& Error);


// 在你的接入实现类中

// 获取子系统实例
UU8PlatformBridgeSubsystem* Subsys = GetSubsystem<UU8PlatformBridgeSubsystem>();

// 添加监听事件
Subsys->OnInitSuc.AddDynamic(this, &UYourGameInstance::Handle_InitSuc);
Subsys->OnInitFailed.AddDynamic(this, &UYourGameInstance::Handle_InitFailed);


// 移除监听事件
Subsys->OnInitSuc.RemoveDynamic(this, &UYourGameInstance::Handle_InitSuc);
Subsys->OnInitFailed.RemoveDynamic(this, &UYourGameInstance::Handle_InitFailed);

登录 ​

在玩家进入游戏之前， 需要调用登录接口，弹出渠道SDK的登录界面：

c++
UU8PlatformBridgeBPLibrary::Login();

当玩家登录成功或失败后， 插件会通过广播的形式触发结果通知：UU8PlatformBridgeSubsystem::OnLoginSuc或UU8PlatformBridgeSubsystem::OnLoginFailed:

c++
// 在你的接入类头文件中，定义处理成功/失败事件的句柄
void Handle_LoginSuc(const FU8LoginResult& Result);
void Handle_LoginFailed(const FString& Error);


// 在你的接入实现类中

// 获取子系统实例
UU8PlatformBridgeSubsystem* Subsys = GetSubsystem<UU8PlatformBridgeSubsystem>();

// 添加监听事件
Subsys->OnLoginSuc.AddDynamic(this, &UYourGameInstance::Handle_LoginSuc);
Subsys->OnLoginFailed.AddDynamic(this, &UYourGameInstance::Handle_LoginFailed);


// 移除监事件
Subsys->OnLoginSuc.RemoveDynamic(this, &UYourGameInstance::Handle_LoginSuc);
Subsys->OnLoginFailed.RemoveDynamic(this, &UYourGameInstance::Handle_LoginFailed);

登出 ​

如果游戏内有登出按钮， 当玩家点击登出按钮的时候， 主动调用登出接口后（该接口没有回调），立即返回到游戏登录界面（不用等待回调结果）

c++
UU8PlatformBridgeBPLibrary::Logout();

注意， 还有另外一种登出： 玩家从渠道SDK的悬浮窗->用户中心中点击登出/切换账号，此时U8SDK会通过UU8PlatformBridgeSubsystem::OnLogout回调通知游戏。 游戏层收到该回调后，需要引导玩家返回到游戏登录界面。（重要，影响渠道审核）

c++
// 在你的接入类头文件中，定义处理成功/失败事件的句柄
void Handle_Logout();


// 在你的接入实现类中

// 获取子系统实例
UU8PlatformBridgeSubsystem* Subsys = GetSubsystem<UU8PlatformBridgeSubsystem>();

// 添加监听事件
Subsys->OnLogout.AddDynamic(this, &UYourGameInstance::Handle_Logout);


// 移除监事件
Subsys->OnLogout.RemoveDynamic(this, &UYourGameInstance::Handle_Logout);

角色数据上报 ​

在玩家创建角色、进入游戏、等级升级以及退出游戏时，需要上报角色信息。 （重要，影响渠道审核）

c++
FU8RoleData RoleData;
RoleData.Type = 3;                  // 时机类型（2创建、3进入、4升级、5退出）
RoleData.RoleID = RoleID;           // 玩家角色ID
RoleData.RoleName = RoleName;       // 玩家角色名称
RoleData.RoleLevel = RoleLevel;     // 玩家角色等级
RoleData.Vip = Vip;                 // 玩家VIP等级
RoleData.MoneyNum = MoneyNum;       // 当前角色拥有的游戏币数量
RoleData.ServerID = ServerID;       // 玩家所在服务器ID
RoleData.ServerName = ServerName;   // 玩家所在服务器名称

// 可按需设置时间（字符串），比如服务端返回的时间戳， 单位秒
RoleData.CreateTime = TEXT("1710000000");           //角色创建成功事件
RoleData.LastLevelUpTime = TEXT("1710000500");      //角色最后升级时间

UU8PlatformBridgeBPLibrary::SubmitGameData(RoleData);

支付 ​

在游戏中购买道具/游戏币时，调用支付接口。

c++
FU8PayParams PayParams;
// 商品信息
PayParams.ProductID   = TEXT("diamond_60");             //商品ID,不可为空
PayParams.ProductName = TEXT("60钻石");                 //商品名称，不可为空
PayParams.ProductDesc = TEXT("用于商城消费的虚拟货币");   //商品描述，不可为空

// 价格信息（单位：CNY）
PayParams.Price    = 6;              // 支付金额，单位元

// 玩家信息
PayParams.RoleID    = TEXT("10086");        //角色ID，不可为空
PayParams.RoleName  = TEXT("骑士A");        //角色名称，不可为空
PayParams.RoleLevel = 15;                   //角色等级
PayParams.Vip       = 1;                    //VIP等级
PayParams.MoneyNum  = 12345;                // 当前角色身上游戏币余额（非人民币）

// 服务器信息
PayParams.ServerID   = TEXT("S1");          //服务器ID，不可为空
PayParams.ServerName = TEXT("电光一服");     //服务器名称，不可为空

// 订单信息
PayParams.CPOrderID   = TEXT("CP_20250101_000001");         //游戏订单号， 最大长度64位。 服务端支付回调通知时，原样返回
PayParams.PayNotifyUrl = TEXT("https://your.server.com/pay/notify");    //游戏服务器接收支付回调通知的URL地址，也可以不设置， 在SDK后台配置

// 扩展字段
PayParams.Extra = TEXT("any custom attach string");         //自定义数据，最大长度64位。 服务端支付回调通知时，原因返回

// 发起支付
UU8PlatformBridgeBPLibrary::Pay(PayParams);

支付成功或失败后，插件会通过广播的形式触发结果通知：UU8PlatformBridgeSubsystem::OnPaySuc或UU8PlatformBridgeSubsystem::OnPayFailed:

c++
// 在你的接入类头文件中，定义处理成功/失败事件的句柄
void Handle_PaySuc();
void Handle_PayFailed(const FString& Error);


// 在你的接入实现类中

// 获取子系统实例
UU8PlatformBridgeSubsystem* Subsys = GetSubsystem<UU8PlatformBridgeSubsystem>();

// 添加监听事件
Subsys->OnPaySuc.AddDynamic(this, &UYourGameInstance::Handle_PaySuc);
Subsys->OnPayFailed.AddDynamic(this, &UYourGameInstance::Handle_PayFailed);


// 移除监听事件
Subsys->OnPaySuc.RemoveDynamic(this, &UYourGameInstance::Handle_PaySuc);
Subsys->OnPayFailed.RemoveDynamic(this, &UYourGameInstance::Handle_PayFailed);

退出游戏 ​

游戏应在退出游戏时，调用此接口， 部分渠道会弹出退出确认框。 注意：没有这个部分渠道会审核失败。

c++
if (UU8PlatformBridgeBPLibrary::IsSupportExit())
{
    UU8PlatformBridgeBPLibrary::Exit();
}
else
{
    // 部分渠道不支持 SDK 弹框退出，则可自行调用控制台命令退出
}

广告接口（可选） ​

IMPORTANT

如果游戏是IAA游戏或需要通过广告变现， 可以接入U8聚合广告接口。 之后通过U8打包工具，将具体的广告SDK打入进去即可，无需单独接入各个广告平台的SDK。

在接入SDK之前， 需要先获取广告参数，建议先请仔细阅读：获取广告参数。

目前支持的广告类型有： 开屏广告/自动开屏、 插屏广告、 横幅广告（Banner）、激励视频广告。

设置广告监听

在广告事件发生时， 插件会通过广播的形式触发结果通知：UU8PlatformBridgeSubsystem::OnAdEvent:

c++
// 在你的接入类头文件中，定义事件的句柄
void Handle_AdEvent(const FU8AdEvent& EventData);


// 在你的接入实现类中

// 获取子系统实例
UU8PlatformBridgeSubsystem* Subsys = GetSubsystem<UU8PlatformBridgeSubsystem>();

// 添加监听事件
Subsys->OnAdEvent.AddDynamic(this, &UYourGameInstance::Handle_AdEvent);


// 移除监事件
Subsys->OnAdEvent.RemoveDynamic(this, &UYourGameInstance::Handle_AdEvent);
1、 激励视频广告
  1. 加载广告
c++
UU8PlatformBridgeBPLibrary::LoadRewardVideoAd(AdId, RewardName, RewardNum);

参数说明：

参数名称参数类型参数说明
AdIdstringU8SDK后台创建的激励视频类型的广告位ID，如果还不知道怎么创建，可以参考文档:获取广告参数
RewardNamestring奖励物品的名称
RewardNumstring奖励物品的数量
  1. 展示广告
c++
if (UU8PlatformBridgeBPLibrary::IsRewardVideoAdReady(AdId))
{
    UU8PlatformBridgeBPLibrary::ShowRewardVideoAd(AdId);
}
  1. 广告回调

广告事件触发时，SDK会通过UU8PlatformBridgeSubsystem::OnAdEvent回调给游戏，其中AdType为rewardVideo，EventType为具体的事件名称。 目前主要有如下事件：

bash

onReward: 符合发放奖励的条件，给玩家发放奖励
onLoaded: 广告加载成功
onShow: 广告曝光成功
onFailed: 广告加载或播放失败
onClicked: 广告被点击
onSkip: 广告被跳过
onClosed: 广告被关闭
2、 插屏广告
  1. 加载广告
c++
UU8PlatformBridgeBPLibrary::LoadInterstitialAd(AdId);

参数说明：

参数名称参数类型参数说明
AdIdstringU8SDK后台创建的插屏广告类型的广告位ID，如果还不知道怎么创建，可以参考文档:获取广告参数
  1. 展示广告
c++
if (UU8PlatformBridgeBPLibrary::IsInterstitialAdReady(AdId))
{
    UU8PlatformBridgeBPLibrary::ShowInterstitialAd(AdId);
}
  1. 广告回调

广告事件触发时，SDK会通过UU8PlatformBridgeSubsystem::OnAdEvent回调给游戏，其中AdType为interstitial，EventType为具体的事件名称。 目前主要有如下事件：

bash

onLoaded: 广告加载成功
onShow: 广告曝光成功
onFailed: 广告加载或播放失败
onClicked: 广告被点击
onSkip: 广告被跳过
onClosed: 广告被关闭
3、 横幅广告
  1. 展示广告
c++
UU8PlatformBridgeBPLibrary::ShowBannerAd(AdId, PosType);

参数说明：

参数名称参数类型参数说明
AdIdstringU8SDK后台创建的Banner广告类型的广告位ID，如果还不知道怎么创建，可以参考文档:获取广告参数
PosTypeintBanner广告的位置，1：位于屏幕最上方；2：位于屏幕最下方
  1. 广告回调

广告事件触发时，SDK会通过UU8PlatformBridgeSubsystem::OnAdEvent回调给游戏，其中AdType为banner，EventType为具体的事件名称。 目前主要有如下事件：

bash

onLoaded: 广告加载成功
onShow: 广告曝光成功
onFailed: 广告加载或播放失败
onClicked: 广告被点击
onSkip: 广告被跳过
onClosed: 广告被关闭
4、 开屏广告

自动开屏广告（仅Android平台支持）

因为开屏广告一般是作为启动屏展示， 结合U8聚合SDK提供的分包工具， 我们支持自动将开屏广告作为启动屏（启动Activity），无需游戏开发者接入， 只需要在后台广告参数中打开开关，配置好广告位ID即可：

U8聚合广告-自动开屏

按上图配置后，通过U8聚合SDK打包工具分包后， 就可以测试开屏广告效果了。

但是，请注意， 自动开屏广告也有一定的局限性：。

如果在游戏层自行实现开屏广告， 可以按如下说明调用：

  1. 加载广告
c++
UU8PlatformBridgeBPLibrary::LoadSplashAd(AdId);

参数说明：

参数名称参数类型参数说明
AdIdstringU8SDK后台创建的开屏广告类型的广告位ID，如果还不知道怎么创建，可以参考文档:获取广告参数
  1. 展示广告
c++
if (UU8PlatformBridgeBPLibrary::IsSplashAdReady(AdId))
{
    UU8PlatformBridgeBPLibrary::ShowSplashAd(AdId);
}
  1. 广告回调

广告事件触发时，SDK会通过UU8PlatformBridgeSubsystem::OnAdEvent回调给游戏，其中AdType为splash，EventType为具体的事件名称。 目前主要有如下事件：

bash

onLoaded: 广告加载成功
onShow: 广告曝光成功
onFailed: 广告加载或播放失败
onClicked: 广告被点击
onSkip: 广告被跳过
onClosed: 广告被关闭

其他接口 ​

1、获取当前渠道号

c++

int32 channelID = UU8PlatformBridgeBPLibrary::GetCurrChannel();

2、自定义事件埋点

WARNING

Unity中的代码，我们已经在初始化、注册、登录、创建角色、 进入游戏、 角色等级升级、 支付几个时机做了自动上报，游戏层不用在这些时机再次上报了。

SDK中已经内置了一些数据统计/买量埋点上报插件SDK， 游戏层如果需要上报一些自定义事件到这些平台，可以调用如下接口：

c++
// 键值参数，全部为字符串
TMap<FString, FString> Params;
Params.Add(TEXT("param1"), TEXT("val1"));

// 自定义上报
UU8PlatformBridgeBPLibrary::CustomUpload(TEXT("eventFromUE"), Params);

eventName在定义时请注意， 如下事件名称为SDK内置名称，：

bash
register: 注册
login： 登录
purchase： 支付
createRole： 创建角色
enterGame： 进入游戏
levelUp： 角色等级升级

要使得上报成效， 还需要在U8打包工具中，给对应渠道开启对应的第三方埋点上报/统计插件SDK。

目前Android平台支持的统计/埋点SDK如下：

插件SDK名称SDK目录
友盟统计umengaction
头条买量埋点上报toutiaoaction
腾讯广点通埋点上报tengxunaction
热云reyunaction
快手埋点上报kuaishouaction
百度埋点上报baiduaction
Appsflyer埋点上报appsflyeraction

iOS平台支持的统计/埋点SDK如下：

插件SDK名称SDK目录
友盟统计UmengAction

版权所有© 2021-2030 上海丞诺网络科技有限公司

沪ICP备17007891号-3 沪公网安备 31011202012782号