Unity

环境要求

Unity 2019.4 或更高版本
Android 5.0, API 21 或更高版本
iOS 11.0

项目配置

1. 6.21.1 版本以后新的依赖方式

在 Packages/manifest.json 中按需添加下述内容，从 6.21.1 开始请使用由 XDSDK 准备的 TapSDK 版本（请注意均在包名 com.xd.tds 下，且版本号格式有变化）。

{
    "dependencies": {
        "com.xd.sdk.common": "6.23.4",
        "com.xd.sdk.account": "6.23.4",
        "com.leancloud.realtime": "2.4.0",
        "com.leancloud.storage": "2.4.0",
        "com.xd.tds.bootstrap": "3.29.5-xd.1",
        "com.xd.tds.common": "3.29.5-xd.1",
        "com.xd.tds.login": "3.29.5-xd.1",
        "com.xd.tds.tapdb": "3.29.5-xd.1",
        "com.tapsdk.androiddependencyresolver": "1.2.3",
        // 上面是必选模块，以下为可选模块
        // TapSDK 其他业务
        "com.xd.tds.antiaddiction":"3.29.5-xd.1",
        "com.xd.tds.moment": "3.29.5-xd.1",
        "com.xd.tds.support": "3.29.5-xd.1",
        "com.xd.tds.achievement": "3.29.5-xd.1",
        "com.xd.tds.billboard": "3.29.5-xd.1",
        "com.xd.tds.friends": "3.29.5-xd.1",
        "com.xd.tds.dlc": "3.29.5-xd.1",
        "com.xd.tds.update": "3.29.5-xd.1",
        // XDSDK 支付模块
        "com.xd.sdk.payment": "6.23.4",
        // XDSDK 海外模块，包含海外第三方业务 SDK
        "com.xd.sdk.oversea": "6.23.4",
        // XDSDK 国内模块，包含国内第三方业务 SDK
        "com.xd.sdk.mainland": "6.23.4",
        // XDSDK 分享模块，包含国内外不同的分享逻辑，需要搭配国内或海外模块使用
        "com.xd.sdk.share": "6.23.4",
        // XDSDK 广告分包模块，包含今日头条广告SDK、分包SDK、腾讯广点通广告SDK、分包SDK 
        "com.xd.sdk.ads.subpkg": "3.6.1",
        // XDSDK 公告模块
        "com.xd.sdk.announcement": "6.23.4",
        // XDSDK 举报模块
        "com.xd.sdk.report": "6.23.4",
        "com.unity.nuget.newtonsoft-json": "3.2.1",
        // PC 平台需要添加
        "com.unity.textmeshpro": "3.0.6",
    },
    "scopedRegistries": [
        {
            // NPMJS 访问不通时可以切换到淘宝源试试 https://registry.npmmirror.com
            // 公司内网可使用 http://npm.xindong.com 
            "name": "NPMJS",
            "url": "https://registry.npmjs.org/",
            "scopes": [
                "com.xd",
                "com.tapsdk",
                "com.leancloud"
            ]
        }
    ]
}

6.21.1 版本以前的依赖方式

通过 UPM 方式添加引用 (公网使用，需要能正常访问 Github 的环境) ：

"com.leancloud.realtime": "https://github.com/leancloud/csharp-sdk-upm.git#realtime-2.4.0",
"com.leancloud.storage": "https://github.com/leancloud/csharp-sdk-upm.git#storage-2.4.0",
"com.taptap.tds.bootstrap": "https://github.com/TapTap/TapBootstrap-Unity.git#3.27.1",
"com.taptap.tds.common": "https://github.com/TapTap/TapCommon-Unity.git#3.27.1",
"com.taptap.tds.login": "https://github.com/TapTap/TapLogin-Unity.git#3.27.1",
"com.taptap.tds.tapdb": "https://github.com/TapTap/TapDB-Unity.git#3.27.1",
"com.xd.sdk.common": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-common-upm-6.21.0",
"com.xd.sdk.account": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-account-upm-6.21.0",
"com.tapsdk.androiddependencyresolver": "https://github.com/taptap/android_dependency_resolver.git#1.2.3",
// 以下为可选
// 支付模块
"com.xd.sdk.payment": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-payment-upm-6.21.0",
// Apple/Google/Facebook/Twitter 登录 SDK & Appsflyer、Firebase 等埋点 SDK
"com.xd.sdk.oversea": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-oversea-upm-6.21.0",
// 国内QQ、微信、微博、抖音、小红书分享 SDK
"com.xd.sdk.mainland": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-mainland-upm-6.21.0",
// 分享接口 SDK
"com.xd.sdk.share": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-share-upm-6.21.0",
// 今日头条广告SDK、分包SDK；腾讯广点通广告SDK、分包SDK 
"com.xd.sdk.ads.subpkg": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-adsubpkg-upm-3.5.0",
// 公告 SDK
"com.xd.sdk.announcement": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-announcement-upm-6.21.0",
// 举报 SDK
"com.xd.sdk.report": "https://github.com/xd-platform/xdsdk_common.git#xdsdk-report-upm-6.21.0",
// 防沉迷 SDK
"com.tapsdk.antiaddiction":"https://github.com/taptap/TapAntiAddiction-Unity.git#3.27.1",
// PC 平台需要
"com.unity.textmeshpro":"3.0.6"

通过 NPM 方式添加引用 (在心动内网下可使用)

"com.leancloud.realtime": "2.4.0",
"com.leancloud.storage": "2.4.0",
"com.taptap.tds.bootstrap": "3.27.1",
"com.taptap.tds.common": "3.27.1",  
"com.taptap.tds.login": "3.27.1",
"com.taptap.tds.tapdb": "3.27.1",
"com.xd.sdk.common": "6.21.0",
"com.xd.sdk.account": "6.21.0",
"com.tapsdk.androiddependencyresolver": "1.2.3",
// 以下为可选
// 支付模块
"com.xd.sdk.payment": "6.21.0",
// Apple/Google/Facebook/Twitter 登录 SDK & Appsflyer/Firebase 等埋点 SDK
"com.xd.sdk.oversea": "6.21.0",
// 国内QQ、微信、微博、抖音、小红书分享 SDK
"com.xd.sdk.mainland": "6.21.0",
// 分享接口 SDK
"com.xd.sdk.share": "6.21.0",
// 今日头条广告SDK、分包SDK；腾讯广点通广告SDK、分包SDK 
"com.xd.sdk.ads.subpkg": "3.5.0",
// 公告 SDK
"com.xd.sdk.announcement": "6.21.0",
// 举报 SDK
"com.xd.sdk.report": "6.21.0",
// 防沉迷 SDK
"com.tapsdk.antiaddiction":"https://github.com/taptap/TapAntiAddiction-Unity.git#3.27.1", // 防沉迷 SDK "com.tapsdk.antiaddiction":"$3.27.1"`}

还需要注册对应的 NPM 路径

"scopedRegistries": [
  {
    "name": "XDSDK",
    "url": "http://npm.xindong.com",
    "scopes": [
      "com.xd"
    ]
  },
  {
    "name": "TapSDK",
    "url": "https://nexus.tapsvc.com/repository/npm-registry/",
    "scopes": [
      "com.tapsdk",
      "com.taptap",
      "com.leancloud"
    ]
  }
]

XDSDK 版本信息参见：RELEASE NOTE，TapSDK 版本号参考：TapSDK ChangeLog。

附：XDSDK 旧版（6.4.0 之前）国内 ChangeLog、海外 ChangeLog。

提示

如果您需要使用 TapSDK 3.19.0 （含）以上的版本时，请将 XDSDK 的版本升级到 6.10.3 （含）以上。

因为 TapSDK 内部 JSON 解析库存在 bug（对部分国家的货币数字解析错误），所以请游戏一定注意将依赖的 TapCommon 模块版本升级到 3.11.0（含）以上。

2. 相关配置文件

将 TDS-Info.plist 放在 /Assets/Plugins 中。
从 6.9.0 开始 XDConfig.json 各个平台（Android、iOS）从 /Assets/Plugins （PC 平台在 /Assets/Resources ）中，改至 /Assets 中，并且出包后，会直接拷贝到包中的Application.streamingAssetsPath下面
【可选】需要使用 Firebase 埋点时
- iOS：将 GoogleService-Info.plist 放在 /Assets/Plugins/iOS 中。
- Android：将 google-services.json 放在 /Assets/Plugins/Android。
以上两个文件是游戏从 Firebase 后台下载的。
【可选】需要使用 Twitter 或 Firebase 时。
- 将 AndroidManifest.xml 放在 /Assets/Plugins/Android 中，按需修改。

3. iOS 系统功能确认

检查 Xcode Capabilities 中是否打开 In-App Purchase（苹果支付）、Push Notifications（推送）、Sign In With Apple（苹果登录）功能。

4. iOS 配置 App 所需能力

如果您的 APP 具有苹果登录、微信分享、推送等功能，需要在 Xcode 工程的 Unity-iPhone Target 下，点击 + Capabilities 按钮，添加自己所需的功能，具体开启方式如下图：

编辑您的 Unity-iPhone.entitlements 文件（位于 Xcode 工程的目录下面），值得注意的是， Entitlements 里面申请的功能必须和你 iOS 的证书包含的功能一致，否则打包失败 (这个证书功能开启需要到Apple开发者平台去配置。简单一点的话，可以用上述Xcode的+ Capabilities 功能，会自动帮我们配置)。Entitlements 示例如下，不用的可以删掉：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- 苹果登录需要的权限 -->
    <key>aps-environment</key>
    <string>development</string>
    <key>com.apple.developer.applesignin</key>
    <array>
        <string>Default</string>
    </array>
    <!-- 实现通用链接 universal link 的配置，微信、QQ 等分享需要 -->
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:example.com</string>
        <string>applinks:www.xd.com</string>
    </array>
</dict>
</plist>

最后在 Build Setting -> Code Signing Entitlements 的路径里配置成你生成的 Entitlements 文件。

5. Android 配置网页支付

XDSDK 从 6.6.0 版本开始，针对 RegionType 为 Global 的类型的网页支付（即海外），在网页支付上不再使用嵌入式 WebView 的形式，改为使用 Android 上的 Chrome 自定义选项卡。

针对 Android 11（Android Api Level >= 30）及以上软件包可见性的适配，在 AndroidManifest.xml 文件中增加 Custom Tabs Service 查询以及支持获取第三方浏览器的信息的查询：

<queries>
    ...
    <intent>
        <action android:name="android.support.customtabs.action.CustomTabsService"/>
    </intent>
  <intent>
      <action android:name="android.intent.action.VIEW" />
      <data android:scheme="https" />
  </intent>
    ...
</queries>

为启用 Chrome 自定义选项卡所需的配置添加 URL Scheme 属性，同时将 SchemeCCTActivity 添加到 AndroidManifest.xml 文件中：

提示

URL Scheme 组成规则：xd + xd_client_id，其中 xd_client_id 为全小写。

举例 : 你的 XD Client ID 为：hn5RcJei2JxCYlS0，在 AndroidManifest.xml 文件中添加的格式为

<data
    android:host="xdcctwebpay"
    android:scheme="xdhn5rcjei2jxcyls0"/>

<activity
    android:name="com.xd.intl.payment.ui.SchemeCCTActivity"
    android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>

        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>

        <data
            android:host="xdcctwebpay"
            android:scheme="xd{your_xd_client_id}}"/>
    </intent-filter>
</activity>

6. Android 分享相关配置

确保 XDConfig.json 配置文件中已配置 QQ、微信、微博、抖音、小红书的配置：

{
   ...
   "wechat": {
      "app_id": "********", // WeChat 分享/支付 配置，可选，没有可以删除配置
   },
   "qq": {
      "app_id": "*******", // QQ 分享配置，可选，没有可以删除配置
   },
   "weibo": {
      "app_id": "*******", // Weibo 分享配置，可选，没有可以删除配置
   },
   "douyin": {
    "app_id": "*******" // 抖音分享配置，可选，没有可以删除配置
   },
   "xhs": {
    // 小红书分享配置，可选，没有可以删除配置
    "app_id_ios": "*******",
    "app_id_android": "*******",
    "universal_link": "https://www.xd.com/xxx/"
  }
}

集成分享 SDK

请参考新版分享进行集成

7. Android 国内微信支付相关配置

确保 XDConfig.json 配置文件中已配置微信的 {app_id} 参数值：

{
   ...
   "wechat": {
      "app_id": "********", // WeChat 分享/支付 配置，可选，没有可以删除配置
   }
}

集成微信支付 SDK

微信支付的 SDK 与分享功能集成的 SDK 是同一个，Unity 的 XDSDK 中会默认自动通过 XDConfig.json 文件中的配置来添加 Android 上的依赖，请确保已集成 XDSDK-Unity 的 Mainland 模块：

{
    "dependencies": {
        // ...

        "com.xd.sdk.mainland": "6.23.4",
    },
    "scopedRegistries": {
        // ....

        {
            // 通过 NPMJS 方式添加引用，推荐正常能访问公网环境时使用
            // 如果访问 NPMJS 存在问题，提供司内内网的备用方案，url 替换为 http://npm.xindong.com 即可。
            "name": "NPMJS",
            "url": "https://registry.npmjs.org/",
            "scopes": [
                "com.xd"
            ]
        }
    }
}

在应用的 AndroidManifest.xml 文件中添加如下配置，请将 {应用包名} 替换为游戏正确包名，否则无法收到微信支付回调：

   <activity-alias
        android:name="{应用包名}.wxapi.WXPayEntryActivity"
        android:exported="true"
        android:targetActivity="com.xd.intl.payment.impl.wechatpay.WXPayEntryActivity" />

8. Android 11 适配配置

提示

从 XDSDK 6.15.0 的版本开始，我们对业务范围内需要添加的 Android 11 及以上的版本中需要增加的软件包可见性的适配进行了增加，您可只关心其他业务需要增加的配置即可。

如果您的应用以 Android 11（API 级别 30）或更高版本为目标平台，在默认情况下，系统会自动让部分应用对您的应用可见，但会隐藏其他应用。通过让部分应用在默认情况下不可见，系统可以了解应向您的应用显示哪些其他应用，这样有助于鼓励最小权限原则，还可帮助 Google Play 等应用商店评估应用为用户提供的隐私权和安全性。针对 XDSDK 支持的登录类型的平台，在手机安装有对应 App 的情况下，无法正常跳转外部 App 进行授权登录时请参考以下配置项进行软件包可见性的适配配置，将 <queries> 标签里的配置添加到 AndroidManifest.xml 文件中：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="string">
 
   <application
      . . .
   </application>

    <!--添加如下 queries 标签的内容，直接在 manifest 标签下-->
  <queries>
      <!-- TapTap -->
      <package android:name="com.taptap"/>
      <package android:name="com.taptap.pad"/>
      <package android:name="com.taptap.global"/>

      <!-- Facebook 可选 没有使用到 FB 则可以不用配置 -->
      <package android:name="com.facebook.katana"/>
      <!-- Facebook 有端分享 没有使用到 FB 则可以不用配置 -->
      <provider android:authorities="com.facebook.katana.provider.PlatformProvider"/>
      <!-- Twitter 没有使用到 Twitter 则可以不用配置 -->
      <package android:name="com.twitter.android"/>
      <!-- LINE 没有使用到 LINE 则可以不用配置 -->
      <package android:name="jp.naver.line.android"/>
      
      <!-- 国内分享-->
      <!-- wechat-->
      <package android:name="com.tencent.mm"/>
      <!-- qq -->
      <package android:name="com.tencent.mobileqq"/>
      <!-- qq 空间-->
      <package android:name="com.tencent.qzone"/>
      <!-- weibo-->
      <package android:name="com.sina.weibo"/>
  </queries>
</manifest>

9. Android Facebook 相关配置

接入 Facebook SDK 时，无论是需要 Facebook 登录或者分享的功能，需要对应用进行一些额外的配置，详情可参见按照 Facebook 快速接入文档。以下是配置示例，请按照游戏实际参数值进行文本替换：

<!-- Facebook Application ID 配置 -->
<meta-data 
    android:name="com.facebook.sdk.ApplicationId"
    android:value="{your_application_id}" />

<!-- Facebook 分享需要的配置 -->
<provider
    android:name="com.facebook.FacebookContentProvider"
    android:authorities="com.facebook.app.FacebookContentProvider{your_application_id}}"
    android:exported="true" />

<!-- Facebook 在无端授权时需要做的配置（Facebook 已废弃内嵌 WebView 可授权模式，采用的时 Chrome Custom Tabs 服务，需要添加这个配置来做支持）-->
<activity
    android:name="com.facebook.CustomTabActivity"
    android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="fb{your_application_id}" />
    </intent-filter>

</activity>

特别需要注意的是：Facebook 的 Application ID 一般给到的是纯数字的 ID，在 Unity 或者 UE 上打包出来的 Android apk 在部分机型上 Facebook SDK 在初始化时读取内容会是纯数字，这时会报错。对此情况可在 AndroidManifest.xml 文件配置中添加的 meta-data 标签中的 android:value 属性配置的值最前面添加"\"符号，或直接使用 Android 的 string.xml 资源文件形式进行资源 ID 引用。

<meta-data 
    android:name="com.facebook.sdk.ApplicationId"
    android:value="\1234567890987" />

// or

<meta-data
    android:name="com.facebook.sdk.ApplicationId"
    android:value="@string/facebook_application_id" />

PC 配置

1. 下载 PC SDK

因为 PC 模块使用到了 Assets 方式的插件（WebView），所以只能以 unitypackage 的方式单独安装，请在 Releases 中下载对应版本的 PC 模块。

2. PC 浏览器插件

SDK 中使用到了付费 PC WebView 插件：3D WebView for Windows and macOS 内部游戏可以联系 TDS 获得；外部游戏则需要自行购买。将插件导入到 Unity 工程即可。

3. 日志调试

XDLogger.LogDelegate = (level, message) => {
    switch (level) {
        case XDLogLevel.Debug:
            Debug.Log($"[DEBUG] {message}");
            break;
        case XDLogLevel.Warn:
            Debug.LogWarning($"[WARN] {message}");
            break;
        case XDLogLevel.Error:
            Debug.LogError($"[ERROR] {message}");
            break;
        default:
            break;
    }
};

4. 支付

PC 平台仅支持网页支付以及查询需要补款的订单SDK UI 弹窗

国内支付

目前支持微信和支付宝，采用内置浏览器的 Web 支付方式

XDGPayment.PayWithWeb(orderId, productId, productName, payAmount, roleId, serverId, extras, (resultType, str) => {
        if (resultType == WebPayResultType.OK) {
            XDLogger.Debug("支付完成");
        } else if (resultType == WebPayResultType.Cancel) {
            XDLogger.Debug("取消支付");
        } else if (resultType == WebPayResultType.Error) {
            XDLogger.Debug($"支付异常: {str}");
        }
    }
);

海外支付

目前支持跳转官网浏览器支付方式

5. Windows 平台网页登录唤醒

参考文档

6. 注意

PC SDK 中使用到了付费的 WebView 插件，Vuplex 目录只允许在公司内使用，切勿传播。

7. Steam 登录 & 支付

如果项目涉及到 Steam 登录或支付功能，需要下载 Steam SDK 并安装。当发布 Steam 包时，在 Unity Editor 的 Build Settings -> Player Settings -> Scripting Define Symbols 中添加 XD_STEAM_SUPPORT 宏。

常见问题

[Android] 升级 OAID 库与其他库有冲突？

构建 Android App 时提示 OAID 库与其他库有 android:allowBackup 属性冲突，这里推荐游戏以 OAID 的配置为准，在 AndroidManifest.xml 文件中的 <application> 节点添加以下属性：

...
<manifest>
   <application
        ...
        xmlns:tools="http://schemas.android.com/tools"
        android:allowBackup="false"
        tools:replace="android:allowBackup" >
        ...
   </application>
</manifest>
...

当然，如果有特殊需求，可以将 android:allowBackup 的属性设置为 true，关于 android:allowBackup 属性的说明请参考 Google 官方文档，请按照实际需求来变更需要的属性。

[Android] 接入海外版本的 XDSDK 网页支付支付结束之后无法跳转回游戏？

请参考Android 网页支付配置相关内容进行配置更改，请注意 xd_client_id 的全小写匹配规则。

Unity

环境要求​

项目配置​

1. 6.21.1 版本以后新的依赖方式​

2. 相关配置文件​

3. iOS 系统功能确认​

4. iOS 配置 App 所需能力​

5. Android 配置网页支付​

6. Android 分享相关配置​

7. Android 国内微信支付相关配置​

8. Android 11 适配配置​

9. Android Facebook 相关配置​

PC 配置​

1. 下载 PC SDK​

2. PC 浏览器插件​

3. 日志调试​

4. 支付​

国内支付​

海外支付​

5. Windows 平台网页登录唤醒​

6. 注意​

7. Steam 登录 & 支付​

常见问题​

[Android] 升级 OAID 库与其他库有冲突？​

[Android] 接入海外版本的 XDSDK 网页支付支付结束之后无法跳转回游戏？​