集成开始

1 准备

1.1准备环境

USDK提供资源

• Unity插件安装包：点击查看

接入方提供

• 准备能联网的安卓设备5.0、iOS设备iOS11.0以上（USDK必须在真机上运行，否则所有回调不成功）
• iOS开发环境:
  • 需要 Xcode15以上版本
  • iOS11.0以上
• 安卓开发环境:
  • JDK 1.8 或以上版本
  • Android Studio 3.0.0或以上版本
  • gradle 2.3.3或以上版本
• 保证游戏运营已经在USDK创建游戏管理成功，准备接入必须要的各项参数，详见各章节

1.2时序图

2 集成SDK

2.1.1 资源导入

在文档中心下载资源包，下载后解压文件夹，将得到如图文件夹，将所有文件导入:

2.1.2 资源说明

提示

以下资源都不能删除，打包后，只会导入对应平台的资源，请勿删除，否则会导致编译错误。如：导出移动端的包，不会带PC的资源

• HeroUSDK USDK文件目录
  • Editor 包含的是Xcode出包相关功能代码
  • Resources PC端相关.prefab资源
  • Script 包含Unity中间层C#中间层代码
  • Plugins 包含Android，iOS端相关库与配置文件
    • Android
      • AndroidManifest.xmlandroid清单文件
      • libs为融合相关的libs库
      • assets为融合相关配置文件
      • gradleTemplate.properties为AndroidX相关配置文件
      • launcherTemplate.gradle为AndroidX相关库引用文件
    • HeroUSDKForIOS
      • UnityForXcodeConfig.json 为SDK基础Xcode配置文件
      • HeroUsdk 为SDK库以及第三方库
• ZFBrowser 浏览器插件资源

2.1.3 Android端配置

1. 在Unity编辑器中勾选 Custom Main Manifest ，路径如下: File/Build Settings/Player Settings/Custom Main Manifest

   

   修改Assets/Plugins/Android/AndroidManifest.xml清单文件中package参数为真实游戏包名，插件中默认为Demo包名请注意修改

2. 在Unity编辑器中勾选Custom Launcher Gradle Template，路径如下:File/Build Settings/Player Settings/Custom Launcher Gradle Template

   

   修改Unity工程中生成的launcherTemplate.gradle文件，在dependencies中添加AndroidX依赖支持，如下代码:

   implementation "androidx.multidex:multidex:2.0.1"
   implementation "androidx.appcompat:appcompat:1.2.0"
   

   android配置中添加compileOptions配置，代码如下:

   compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
   }
   

   修改完成后如图:

   

3. 在Unity编辑器中勾选Custom Gradle Properties Template，路径如下:File/Build Settings/Player Settings/Custom Gradle Properties Template

   

   修改Unity工程中生成的gradleTemplate.properties文件，在文件中添加AndroidX配置

   android.useAndroidX=true
   android.enableJetifier=true
   

   修改完成后如图:

   

注意事项:

1、修改需要修改herosdkcfg.xml中_hu_pid_与_hu_pk_的值，Demo工程中文件在以下截图位置:

• 相关参数可联系游戏运营在USDK管理后台 (opens new window)的游戏管理-游戏首页中获取

2、插件资源中，Android端清单配置AndroidManifest.xml不可修改.其中包含了USDK的HeroUSDKApplication,HeroUSDKSplashActivity,HeroUSDKUnityPlayerActivity缺一不可,且游戏中不能同时存在多个Application配置。出现以上配置修改都会出现SDK功能异常,无法出Android母包。

以下为Demo工程中文件截图:

2.1.4 iOS端配置

1. iOS端从Unity工程中导出Xcode工程后，可在工程中配置镜像ID、屏幕旋转方式、埋点地址、灾备地址等，如图

   

2.1.5 PC端配置

1. 请确保在导入Unity插件时，将USDKResources拷贝到Unity工程中.目前插件中Resources包含如下资源:

   

   • LoginPannel.prefab为手机登录、微信扫码登录界面。
   • PayPannel.prefab为微信、支付宝扫码支付界面。
   • ProtocolPannel.prefab为协议内容界面。
   • QQLoginPannel.prefab为QQ登录界面。
   • RealNamePannel.prefab为实名认证界面。

2. 所有Prefab资源SDK在相关登录、支付等功能中已内部添加。游戏无需自己再拖入场景中.如果CP需要修改添加方式，则需要修改HeroUSDK/Script/HeroUSDKImp.cs中getGameObjectByAssetPrefab方法

   //添加显示Prefab组件
   public void getGameObjectByAssetPrefab(string prefabName)
   {
       if (!this.prefabDic.ContainsKey(prefabName))
       {
           GameObject gameObject = HeroUSDKUtils.getGameObjectByAssetPrefab(prefabName);
           var transform = this.usdkListener.transform;
           gameObject.transform.parent =  transform ;
           gameObject.GetComponent<RectTransform>().offsetMin = new Vector2(0.0f, 0.0f);
           gameObject.GetComponent<RectTransform>().offsetMax = new Vector2(0.0f, 0.0f);
           //gameObject.transform.position = transform.localPosition ;
           this.prefabDic.Add(prefabName,gameObject);
       }
   }
   

   注意：

   • 添加Prefab组件前，需要游戏在场景中挂载继承HeroUSDKListener的脚本以便接收SDK回调
   • 因为是使用Prefab组件来显示相关内容，Unity场景中需要添加Canvas才可以正常显示

   以下为Demo游戏中配置截图:

   

   • 其中EventHandle继承于HeroUSDKListener，参考设置回调监听对象

3. SDK内部添加Prefab组件是以覆盖形式添加.游戏中可能需要自定义相关组件的大小与样式

   以登录界面LoginPannel.prefab为案例:

   

   相关组件介绍:

   • Browser (GUI)为浏览器组件，主要作用为加载浏览器内容
   • Reload_Button为刷新按钮，主要用于刷新网页内容
   • Close_Button为关闭按钮，主要用于关闭登录界面，并给游戏相关回调

   以上为登录界面基础组件.其中Browser(GUI)、Reload_Button、Close_Button仅可以修改大小以及相对位置。

   Browser(GUI)组件中挂载的脚本属性建议使用默认不进行修改，否则会出现加载网页异常。

   修改组件Rect Transform可查看参考资料 (opens new window)

4. 登录组件在游戏中运行后如截图:

   

5. Unity导出应用程序配置

   1. 在Unity编辑器中File/Build Settings中，勾选需要打包的场景。

   2. 在Platform/Target Platform中选择Windows，如图:

      

   3. Player Settings中设置游戏所需配置

   4. 点击Build按钮，选择应用保存地址后，等待Unity导出完成即可

   1. 在Unity编辑器中File/Build Settings中，勾选需要打包的场景。

   2. 在Platform/Target Platform中选择Mac OS X，如图:

      

   3. Player Settings中设置游戏所需配置

   4. 点击Build按钮，选择应用保存地址后，等待Unity导出完成即可

6. 代币支付

   在项目的Content目录下放入名为hero_package_config的文件（空文件，无后缀）即为代币支付，此代币支付用于版署合规性审查。代币申请请联系运营同学。

7. 防沉迷 PC端设置防沉迷强制下线回调

   1. 根据政策要求，游戏必须接入「防沉迷强制下线」流程;
   2. 触发防沉迷后，会通过该接口将通知玩家下线;
   3. CP需实现此接口，并自定义界面显示文本;
   4. PC防沉迷已与移动端保持一致，

2.1.6 Steam端配置

1. 从Steam官网 (opens new window)下载最新版本的Steamworks SDK，并拷贝下载文件到Unity工程中

   

   注意:

   如果没有图中所示文件夹，则需要CP自己创建，格式：steamworks_sdk_{版本号}文件夹；将下载的Steamworks SDK放入该文件夹中，如图中所示155为插件开发版本

2. 下载Github (opens new window)下载最新版本Steamworks.NET的 .unitypackage 插件，并将其导入到Unity工程中，如下图:

   

3. 修改Assets/Scripts/Steamworkds.NET/SteamManagers.cs中Awake方法中的参数，修改SteamAPI.RestartAppIfNecessary中的参数，为游戏申请的Steam真实参数

   

4. 修改Unity工程中steam_appid.txt文件中的参数为游戏真实参数，如图位置:

   

5. Unity主场景中新建GameObject并挂载Steamworks.NET提供的SteamManager脚本，如图:

   

6. Unity场景生命周期新增USDKOnEnable方法处理

   
   private void OnEnable()
   {
       HeroUSDK.getInstance().OnEnable();
   }
   
   

7. 登录改成调用 steam登录接口，如下代码:

   // 替换登录调用 HeroUSDK.getInstance().login();
   HeroUSDK.getInstance ().steamLogin(); 
   

注意

Unity中运行插件，都需要本地运行Steam客户端进行调试

2.1.7 鸿蒙端配置

1. 配置鸿蒙参数

点击编译器GameConfig配置华为环境

找到中台复制参数

将中台复制的参数复制游戏参数里面，点击生成配置盘数

复制的参数会在HeroUSDK/Resources/Config/HeroUProjectNew 里面

2. 打包

下在鸿蒙打包插件然后导出DevEco Studio 工程 注意：打鸿蒙包需要删除HeroUSDK这个程序集，鸿蒙暂时不支持程序集

3. 修改DevEco Studio 工程代码UnityMainWorkerHandler.ts代码

修改entry\src\main\ets\workers\UnityMainWorkerHandler.ts代码

1.1 添加引用

import hilog from '@ohos.hilog';
import { SDKHandler } from '@ohos/libSysSDKCapabilities'

1.2 在workerPort.onmessage = function (e) 添加

case "syncHMSSDKResult":
      SDKManager.HMSSDKSyncToWorker(data.data_type, data.data)
      break;

4. 修改DevEco Studio 工程代码UnityMainWorker.ets代码

修改entry\src\main\ets\workers\UnityMainWorker.ets代码

1.1 添加引用

import { SDKManager } from "@ohos/libSysSDKCapabilities";

1.2 在 this.threadWorker.onmessage = async function (msg)中添加

 if (msg.data.type == "Login_SDK") {
        let result = await SDKHandler.getInstance().handleLogin();
        hilog.info(0x0000, "LoginSDK", 'login success: %{public}s', JSON.stringify(result));
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "Login", 'data': result });
      }
      if (msg.data.type == "IAP_Init") {
        let result = await SDKHandler.getInstance().handleInitIAP();
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "IAPInit", 'data': result });
      }
      if (msg.data.type == "IAP_QueryProducts") {
        let param = JSON.parse(msg.data.data);
        let result = await SDKHandler.getInstance().handleQueryIAPList(param.productType, param.productIds);
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "QueryList", 'data': result });
      }
      if (msg.data.type == "IAP_Purchase") {
        let param = JSON.parse(msg.data.data);
        let result = await SDKHandler.getInstance().handleStartPurchase(param.productType, param.productId,param.developerPayload);
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "StartPurchase", 'data': result });
      }
      if (msg.data.type == "IAP_ConsumePurchase") {
        let parameter = JSON.parse(msg.data.data);
        let result = await SDKHandler.getInstance().handleConsumePurchase(parameter.purchaseToken);
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "ConsumePurchase", 'data': result });
      }
      if (msg.data.type == "IAP_QueryOwnedPurchases") {
        hilog.info(0x0001, "Iap Demo", 'IAP_QueryOwnedPurchases msg.data.data is: ' + msg.data.data)
        let param = JSON.parse(msg.data.data);
        let result = await SDKHandler.getInstance().handleCheckOwnedPurchases(param.productType);
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "CheckOwnedPurchases", 'data': result });
      }
      if (msg.data.type == "GamePlayer_Init") {
        let result = await SDKHandler.getInstance().handleGamePlayerInit();
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "GamePlayerInit", 'data': result });
      }
      if (msg.data.type == "GamePlayer_GetLocalPlayer") {
        let result = await SDKHandler.getInstance().handleGamePlayerGetLocal();
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "getLocalPlayer", 'data': result });
      }
      if (msg.data.type == "GamePlayer_SavePlayerRole") {
        let result = await SDKHandler.getInstance().handleGamePlayerSave(msg.data.data);
        // 向worker线程发送消息
        UnityMainWorker.getInstance()
          .postMessage({ 'type': 'syncHMSSDKResult', 'data_type': "savePlayerRole", 'data': result });
      }

5. 下载libSysSDKCapabilities 模块 下载地址：点击下载 (opens new window)

1.将libSysSDKCapabilities 模块放在打出的鸿蒙工程里

2.在build-profile.json5 添加模块的引入

"name": "libSysSDKCapabilities",
"srcPath": "./libSysSDKCapabilities"

3.在entry/oh-package.json5文件中注册模块

 "@ohos/libSysSDKCapabilities": "../libSysSDKCapabilities"

4.在entry\src\main\module.json5 中加入client_id和app_id（从华为后台取）

{
        "name": "client_id",
        "value": "*********"  //配置为步骤1中获取的Client ID
      },
      {
        "name": "app_id",
        "value": "**************"  //配置为步骤1中获取的APP ID
      }

3 测试指南

如果在接入、测试过程中遇到问题，你可以点击查看常见问题

前提条件 确定游戏能正常打包

开始验证 在确认资源导入后，请开发者尝试将游戏+资源进行打包：

• 如果打包成功并运行后有用户协议弹窗出现，则可以继续接入《第二步：开始接入》
• 如果打包不成功或运行后没有弹出弹窗，请联系我们反馈问题

恭喜你完成USDK集成，让我们开始《第二步：开始接入》吧～