1. 版本更新说明

2. SDK简介

SDK名称：资源后台下载SDK
开发者：北京瓦力网络科技有限公司
版本号：1.1.0
主要功能：为接入本SDK的开发者提供资源后台下载能力，开发者可自定义资源下载时段，小米侧将在玩家设备闲置时触发资源包任务检测，并后台拉起游戏以完成资源包静默下载，玩家进入游戏后可省去下载等待时间。据往期功能验证，本能力可显著提升玩家启动→登录转化率，在优化玩家体验的同时提升游戏业务表现。

3.接入前准备

请阅读游戏正式上架流程介绍，并确认游戏已上架小米平台。当前仅支持已正式上架的联运游戏包体使用本能力，请勿在未上架游戏包体内接入和使用本SDK。
注：当前仅支持服务端接口发起资源包后台下载任务，后续将在开放平台提供可配置的前端页面，敬请期待。

4.开发环境

• JDK 1.8及以上
• 安装AndroidStudio 3.6.1及以上
  
• minSdkVersion 19及以上
• targetSdkVersion 34（推荐）
• compileSdkVersion 34（推荐）
• Gradle 5.6.4及以上（推荐）

• 测试设备
  
• 使用国内版小米手机

5.接入流程

5.1 集成SDK

1.最新版本

2. maven依赖

配置Maven仓库地址
Android Studio的代码库配置在Gradle插件7.0以下版本、7.0及以上版本有所不同。请根据您当前的Gradle插件版本，选择对应的配置过程。
Gradle插件版本在项目的“gradle-wrapper.properties ”中查看

7.0以下版本

• 打开Android Studio项目级“build.gradle”文件。
• 在“buildscript > dependencies”中配置AndroidGradle插件版本不低于3.6.0。
• 在“allprojects > repositories”中配置小米安全检测SDK的Maven仓地址。

buildscript {  
    dependencies {  
        //确保该版本不低于3.6.0  
        classpath 'com.android.tools.build:gradle:3.6.3'  
         …  
    }  
}  
allprojects {  
    repositories {  
        配置小米的Maven仓库地址...  
        maven {  
            url "https://repos.xiaomi.com/maven"  
            credentials {  
                username 'mi-gamesdk'  
                password 'AKCp8mYeLuhuaGj6bK1XK7t2w4CsPuGwg6GpQdZ9cat7K59y5sD7Tx3dHjJcFrBGj3TQ4vi7g'  
            }  
        }  
    }  
}

• 在“gradle-wrapper.properties ”中确保Gradle版本不低于5.6.4。

distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.4-all.zip

7.0及以上版本

配置小米游戏的Maven仓地址至settings.gradle中。
注意区分项目使用的settings.gradle和settings.gradle.kts
settings.gradle 配置示例

dependencyResolutionManagement { 
    ... 
    repositories { 
        ... 
        //增加小米SDK的Maven仓库地址 
        maven { 
            url "https://repos.xiaomi.com/maven" 
            credentials { 
                username 'mi-gamesdk' 
                password 'AKCp8mYeLuhuaGj6bK1XK7t2w4CsPuGwg6GpQdZ9cat7K59y5sD7Tx3dHjJcFrBGj3TQ4vi7g' 
            } 
        } 
    } 
} 

settings.gradle.kts 配置示例

dependencyResolutionManagement { 
    ... 
    repositories { 
        ... 
        //增加小米SDK的Maven仓库地址
        maven {
            url = uri("https://repos.xiaomi.com/maven")
            credentials {
                username = "mi-gamesdk"
                password = "AKCp8mYeLuhuaGj6bK1XK7t2w4CsPuGwg6GpQdZ9cat7K59y5sD7Tx3dHjJcFrBGj3TQ4vi7g"
            }
        } 
    } 
} 

3.添加编译依赖

打开应用级的“build.gradle”文件。
在“dependencies”中添加如下编译依赖

dependencies {   
    implementation "com.xiaomi.ecosys:preDownload:1.1.0"
}

5.2 业务流程

5.2.1 整体流程

5.2.2 主流程-资源预下载任务创建

5.2.3 主流程-资源预下载（游戏进程内下载）

5.2.4 Demo参考

名称：demo.zip
地址：https://kpan.mioffice.cn/webfolder/ext/MqdII9H0NFz%24uVm31GQvyw%40%40?n=0.9005830943882296
密码：ab12

5.3 客户端接口

5.3.1 接口说明

接口类：com.xiaomi.ecosys.gameservice.ability.predownload.PreDownloadManager

5.3.1.1 核心接口

5.3.1.2 可选接口

5.3.1.3 关键结构体

5.3.2 调用示例

5.3.2.1 初始化接口

游戏进程启动时同步调用，传入资源预下载关键接口的实现

//进程初始化
public class GameApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        ...
        if (ctaAgreed) {
            ...
            PreDownloadManager.getInstance().init(context, new PreloadCallbackImpl(context));
            ...
        }
        ...
    }
    
}

5.3.2.1.1 资源下载触发回调接口实现

public class PreloadCallbackImpl implements PreDownloadCallback {
    private Context mContext;
    public PreloadCallbackImpl(Context context) {
        if (context == null) {
            return;
        }
        mContext = context.getApplicationContext();
    }

    @Override
    public int onPreDownloadBegin(String key, ResourceData resourceData) {
        //请求游戏服务端
        //...

        if (resourceNeedDownload) {
            //查询资源是否已部分下载
            
            if (taskId != -1L) {
                //恢复下载（断点续传）
                int result = DownloadManagerImpl.getInstance().resumeIfNeed(key, taskId);
                return result;
            } else {
                //发起下载
                
                File file = getDownloadDestFile(key);

                taskId = DownloadManagerImpl.getInstance().safeEnqueue(key, resourceData.getDownloadUrl(), file);
                if (taskId != -1L) {
                    //发起下载成功 保存下载ID
                    return 0;
                } else {
                    //发起下载失败
                    return PreDownloadConstants.ERROR_CODE_DOWNLOAD_BEGIN_FAIL;
                }
            }
        } else {
            return PreDownloadConstants.ERROR_CODE_CHECK_RESOURCE_INVALID;
        }
    }

    @Override
    public int onPreDownloadPause(String key) {
        //下载暂停
        
        long taskId = sp.getLong(key, -1L);
        if (taskId != -1L) {
            boolean pause = DownloadManagerImpl.getInstance().pause(key, taskId);
            return pause ? 0 : PreDownloadConstants.ERROR_CODE_PAUSE_FAIL;
        }
        return PreDownloadConstants.ERROR_CODE_NO_NEED_PAUSE;
    }

    @Override
    public void onPreDownloadStop() {
        //停止资源下载
        DownloadManagerImpl.getInstance().stopAll();
    }


    @Override
    public PreDownloadResourceCheckResult onPreDownloadCheck(String key, ResourceData resourceData) {
        //系统托管下载（暂不支持）
        return null;
    }

    private File getDownloadDestFile(String fileName) {
        String child = "xxxxxx" + File.separator + fileName;
        return new File(mContext.getCacheDir(), child);
    }
}

5.3.2.2 资源下载状态变化通知

游戏进程内预下载场景通知系统侧下载状态变更

public class DownloadManagerImpl implements RefreshListener {
    
    ,,,
    
    @Override
    public void onRefresh(@NonNull ProgressInfo progressInfo) {
        switch (progressInfo.getStatus()) {
            case Status.PAUSED:
                PreDownloadManager.getInstance().downloadStatusChanged(key, PreDownloadManager.DownloadStatus.PAUSED);
                break;
            case Status.SUCCESSFUL:
                PreDownloadManager.getInstance().downloadStatusChanged(key, PreDownloadManager.DownloadStatus.COMPLETED);
                break;
            case Status.FAILED:
                PreDownloadManager.getInstance().downloadStatusChanged(key, PreDownloadManager.DownloadStatus.FAILED);
                break;
            case Status.DOWNLOADING:
                PreDownloadManager.getInstance().downloadStatusChanged(key, PreDownloadManager.DownloadStatus.DOWNLOADING);
                break;
        }
    }
    ...

}

5.3.2.3 查询预下载功能开关状态

获取当前用户是否开启本游戏的资源预下载功能开关，游戏内可展示

PreDownloadManager.getInstance().getPreDownloadSwitchStatus(this, new SwitchStatusCallback() {
    @Override
    public void onFail(int errorCode, String errorMsg) {
        if (errorCode == PreDownloadConstants.ERROR_CODE_IPC_CONNECT_ERROR) {
            //当前ROM版本暂不支持

        }
    }

    @Override
    public void onSwitchStatusResult(int code) {
        if (code == 1) {
            //功能开关状态开启
        } else {
            //功能开关状态关闭
        }
    }
});

5.3.2.4 引导用户开启预下载功能

游戏内可提供入口，引导用户开启资源预下载功能，用户点击后调用该接口

PreDownloadManager.getInstance().showPreDownloadGuide(this, new ShowGuideCallback() {
    @Override
    public void onShowGuideResult(int code) {
        if (code == 1) {
            //正常拉起弹窗

        } else if (code == 2) {
            //开关已开启，无需重复调用

        } else if (code ==  3){
            //用户已拒绝开启

        } else {
            //暂不支持

        }
    }

    @Override
    public void onFail(int errorCode, String errorMsg) {
        if (errorCode == PreDownloadConstants.ERROR_CODE_IPC_CONNECT_ERROR) {
            //当前ROM版本暂不支持

        }
    }
});

5.3.3 SDK错误码

定义类 com.xiaomi.ecosys.gameservice.ability.predownload.constants.PreDownloadConstants

• 游戏校验错误码

• 通用错误码

5.4 服务端接口（可选）

5.4.1 前置：获取Access Token

1.功能说明

此接口用于从小米开发者服务平台获取开发者级Access Token，用于接口能力的接入。
2.接口说明

3.请求参数

• Header：无
• Body：

• 响应参数

4. 调用示例

package com.xiaomi.xxx;

import okhttp3.FormBody;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

import java.util.Objects;

/**
 *
 * 本范例代码，可以通过修改参数，运行main函数，查看接口效果
 * 以下是本范例代码需要的maven依赖配置
 <dependency>
 <groupId>com.squareup.okhttp3</groupId>
 <artifactId>okhttp</artifactId>
 <version>4.9.1</version>
 </dependency>
 */
public class Example {
    /**
     * 鉴权接口域名
     */
    private static final String DOMAIN = "https://api.developer.xiaomi.com";

    /**
     * 推送普通apk Url前缀
     */
    private static final String CLIENT_TOKEN = DOMAIN + "/openservice-api/oauth2/developer_token";

    /**
     * 获取token，需要开发者已开通对应业务功能
     *
     * @param grant_type 授权类型，填写 client_credential
     * @param client_id 开发者ID
     * @param client_secret 应用密钥，米侧提供：AppSecret
     * @param scope 授权范围，参见具体接口文档
     * @return client_token
     */
    public String getClientToken(String grant_type, String client_id, String client_secret, String scope) {
        OkHttpClient httpClient = new OkHttpClient();
        FormBody.Builder formBodyBuilder = new FormBody.Builder();
        formBodyBuilder.add("grant_type", grant_type);
        formBodyBuilder.add("client_id", client_id);
        formBodyBuilder.add("client_secret", client_secret);
        formBodyBuilder.add("scope", scope);

        try {
            RequestBody requestBody = formBodyBuilder.build();

            Request request = new Request.Builder().url(CLIENT_TOKEN).post(requestBody).build();
            Response response = httpClient.newCall(request).execute();
            return Objects.requireNonNull(response.body()).string();
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return "";
    }

    public static void main(String[] args) throws Exception {
        Example example = new Example();
        // 查询client_token
        String info = example.getClientToken("client_credentials","xxxx", "xxxxxxxx","300001");
        System.out.println("token [" + info + "]");
    }
}

curl -X POST 'http://staging-api.developer.miui.com/openservice-api/oauth2/developer_token' 
-H 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'grant_type=client_credentials' 
--data-urlencode 'client_id=xxxx' 
--data-urlencode 'client_secret=xxxxxxxx' 
--data-urlencode 'scope=300001'

5.返回示例

{
    "access_token": "eyJhb***iwg",
    "expires_in": 7200,
    "token_type": "Bearer" 
}

6.错误码

5.4.2 接口信息

请求参数：

• Header:

• Body：业务传参。
• 公共传参获取方式：
  应用id（appid）获取：

小米id（userId）获取：

5.4.2.1 资源包任务创建提审接口

• 请求方式：POST
• 请求路径：

/add_submit

• 接口约束
  
• 创建正式任务的任务时间区间不可重叠（测试任务无该限制）
• 若提交任务后，想提交重复任务时间区间的任务，必须删除（非下线）老任务，才可正常提交

• 请求参数

• 响应参数

• 调用示例

curl -X POST 'https://api.developer.xiaomi.com/openservice-api/rest/game-api/out/preDownload/v2/add_submit' -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36' -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJhb***iwg' -H 'clientId: xxxx' -d '{
  //小米id
  "userId": "xxxxxxx",
  //应用id
  "appId": "xxxxxxxxxxxxx",
  //是否测试任务
  "isTest": 0,
  //token
  "token": "test",
  //资源预下载任务名称
  "taskName": "资源包后台下载接入测试",
  //资源下发方式
  "distributeMethod": 1,
  //任务类型
  "taskType": 1,
  //是否限制版本
  "versionLimit": 1,
  //最低版本
  "versionMin": "453",
  //最高版本
  "versionMax": "453",
  //任务开始时间
  "startTime": "2025-12-25 01:01",
  //任务结束时间
  "endTime": "2025-12-27 23:20",
  //CDN可用时间
  "cdnAvailableTimeList": [
    {    
      //CDN开始时间
      "begin_time": "01:01",
      //CDN结束时间
      "end_time": "11:11"
    }
  ],
  //资源包版本号
  "resourcePackVersionCode": "111111",
  //扩展字段
  "ext": {
    //预下载包名
    "fileName": "测试资源包名",
    //分配的渠道
    "channel": "对应渠道",
    //拉起游戏进程建议的时间间隔
    "interval": 30,
    //拉起优先级
    "priorityLevel": 1,
    //key
    "api_key": "key",
    //签名
    "api_sign": "sign"
  }
}' -k

• 返回示例

{
  //业务状态码
  "code": 200,
  //信息
  "msg": "success",
  //任务流水号
  "data": "3xxxxxxx-xxxxxxx-xx",
  //时间戳
  "timestamp": 1767862736041,
  //请求链路id
  "traceId": "xxxxxxxxxxxxxx"
}

5.4.2.2 终止任务接口

• 请求方式：POST
• 请求路径：
  

  /offline

• 接口约束：
  

  只有发布中（人审核通过，且当前时间为任务下发时间区间内）的任务才可以终止

• 请求参数

• 响应参数

• 调用示例

curl -X POST 'http://staging-api.developer.miui.com/openservice-api/rest/game-api/out/preDownload/v2/offline' -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36' -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJhb***iwg' -H 'clientId: xxxx' -d '{
  //小米id
  "userId": "xxxxxxx",
  //应用id
  "appId": "xxxxxxxxxxxxx",
  //任务流水号
  "taskNum": "3xxxxxxx-xxxxxxx-xx",
  //终止原因
  "reason": "test"
}' -k

• 返回示例

{
  //业务状态码
  "code": 200,
  //信息
  "msg": "success",
  "data": null,
  //时间戳
  "timestamp": 1767579114868,
  //请求链路id
  "traceId": "xxxxxxxxxxxxxx"
}

5.4.3 回调接口

• 功能介绍
  

  该接口由接入方提供，米侧会在资源包任务状态变化（审核通过/驳回/下线）的情况进行状态信息同步回调。

• 请求方式：POST
• 请求路径：
  

  由接入方提供

• 请求参数
• Header:

• Body：

• 响应参数

• 调用示例

curl -X POST 'https://xxxxx/callback' -H 'Content-Type: application/json' -d '{
  //状态变更原因
  "msg": "xxxxxxxx",
  //任务流水号
  "taskNum": "5a112667-14niljW-9e",
  //接口签名校验
  "api_sign": "eb3f344356e66985fe17cfb8ba38af24c1c2941e",
  //任务状态
  "status": 7
}'

• 返回示例

{
  //业务状态码
  "code": 200,
  //信息
  "msg": "success"
}