更新唤起开发指南

信息

本文档只适用于国内版本，海外版本请参考 文档

权限说明

Unity

该模块依赖权限如下：

权限	使用目的	权限申请时机
网络权限	用于正常网络访问	用户首次使用该功能时会申请权限
安装 APK 权限	用于安装 Tap 客户端	用户首次使用该功能时会申请权限

Android Java

该模块依赖权限如下：

权限	使用目的	权限申请时机
网络权限	用于正常网络访问	用户首次使用该功能时会申请权限
安装 APK 权限	用于安装 Tap 客户端	用户首次使用该功能时会申请权限

同时该模块也会访问设备已安装的 Tap 客户端信息，所以接入 SDK 后将在应用 AndroidManifest.xml 中添加如下配置：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
<queries>
        <package android:name="com.taptap" />
        <package android:name="com.taptap.global" />
</queries>

Android Kotlin

该模块依赖权限如下：

权限	使用目的	权限申请时机
网络权限	用于正常网络访问	用户首次使用该功能时会申请权限
安装 APK 权限	用于安装 Tap 客户端	用户首次使用该功能时会申请权限

同时该模块也会访问设备已安装的 Tap 客户端信息，所以接入 SDK 后将在应用 AndroidManifest.xml 中添加如下配置：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
<queries>
        <package android:name="com.taptap" />
        <package android:name="com.taptap.global" />
</queries>

集成前准备

使用更新唤起功能前提需要通过 TapTap 开发者中心 > 商店 > 游戏资料 > 商店资料 中已经上传 APK， 发布设置为 立即上线 并通过 审核（开发者包如果暂时不想对外，发布状态选 敬请期待 或者 预约）。

SDK 获取

Unity

接入外部依赖

SDK 内部使用了部分第三方库，开发者接入时需先确保 SDK 外部依赖库已正常接入，具体设置如下：

1. SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.1"

2. SDK 使用 com.google.external-dependency-manager 管理 Android、iOS 依赖，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

{
   "dependencies": {
      "com.google.external-dependency-manager": "1.2.179"
   },
   "scopedRegistries": [
      {
         "name": "package.openupm.com",
         "url": "https://package.openupm.com",
         "scopes": [
            "com.google.external-dependency-manager"
         ]
      }
  ]
}

添加 SDK 依赖

SDK 支持 Unity Package Manager 及本地文件导入两种集成方式，开发者根据需求选择其中一种即可，推荐使用远程依赖。

远程依赖

SDK 支持通过 NPMJS 及 GitHub 两种方式，开发者选择其中一种即可。

1. NPMJS 接入

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
    undefined
    "com.taptap.sdk.core":"4.5.0",
    "com.taptap.sdk.update":"4.5.0",
}

但需要注意的是，需在 Packages/manifest.json 中 dependencies 同级下声明 scopedRegistries：

"scopedRegistries":[
  {
    "name": "NPMJS",
    "url": "https://registry.npmjs.org/",
    "scopes": ["com.taptap"]
  }
]

2. GitHub 接入

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
   "com.taptap.sdk.core":"https://github.com/taptap/TapSDKCore-Unity.git#4.5.0",
   "com.taptap.sdk.update":"https://github.com/taptap/TapSDKUpdate-Unity.git#4.5.0", 
 }

在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。

本地文件导入

1. 在 下载页 下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：

   • TapTapSDK_Core.unitypackage TapTapSDK 核心模块，必选。
   • TapTapSDK_Update.unitypackage TapTapSDK 更新唤起模块，必选。

2. 如果当前项目已集成 Newtonsoft.Json 依赖，则忽略该步骤，否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件，并将下载的文件后缀从.nupkg 修改为 .zip，同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 Assets 的 Plugins 目录下，另外为了避免导出 IL2CPP 平台时删除必要数据，需在 Assets 目录下创建 link.xml 文件（如果已有该文件，则添加如下内容），其内容如下：

<linker>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
  </assembly>
</linker>

Android Java

1. 项目根目录的 build.gradle 添加仓库地址:

allprojects {
    repositories {
        google()
        mavenCentral()
   }
}

2. app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:4.5.0'
    implementation 'com.taptap.sdk:tap-update:4.5.0'
}

Android Kotlin

1. 项目根目录的 build.gradle 添加仓库地址:

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

2. app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:4.5.0'
    implementation 'com.taptap.sdk:tap-update:4.5.0'
}

初始化

TapSDK 初始化

Unity

TapTapSdkOptions 详细参数见 入门指南#快速开始

using TapSDK.Core;
using TapSDK.Compliance;

// 核心配置 详细参数见 [入门指南#快速开始]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// TapSDK 初始化
TapTapSDK.Init(coreOptions);

Android Java

TapTapSdkOptions 详细参数见 入门指南#快速开始

import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;

/* 必选配置 */
// 开发者中心对应 Client ID
String clientId = "";
// 开发者中心对应 Client Token
String clientToken = "";
// 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
boolean enableLog = BuildConfig.DEBUG;

TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
        clientId, // 游戏 Client ID
        clientToken, // 游戏 Client Token
        TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
tapSdkOptions.setEnableLog(enableLog);
// 初始化 TapSDK
TapTapSdk.init(context, tapSdkOptions);

Android Kotlin

TapTapSdkOptions 详细参数见 入门指南#快速开始

import com.taptap.sdk.core.TapTapSdk
import com.taptap.sdk.core.TapTapSdkOptions
import com.taptap.sdk.core.TapTapRegion
import com.taptap.sdk.core.TapTapLanguage

TapTapSdk.init(
    context = context,
    sdkOptions = TapTapSdkOptions(
        clientId = clientId,
        clientToken = clientToken,
        region = TapTapRegion.CN,
        preferredLanguage = TapTapLanguage.ZH_HANS,
        enableLog = false
    ),
)

开始更新

提示

TapSDK 如果检查当前设备未安装 TapTap 客户端，首先会弹窗询问用户「是否需要使用 TapTap 更新」，当点击「取消」按钮时取消更新的回调方法才会执行。

开发者需自行维护版本校验接口，以便在新版本发布时触发 TapTapUpdate#UpdateGame 接口。这一流程将有效提升用户体验。

Unity

using TapSDK.Update

TapTapUpdate.UpdateGame(() => {
    // 唤醒更新收到[取消]回调
});

Android Java

由于更新唤起 UI 依赖于开发者设置的 Activity 实例，所以为了避免因 Activity 发生重建导致更新唤起功能不可用，开发者应确保在屏幕旋转、配置修改时当前 Activity 不会发生重建，具体设置方式参考 限制 activity 重新创建

import com.taptap.sdk.update.TapTapUpdate;
import com.taptap.sdk.update.TapTapUpdateCallback;

TapTapUpdate.updateGame(activity, new TapTapUpdateCallback() {
    @Override
    public void onCancel() {
        // 更新取消
    }
});

Android Kotlin

由于更新唤起 UI 依赖于开发者设置的 Activity 实例，所以为了避免因 Activity 发生重建导致更新唤起功能不可用，开发者应确保在屏幕旋转、配置修改时当前 Activity 不会发生重建，具体设置方式参考 限制 activity 重新创建

import com.taptap.sdk.update.TapTapUpdate
import com.taptap.sdk.update.TapTapUpdateCallback

TapTapUpdate.updateGame(
    activity = this,
    callback = object : TapTapUpdateCallback {

        override fun onCancel() {

            Toast.makeText(this@DemoUpdateActivity, "取消更新", Toast.LENGTH_SHORT)
                .show()
        }
    }
)

测试

为了保证上线后，游戏对于用户是否正常使用更新唤起功能，请务必按照以下说明完成自测。

上传 APK

新应用需要上传测试的 APK 至开发者中心，并通过审核。已上架的游戏，需确保更新资料版本中的 APK 包名和已上架的 APK 包名保持一致。

应用上线

针对已上架的游戏，开发者需确保更新资料版本中的包名和已上架的游戏包名保持一致，否则会导致玩家因包名不一致而更新失败。

针对新游戏，开发者需要在 TapTap 上线一个包含 APK 包并且通过审核（用于平台获取游戏包名，包名需与后续更新的包名保持一致）的商店资料版本，如果 APK 包当前无法对外，可将发布状态设置为「敬请期待」或「预约」。

开始测试

触发更新唤起功能后正常状态是可以唤起应用在 TapTap 商店的详情页面。