跳到主要内容

Android

环境要求​

  • Android 5.0，API 21 或更高版本。
备注

请注意：XDSDK 目前使用的是 AndroidX 方案，与旧版本的 support 版本不兼容，建议游戏采用 AndroidX 版本，为以后在 Android 平台有更好的支持。

附：Google 官方迁移至 AndroidX 文档

接入前准备​

下载 XDSDK Android，解压后选择需要用到的 SDK aar 包导入到项目 your_app > app > libs 目录下。

集成 XDSDK​

  1. 在您的项目中，打开 your_app > Gradle Scripts > build.gradle(Module:app)，添加以下依赖到 dependencies{} 部分：
// 基础库， 必须
implementation files('libs/XDGCommon_6.22.2.aar')
// 登录
implementation files('libs/XDGAccount_6.22.2.aar')
// 支付
implementation files('libs/XDGPayment_6.22.2.aar')
// 第三方登录
implementation files('libs/XDGThirdLogin_6.22.2.aar')
// 第三方登录（国内）
implementation files('libs/XDGThirdLoginCN_6.22.2.aar')
// 第三方埋点
implementation files('libs/XDGThirdTrack_6.22.2.aar')
// 第三方分享（合并国内海外）
implementation files('libs/XDGSharing_6.22.2.aar')


// 手机「一键登录」（国内）
implementation files('libs/ali_auth_number_2.12.11.2.aar')
implementation files('libs/main-2.1.4-release.aar')
implementation files('libs/logger-2.1.5.2-release.aar')

// XDSDK 广告包/分包（可选）
implementation files('libs/XDADs_6.22.2.aar')

// XDSDK 依赖的 TapSDK 库
implementation files('libs/TapBootstrap_3.27.1.aar')
implementation files('libs/TapCommon_3.27.1.aar')
implementation files('libs/TapLogin_3.27.1.aar')
implementation files('libs/TapDB_3.27.1.aar')

// 基础库依赖
implementation 'androidx.appcompat:appcompat:1.3.1'
implementation 'com.google.code.gson:gson:2.8.6'
implementation 'cn.leancloud:realtime-android:8.2.17'
implementation 'cn.leancloud:storage-android:8.2.17'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'

// Google Advertising ID
implementation "com.google.android.gms:play-services-ads-identifier:17.0.0"

// 国内分享相关
//wechat share
implementation "com.tencent.mm.opensdk:wechat-sdk-android:6.8.0"
//sina weibo share
implementation "io.github.sinaweibosdk:core:$12.5.0@aar"
// qq share
implementation files('libs/open_sdk_3.5.14.3_rc26220c_lite.jar')

// 国内支付相关
// 支付宝支付
implementation "com.alipay.sdk:alipaysdk-android:15.8.11@aar"
// 微信支付（同微信分享）
implementation "com.tencent.mm.opensdk:wechat-sdk-android:6.8.0"

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

备注
  • XDSDK 包含了登录、支付及一些基础功能，游戏可自行选择需要接入的模块，第三方登录、第三方埋点同理。
  • XDSDK 本身不强制绑定 TapSDK 的版本，TapSDK 未有重大 API 变动时，游戏可根据自身需求依赖对应的 TapSDK 版本。
  1. 添加 OAID SDK 为保证 TapDB 数据的精准性，需要游戏将 OAID SDK 添加到项目中，下载 OAID SDK，在 your_app > Gradle Scripts > build.gradle(Module:app)，添加 OAID SDK 依赖到 dependencies{} 中。
implementation(name: "oaid_sdk_1.0.25", ext: "aar")
  1. 将 前文中的 XDConfig.json 文件 移到 your_app > src > main > assets 文件夹下。
  2. 构建项目。

网页支付配置相关​

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

  1. 添加 Custom Tabs 依赖：
dependencies {
    ...
    implementation "androidx.browser:browser:1.4.0"
}
  1. 针对 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>
  1. 为启用 Chrome 自定义选项卡所需的配置添加 URL Scheme 属性，同时将 SchemeCCTActivity 添加到 AndroidManifest.xml 文件中：
提示

URL Scheme 组成规则：xd + xd_client_id，其中 xd_client_id 为全小写。 eg. : 你的 XD Client ID 为：hn5RcJei2JxCYlS0，在 AndroidManifest.xml 文件中添加的格式为 <data 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>

第三方登录配置相关​

XDSDK 默认只提供 TapTap 登录和游客登录，其他第三方登录功能集成在 XDGThirdLogin 模块中，游戏可根据自身需要添加对应第三方平台登录配置。

在 your_app > Gradle Scripts > build.gradle(Module:app) 中添加以下依赖：

// Google 登录
implementation "com.google.android.gms:play-services-auth:16.0.1"
// Facebook 登录
implementation "com.facebook.android:facebook-login:15.2.0"
// Twitter 登录
implementation "com.twitter.sdk.android:twitter:3.3.0"
// LINE 登录
implementation "com.linecorp:linesdk:5.0.1"

手机号码「一键登录」配置相关​

  1. 集成阿里云 SDK

XDSDK 使用阿里云「一键登录」SDK 功能相关，需要添加所需的 aar 包，在 your_app > Gradle Scripts > build.gradle(Module:app) 中添加以下依赖：

// 阿里云一键登录
implementation files('libs/ali_auth_number_2.12.11.2.aar')
// 阿里云 SDK 内部的一些核心工具类
implementation files('libs/main-2.1.4-release.aar')
// 阿里云 SDK 内部用于收集日志信息和监控告警
implementation files('libs/logger-2.1.5.2-release.aar')
  1. 可选：若您需要开启资源混淆，则需要在相应工程的 res/raw/keep.xml 文件中添加以下代码：
tools:keep="@drawable/authsdk*,
@layout/widget_pns_*,
@anim/authsdk*,
@theme/authsdk_*,
@id/pns_*,
@id/authsdk*,
@color/pns_*,
@dimen/pns_*"
  1. 可选：域名配置。部分终端设备使用的是中国联通 SIM 卡的 5G 移动数据，可能会导致使用一键登录功能获取本机号码失败。可在 networkSecurityConfig.xml 清单文件配置中添加联通域名（enrichgw.10010.com）解决此问题

networkSecurityConfig.xml 示例：

<network-security-config>
    <domain-config cleartextTrafficPermitted="true" >
        <domain includeSubdomains="true">enrichgw.10010.com</domain> <!-- 联通内部5G请求域名，开发者需要添加 -->
        <domain includeSubdomains="true">onekey.cmpassport.com</domain>  <!-- 移动内部请求域名，开发者需要添加 -->
    </domain-config>
</network-security-config>
  1. HTTP 配置。在 AndroidManifest.xml 里，给 Application 节点增加 usesCleartextTraffic 配置。
<application
    ...
    android:usesCleartextTraffic="true">
    ...
</application>

目前中国移动提供的个别接口为 HTTP 请求，对于全局禁用 HTTP 的项目，需要配置 HTTP 白名单。以下为运营商 HTTP 接口域名：onekey.cmpassport.com，enrichgw.10010.com。

第三方埋点配置相关​

XDSDK 默认只提供 TapDB 埋点功能（内含支付成功埋点事件），其他第三方埋点功能集成在 XDGThirdTrack 模块中，游戏可根据自身需要添加对应第三方平台埋点配置。

在 your_app > Gradle Scripts > build.gradle(Module:app) 中添加以下依赖：

// AppsFlyer
implementation 'com.appsflyer:af-android-sdk:6.5.2'
implementation 'com.android.installreferrer:installreferrer:2.2'
// Adjust
implementation 'com.adjust.sdk:adjust-android:4.24.1'
// Firebase
implementation "com.google.firebase:firebase-core:18.0.0"

Google 支付配置相关​

在 your_app > Gradle Scripts > build.gradle(Module:app) 中添加以下依赖：

implementation "com.android.billingclient:billing:4.1.0"

Firebase 推送配置​

需要使用 XDSDK 默认处理的 Firebase 推送通知功能，请按照下列步骤集成 Firebase。

  1. 添加 Firebase 配置文件。前往 Firebase 控制台，将 Firebase Android 配置文件添加到您的应用：

    • 点击下载 google-services.json 以获取 Firebase Android 配置文件（google-services.json）。
    • 将配置文件移动到应用模块（应用级）目录中。

  2. 将 google-service 插件添加到 Gradle 文件中。

    (1). 在根级（项目级）Gradle 文件（build.gradle）中添加规则，以纳入 Google 服务 Gradle 插件。此外，请确认您拥有 Google 的 Maven 代码库。

    buildscript {
        repositories {
            // Check that you have the following line (if not, add it):
            google()  // Google's Maven repository
        }

        dependencies {
            // ...
            // Add the following line:
            classpath 'com.google.gms:google-services:4.3.10'  // Google Services plugin
        }
    }

    allprojects {
        // ...
        repositories {
            // Check that you have the following line (if not, add it):
            google()  // Google's Maven repository
            // ...
        }
    }

    (2). 在您的模块（应用级）Gradle 文件中（通常是 app/build.gradle）中，应用 Google 服务 Gradle 插件：

    apply plugin: 'com.android.application'
    // Add the following line:
    apply plugin: 'com.google.gms.google-services'  // Google Services plugin

    android {
        // ...
    }

  3. 请在 your_app > Gradle Scripts > build.gradle(Module:app) 中添加 FCM 依赖：

implementation "com.google.firebase:firebase-messaging:21.1.0"

请在 AndroidManifest.xml 文件中添加 Firebase 推送相关的配置，请注意全路径匹配：

<service
        android:name="com.xd.intl.common.firebase.TDSGlobalFirebaseMessagingService"
        android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>

分享相关配置​

  1. 确保 XDConfig.json 配置文件中已配置 QQ、微信、微博的配置：
{
   ...
   "wechat": {
      "app_id": "********", // WeChat 分享/支付 配置，可选，没有可以删除配置
   },
   "qq": {
      "app_id": "*******", // QQ 分享配置，可选，没有可以删除配置
   },
   "weibo": {
      "app_id": "*******", // Weibo 分享配置，可选，没有可以删除配置
   }
}
  1. 集成分享 SDK

请参考新版分享进行集成

国内微信支付相关配置​

  1. 确保 XDConfig.json 配置文件中已配置微信的 {app_id} 参数值：
{
   ...
   "wechat": {
      "app_id": "********", // WeChat 分享/支付 配置，可选，没有可以删除配置
   }
}
  1. 集成微信支付 SDK

微信支付的 SDK 与分享功能集成的 SDK 是同一个，确保已添加微信 SDK 的依赖：

// 微信支付
implementation "com.tencent.mm.opensdk:wechat-sdk-android:6.8.0"
  1. 在应用的 AndroidManifest.xml 文件中添加如下配置，请将 {应用包名} 替换为游戏正确包名，否则无法收到微信支付回调：
   <activity-alias
        android:name="{应用包名}.wxapi.WXPayEntryActivity"
        android:exported="true"
        android:targetActivity="com.xd.intl.payment.impl.wechatpay.WXPayEntryActivity" />

Android 11 适配​

提示

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

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

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

    <!-- Facebook -->
    <package android:name="com.facebook.katana"/>
    <!-- Facebook 有端分享 -->
    <provider android:authorities="com.facebook.katana.provider.PlatformProvider"/>
    <!-- Twitter -->
    <package android:name="com.twitter.android"/>
    <!-- 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>

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" />

常见问题​

升级 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 官方文档，请按照实际需求来变更需要的属性。

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

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