Skip to main content

Shiply Harmony 远程资源 SDK 集成

一、隐私安全说明​

Shiply 资源发布 Harmony SDK
版本：1.0.22
更新时间：2024年12月25日
SDK介绍：为移动开发者提供专业的资源分发能力，帮助开发者动态下载远程资源文件。
服务提供方：深圳市腾讯计算机系统有限公司
接入指引：《Shiply资源发布SDK接入指引》
隐私保护规则：《Shiply资源发布SDK个人信息保护规则》
合规使用指南：《Shiply资源SDK合规使用指南》

二、Harmony SDK 简介​

Shiply Harmony 版本 SDK，支持在鸿蒙系统上进行远程配置下发、远程资源下发。

  • 支持丰富的下发条件（允许自定义条件）

  • 支持灰度发布、全量发布、定时发布

  • 支持测试、验证、发布审批等流程

  • 差量省流技术（iOS/Android 支持，鸿蒙版本后续支持）

三、 接入 Harmony SDK​​

步骤一、注册产品​

  1. 在 Shiply 平台上注册产品，平台选择 Harmony

  2. 注册完成后，可以在设置-项目设置-常规-您的产品获取 APP ID 和 APP Key

步骤二、集成SDK​

自动集成（推荐）​​

1、配置内网鸿蒙三方库，执行以下命令。(设置默认存在该三方库，则无需配置)
ohpm config set registry https://ohpm.openharmony.cn/ohpm/
提醒
设置默认原始只有鸿蒙官方三方库，如添加了其他三方库，需通过 ohpm config list 查看设置的三方库，手动将 https://ohpm.openharmony.cn/ohpm/ 追加后重新设置。
2、通过 ohpm 安装 shiply 库。

ohpm install shiply@latest
ohpm install aki // 依赖 aki

3、安装完成后可直接在arkTs中通过 import 导入引用。

手动集成​​

1、通过三方仓库或其他渠道下载 shiply.har 三方SDK包。
2、在需要集成的模块下创建 libs 目录，将 shiply.har 放入目录。
3、在模块的 oh-package.json5 文件中添加对应 dependencies ，如下所示。

"dependencies": {
    "@ohos/shiply": "file:../shiply",
    "@ohos/aki": "^1.2.6" // 按需升级版本
}

步骤三、使用资源下发能力​

初始化 SDK​

import { ResHubParam, ResHubModel, ResHubError, ResHub } from '@ohos/shiply'
let param: ResHubParam = new ResHubParam();
param.appVersion = "1.0.0";
param.deviceType = "Macbook";
param.systemVersion = "13.2.1";
param.qimei = "59521F70-C388-486B-A6A5-22B903E6DACD";
param.isDebugPackage = false; //  是否为Debug包，设置为 true 可获取到未发布的资源，默认为 false（仅用于测试，请注意不要在线上版本设置true！！！）
param.callbackOnMainThread = true;
let context = getContext(this) as common.UIAbilityContext;
let filesDir = context.filesDir;
param.resConfigStoragePath = filesDir + "/reshub/mmkv"; // 资源的配置文件存储目录
param.resStoragePath = filesDir + "/reshub/resource";   // 资源文件存储目录
let levelLogCallback = (level: number, log: string) => {
// 需要打印到你的 App 日志中！
};
// AppKey 和 AppID 请前往 Shiply 网页端获取
// 正式环境 “online”，测试环境 “test”
ResHub.initResHubCenter(param, "95b84b2e2d", "c3fb420e-d3e4-4711-90ea-4cdb7a81ac16", "online", levelLogCallback);
this.initMessage = "初始化成功";

异步拉取资源（的锁定版本）​

资源加载策略:

  1. 如果本地有该资源或对应的可用预置资源，优先读取加锁的，如果当前没有加锁，则同时加锁该资源，通过block直接返回，并异步静默更新资源

  2. 如果本地没有该资源或对应的可用预置资源，则等待网络请求资源后，锁定版本并返回
    注意：
    该方法在进程运行期间，多次调用返回的资源保证是同一个版本

    /// @param resId 资源id
    /// @param progressBlock 进度的回调
    /// @param completedBlock 完成的回调
    let progressCalback = (progress: number) => {
    }
    let completionCallback = (success: Boolean, error: ResHubError, resModel: ResHubModel) => {
    hilog.info(0x0000, 'ShiplyLog', 'resId=%{public}s md5=%{public}s', resModel.resId, resModel.md5);
    }
    ResHub.loadWithId(this.resId, progressCalback, completionCallback);

同步获取现有最新资源​

同步获取现有最新资源, 不会进行网络请求

 
资源加载策略:

  1. 如果本地没有获取过该资源，且没有对应的可用预置资源，返回nil

  2. 如果本地有该资源或对应的可用预置资源，返回最新版本的资源
    注意：

  3. 由于本地资源可能被更新，该方法多次调用返回的资源不保证是同一个版本

  4. 如果需要在进程运行期间获取特定资源时使用同一版本，可使用带版本锁定的接口

  5. 该方法默认会校验资源文件是否正确(MD5校验)，如果需要关闭，请调用latestResWithId:needValidate:方法

    /// @param resId 资源id
    let resModel: ResHubModel = ResHub.latestResWithId(this.resId, true);

异步拉取本地配置中远程最新资源​

资源加载策略:

  1. 返回自动更新配置策略下，配置中最新的资源，即使本地有可用资源，也会根据最新配置，先尝试获取最新包

  2. 如果本次更新失败，回调失败结果，并返回本地最新包

     
    注意：

  3. 由于获取的是最新资源，该方法多次调用返回的资源不保证是同一个版本

  4. 如果需要在进程运行期间获取特定资源时使用同一版本，可使用带版本锁定的接口

  5. 此处的最新包和平台的最新包不一定匹配，会有一定的延时，因为当前配置是根据自动更新策略全量拉取的，所以本次如果命中配置缓存，则不能获取到平台上的最新资源。
    如果需要拉取实时最新资源，请使用Realtime Latest相关接口

    /// @param resId 资源id
    /// @param progressBlock 进度的回调
    /// @param completedBlock 完成的回调
    let progressCalback = (progress: number) => {
    }
    let completionCallback = (success: Boolean, error: ResHubError, resModel: ResHubModel) => {
    hilog.info(0x0000, 'ShiplyLog', 'resId=%{public}s md5=%{public}s', resModel.resId, resModel.md5);
    }
    ResHub.loadLatestWithId(this.resId, progressCalback, completionCallback);

异步拉取远程实时最新资源​

资源加载策略:

  1. 保证实时返回最新资源，即使本地有可用资源，也会先请求最新配置，再根据配置获取最新包

  2. 如果本次更新失败，回调失败结果，并返回本地最新包

     
    注意：

  3. 因为该接口一定会实时请求配置，频繁调用会大幅增加配置拉取成本，因此只应该对实时性要求非常高，要求必须拉到远端最新包的资源调用该接口

  4. 对实时性要求不太高，又希望更新的资源，请调用loadLatest（异步拉取多个本地配置中 远程最新资源）接口，该接口默认冷启动后，以及每三小时定时更新配置

  5. 由于获取的是最新资源，该方法多次调用返回的资源不保证是同一个版本

  6. 如果需要在进程运行期间获取特定资源时使用同一版本，可使用带版本锁定的接口

    /// @param resId 资源id
    /// @param progressBlock 进度的回调
    /// @param completedBlock 完成的回调
    let progressCalback = (progress: number) => {
    }
    let completionCallback = (success: Boolean, error: ResHubError, resModel: ResHubModel) => {
    hilog.info(0x0000, 'ShiplyLog', 'resId=%{public}s md5=%{public}s', resModel.resId, resModel.md5);
    }
    ResHub.loadRealtimeLatestWithId(this.resId, progressCalback, completionCallback);

异步拉取资源的最新配置​

配置加载策略:

  1. 该方法仅获取配置，不下载/更新资源

  2. 结果回调返回的资源中，本地存储路径信息为空

    /// @param resId 资源id
    /// @param completedBlock 完成的回调
    let completionCallback = (success: Boolean, error: ResHubError, resModel: ResHubModel) => {
    hilog.info(0x0000, 'ShiplyLog', 'resId=%{public}s md5=%{public}s', resModel.resId, resModel.md5);
    }
    ResHub.fetchResConfigWithId(this.resId, completionCallback);

删除本地指定id的资源​

/// @param resId 资源id
ResHub.deleteWithId(this.resId);

清空本地所有资源​

ResHub.deleteAll();