搜索
分发文档
应用分发
游戏分发
电视应用分发
快应用分发
快游戏分发
服务分发
内容分发
分发文档/游戏分发/游戏运营/资源包预下载/资源包预下载接入文档
资源包预下载接入文档更新时间: 2024-06-11 16:49:13

一、业务介绍

在游戏首发和更新时,过大的资源包常常给玩家带来较差的登录体验,从而影响游戏的登录转化,过往平台侧曾与多位开发者配合使用“资源包预下载”能力,效果较为显著,平均可带来新游10pts/老游2pts以上的登录转化率提升。

“资源包预下载”功能旨在通过系统能力,在游戏首发/更新前,将游戏的资源文件提前下载到目标用户的设备中。用户在首发/更新启动游戏后,游戏客户端即可直接加载已下载完成的资源文件,从而提升玩家的登录体验,降低游戏的登录率折损。

二、快速入门

功能实现时序图

上传文件


配置上线流程

上传文件

三、配置操作指南

1. 登录小米开发者站-管理中心-对应游戏详情页-资源包预下载,向对接商务/运营申请到功能使用权限后,进行任务创建。

上传文件

2. 任务编辑页如下图所示,分为“新游首发”“游戏更新”两种任务类型,操作注意事项如下:

上传文件

  1. 任务类型对应不同的目标用户,当游戏为预约/内测状态时,仅能添加“新游首发”类型的任务,资源包将对本游戏预约用户下发,以供游戏首发时读取;当游戏为正式上架(即下载)状态时,仅能添加“游戏更新”类型的任务,资源包将对本游戏安装保有用户下发,以供游戏更新时读取。
  2. 当任务类型为“游戏更新”时,允许开发者进行目标下发版本的控制,即仅对当前安装了指定版本范围游戏客户端的用户下发资源包,以减少资源浪费。
  3. 请注意版本号格式正确填写,安卓系统下的游戏版本号为纯数字(非版本名称),例:699466(非1.0.2.1)。如填写了错误的版本号,将无法下发成功。版本号范围可不设上限或下限,对应配置项空置即可。
  4. 任务起止时间间隔最多只能设置10天,最少不能低于48小时
  5. 资源预计读取时间的开始时间不能早于任务开始时间,结束时间不能晚于任务结束时间14天(不含任务结束时间当日)
  6. 资源预计读取时间不影响游戏客户端的实际读取操作,仅供数据统计使用,请尽量准确填写
  7. 资源包成功下发后,在用户手机里最长保留时间为15天,请在任务开始时间15天内进行资源包读取
  8. 资源包上传包体单个不得超过4G,总大小不超过8G,同一任务,资源包数量不能超过6个
  9. 资源包任务在草稿状态时,可以在测试管理中添加测试人的oaid,选择该对应任务,并使用文档下发“调试操作”中的命令行来触发文件下载,并在本地设备上测试。
  10. 资源包任务点击提审后,将进入平台审核流程,审核通过后,则任务正式上线(未到上线时间的允许撤销)。请开发者谨慎操作,一定要自测资源包无问题后,才能操作提审上线。
  11. 资源包任务在发布中状态时,可以查看每日下载及读取数据,每日数据将于次日刷新展示,下载数据仅在选中的任务起止时间段内返回,读取数据仅在选中的预计读取时间段内返回。
  12. 资源包任务在发布中状态时,可以修改任务名称、任务结束时间、资源预计读取结束时间,经审核通过后生效。

四、接入接口

接入前准备

因为需要用到ContentProvider查询接口,为了数据安全,需要在接入方应用的AndroidManifest.xml中加入如下权限声明

<uses-permission android:name="com.xiaomi.gamecenter.preload.permission.PRELOAD_PROVIDER" />

查询是否支持预下载 

查询Uri:"content://com.xiaomi.gamecenter.preload/game_source?query=support" 返回Cursor列:值为2(不支持)不为2(支持) 

示例代码

private boolean checkSupport() {
try {
Cursor statusCursor = getContentResolver().query(Uri.parse("content://com.xiaomi.gamecenter.preload/game_source?query=support"), null, null, null, null);
if (statusCursor != null && statusCursor.moveToFirst()) {
return statusCursor.getInt(0) != 2;
}
} catch (Throwable t) {

}
return false;
}

获取预下载文件列表 

查询当前预下载文件信息 

查询Uri:"content://com.xiaomi.gamecenter.preload/game_source?query=list" 可以带上文件名、md5、任务Id来查询指定文件信息(可选参数,可以带一个或者都不带) 返回文件信息列表。Cursor结构

字段类型说明
fileNameString文件名
md5String文件的MD5值
fileLengthLong文件总大小
stateint0 未下载 1 正在下载 2 下载完成 3 下载失败
currentLengthLong当前文件大小
fileUriString文件Uri,可以通过此Uri打开文件 

参考代码:

Cursor fileCursor = null; 
try {
fileCursor = getContentResolver().query(
Uri.parse("content://com.xiaomi.gamecenter.preload/game_source?query=list")
.buildUpon()
.appendQueryParameter("fileName",fileName) //可选
.appendQueryParameter("md5",md5) //可选
.appendQueryParameter("taskId",taskId) //可选
.build(), null, null, null, null);
} catch (Throwable ignored){
}
if (fileCursor != null) {
int fileNameIndex = fileCursor.getColumnIndexOrThrow("fileName");
int md5Index = fileCursor.getColumnIndexOrThrow("md5");
int fileLengthIndex = fileCursor.getColumnIndexOrThrow("fileLength");
int stateIndex = fileCursor.getColumnIndexOrThrow("state");
int currentLengthIndex = fileCursor.getColumnIndexOrThrow("currentLength");
int fileUriIndex = fileCursor.getColumnIndexOrThrow("fileUri");
while (fileCursor.moveToNext()) {
//读取预下载文件信息
String fileName = fileCursor.getString(fileNameIndex);
String md5 = fileCursor.getString(md5Index);
long fileLength = fileCursor.getLong(fileLengthIndex);
int status = fileCursor.getInt(stateIndex);
long currentLength = fileCursor.getLong(currentLengthIndex);
String contentUri = fileCursor.getString(fileUriIndex);
}
}

拷贝文件至本地参考代码

InputStream inputStream = null;
FileOutputStream fos = null;
File file = new File(getExternalCacheDir(), fileName);
if (file != null) {
try {
inputStream = getContentResolver().openInputStream(Uri.parse(contentUri));
fos = new FileOutputStream(file);
byte[] b = new byte[1024];
int length;
while((length = inputStream.read(b))>0){
fos.write(b,0,length);
}
Toast.makeText(this,"copy to :"+file.getPath(), Toast.LENGTH_SHORT).show();
} catch (Exception e) {
e.printStackTrace();
} finally {
try {
if (inputStream != null) {
inputStream.close();
}
} catch (IOException e) {
e.printStackTrace();
}
try {
if (fos != null) {
fos.close();
}
} catch (IOException e) {
e.printStackTrace();
}
}
}

文件读取完毕 

文件读取完后,请务必调用下面的方法来删除缓存的资源包,释放占用的存储空间 

1.全部资源文件读取完毕 

通知SDK删除已缓存的所有资源包,读取成功时传入参数“finished=true”,读取失败时传入参数“finished=false”

默认删除所有本地资源包

try { 
getContentResolver().delete(Uri.parse("content://com.xiaomi.gamecenter.preload/game_source?finished=true"), null, null);
}catch (Throwable ignored){
}

传入参数taskId可用于指定删除指定任务的文件

try { 
getContentResolver().delete(Uri.parse("content://com.xiaomi.gamecenter.preload/game_source?finished=true")
.buildUpon()
.appendQueryParameter("taskId", taskId)
.build(), null, null);
}catch (Throwable ignored){
}

注:在每次获取预下载文件列表或删除资源包之前都需要先查询是否支持预下载

五、调试操作

1. 配置资源包任务:新建任务,上传资源包,保存任务,使任务状态为草稿状态(新增驳回,预发布撤销均等同于草稿)

上传文件

2. 设置测试设备白名单以及对应任务:列表页右上角“测试管理”,配置测试设备oaid(游戏中心app-我的-用户头像-快速点击用户头像十下),并点选想要测试的对应任务

上传文件

3. 测试手机安装商店测试包并覆盖安装商店测试包:点击文字即可下载 (密码:88xm)

4. 命令行触发调用资源预下载功能:

adb shell am startservice -n com.xiaomi.market/com.xiaomi.market.testsupport.DebugService -e cmd game_download -e download_cmd preload

可在logcat中通过tag:PreloadProvider、PreloadManager查看获取资源状态和下载状态

六、要点说明

【接入工作】只需要客户端接口对接,来获取资源包状态或者通知小米资源包获取结果。

【配置时间】在游戏热更前一周/预约首发前一周左右,开发者需要提前配置资源包预下载任务,因本功能可用带宽有限,请尽量提前时间配置,以免下发不完全。

【静默下载方式】需要用户手机处于闲时(小米平台侧判断)并且应用商店允许资源包预下载(打开率较高)的情况下才会进行资源包静默下载;新游首发任务会提供额外的主动下发链路以最大化下发效果。

【资源包版本管理】如果资源包仅对某些版本生效,开发者需要在任务中配置正确的版本范围。如果预下载资源包的上个版本前置依赖资源包用户未下载的情况,需要游戏自行下载缺失的资源包。

【环境依赖】用户设备为小米手机,且安装的应用商店版本大于等于v4.15.1

七、常见问题

如下是在资源包预下载能力测试中常见问题点,供参考:

1.查看资源文件的游戏包名必须和平台配置资源的应用包名保持一致

2.查询接口返回Cursor后的读取,建议按照接口文档中的读取文件Uri的方式读取

3.测试游戏Demo之前,需要保证应用商店先安装,注册对应的自定义权限,游戏Demo才能正常请求接口

4.当前仅支持任务式下发,每个任务中配置的资源只会针对该设备下发一次

上一篇:质量数据服务
下一篇:节点信息业务介绍
文档内容是否有帮助?
有帮助
无帮助