Shiply iOS 远程资源 SDK 集成
一、隐私安全说明
Shiply 资源发布 iOS SDK
版本：1.10.21
更新时间：2025年2月14日
SDK介绍：为移动开发者提供专业的资源分发能力，帮助开发者动态下载远程资源文件。
服务提供方：深圳市腾讯计算机系统有限公司
隐私保护规则：《Shiply资源发布SDK个人信息保护规则》
合规使用指南：《Shiply资源SDK合规使用指南》
前置概念：接入前请先阅读 通用概念，了解各平台共用的
appId/appKey/guid/qimei/target/资源加载策略 等核心概念，避免跨平台混淆。
SDK
如遇到 iOS SDK Pod Install 失败，请更新版本号：
- ShiplyPro >= 1.1.0
- ShiplyResHub >= 1.10.22-rc.5
- ShiplyRDelivery >= 1.3.6.9
二、初始化 SDK
可参考 Demo 工程（公开仓库 ）进行体验和接入。
// 1. 构建初始化参数
ResHubParam *param = [[ResHubParam alloc] init];
param.appVersion = @"1.0.0"; // 应用版本号，用于匹配资源
// 请在 qimei 填写你的设备唯一标识符（用于条件下发，测试任务加体验名单）
param.qimei = @"your_device_unique_id";
struct utsname systemInfo;
uname(&systemInfo);
NSString *deviceType = [NSString stringWithCString:systemInfo.machine encoding:NSUTF8StringEncoding];
param.deviceType = deviceType; // 设备型号，数据上报使用
param.systemVersion = [UIDevice currentDevice].systemVersion; // 系统版本号，拉取配置及数据上报使用
param.localPresetResPath = [[[NSBundle mainBundle] resourcePath] stringByAppendingPathComponent:@"res_hub"]; // 内置资源路径，如无内置资源，可不填
param.callbackOnMainThread = YES; // progress回调是否要求在主线程进行，默认为NO
// 2. 注入必选的功能模块
// 必须实现包括：网络请求、文件下载、KV存储、上报、文件处理
ResHubDependImpl *depends = [[ResHubDependImpl alloc] init];
// 网络请求和kv存储，可集成RDelivery的DefaultNetworkImpl和DefaultStorageImpl模块
depends.netImpl = [RDNetworkImpl sharedInstance];
depends.kvFactoryImpl = [RDMMKVFactoryImpl sharedInstance];
// 文件下载、上报、文件处理，可集成ResHub的Download、Beacon和File模块
depends.downloadImpl = [ResHubDownloadImpl sharedInstance];
depends.fileImpl = [ResHubFileImpl sharedInstance];
depends.yymodelImpl = [RDeliveryJsonModelImpl sharedInstance];
depends.jsonModelImpl = [RDeliveryJsonModelImpl sharedInstance];
param.depends = depends;
[[ResHubCenter sharedInstance] initSDK:param];
// 3. 创建一个hub实例
ResHub *hub = [[ResHubCenter sharedInstance] resHubWithAppId:@"xxxxxxx"
appKey:@"xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
env:@"online"]; // 正式环境"online"，默认测试环境"test"，其他环境填写环境ID
三、使用 SDK
以下所有示例可在 Demo 中体验
3.1 同步获取资源（仅获取，不会下载资源）
// 1. 同步获取最新资源（首选）
ResHubModel *model = [[self resHub] latestResWithId:[self resId]];
// 2. 同步获取本地资源（特殊场景使用，App 生命周期锁定返回一个版本）
ResHubModel *model = [[self resHub] resWithId:[self resId]];
3.2 异步获取资源（会下载资源）
// 1. 异步拉取最新资源（首选）
[[self resHub] loadLatestWithId:resId
progress:^(CGFloat progress) {
} completed:^(BOOL success, NSError * _Nullable error, ResHubModel * _Nullable resModel) {
}];
// 2. 异步拉取指定资源并加锁（特殊场景使用，App 生命周期锁定返回一个版本），优先返回本地资源，同时会自动进行网络请求更新资源
[[self resHub] loadWithId:resId
progress:^(CGFloat progress) {
} completed:^(BOOL success, NSError * _Nullable error, ResHubModel * _Nullable resModel) {
}];
3.3 批量拉取资源（会下载资源）
// 1. 批量异步拉取最新资源(首选)，一定会进行网络请求尝试获取最新包
[[self resHub] batchLoadLatestWithIds:resIds
progress:^(NSUInteger completedCount, NSUInteger totalCount, CGFloat progress) {
} completed:^(BOOL allSuccess, NSDictionary<NSString *,NSError *> * _Nullable errorMap, NSDictionary<NSString *,ResHubModel *> * _Nullable resModelMap) {
}];
// 2. 批量异步拉取资源，优先返回本地资源，同时会自动进行网络请求更新资源
[[self resHub] batchLoadWithIds:resIds
progress:^(NSUInteger completedCount, NSUInteger totalCount, CGFloat progress) {
} completed:^(BOOL allSuccess, NSDictionary<NSString *,NSError *> * _Nullable errorMap, NSDictionary<NSString *,ResHubModel *> * _Nullable resModelMap) {
}];
3.4 按场景拉取资源（会下载资源）
// 1. 通过场景(Scene)ID异步拉取多个远程最新资源(首选)
[[self resHub] batchLoadLatestWithSceneId:sceneId progress:^(NSUInteger completedCount, NSUInteger totalCount, CGFloat progress) {
} completed:^(BOOL allSuccess, NSDictionary<NSString *,NSError *> * _Nullable errorMap, NSDictionary<NSString *,ResHubModel *> * _Nullable resModelMap) {
}];
// // 通过场景(Scene)异步拉取多个资源（特殊场景使用，App 生命周期锁定返回一个版本）
[[self resHub] batchLoadWithSceneId:sceneId progress:^(NSUInteger completedCount, NSUInteger totalCount, CGFloat progress) {
} completed:^(BOOL allSuccess, NSDictionary<NSString *,NSError *> * _Nullable errorMap, NSDictionary<NSString *,ResHubModel *> * _Nullable resModelMap) {
}];
3.5 删除资源
// 1. 删除某个资源的指定版本
ResHubConfigItem *resConfig = [[ResHubConfigItem alloc] init];
resConfig.resId = resId;
resConfig.version = [resVer integerValue];
[[self resHub] deleteWithModel:resConfig];
// 2. 删除某个资源
[[self resHub] deleteWithId:resId];
// 3. 删除所有
[[self resHub] deleteAll];
3.6 获取所有配置信息（不会下载资源）
// 1. 获取所有配置信息
- (nullable NSDictionary<NSString *, ResHubConfigItem *> *)allReshubConfigDict;
// 2. 获取某个资源的配置信息
- (nullable ResHubModel *)fetchedResConfigWithId:(NSString *)resId;
四、注意事项
init不可用：必须经ResHubCenter的sharedInstance获取中心实例，再经resHubWithAppId:appKey:env:获取 App 实例。初始化调用initSDK:。initSDK:必须在主线程执行：否则可能导致初始化异常。depends是必填依赖注入：ResHubParam.depends非 nullable，未设置直接 crash。必须实现 6 个 required property：kvFactoryImpl、fileImpl、netImpl、downloadImpl、beaconImpl、yymodelImpl。- MD5 校验：
resWithId:默认校验，大资源同步读取可能耗时，可needValidate:NO关闭后异步校验isValidResFileWithModel:。 - 语义选择：体验一致用 Lock；要最新用 Latest；实时性极高才用 Realtime Latest（成本高）。
- Latest 与平台最新有延迟：
loadLatest命中配置缓存时取不到平台最新，要实时用 Realtime。 - 依赖 RDelivery：ResHub 复用 RDelivery 的网络/存储/日志组件，注入在 RDelivery 层完成。
configUpdateMode默认值：RDCONFIG_UPDATE_MODE_APP_START | RDCONFIG_UPDATE_MODE_SCHEDUAL（启动时 + 定时更新），默认定时间隔 3 小时。callbackOnMainThread默认值：NO，progress 回调默认在子线程，需要主线程回调时设为YES。
回调与监听
// 资源刷新监听
[resHub addResRefreshListener:self]; // 实现 ResHubResRefreshListener 协议
// 移除监听
[resHub removeResRefreshListener:self];
ResHubResRefreshListener 协议
@protocol ResHubResRefreshListener <NSObject>
@optional
/// 资源首次加载成功（本进程内首次）
- (void)onResFirstLoadedWithId:(NSString *)resId model:(ResHubModel *)model;
/// 资源版本或配置更新
- (void)onResRefreshed:(NSString *)resId model:(ResHubModel *)model;
/// 所有资源配置拉取完成
- (void)onResConfigInfoPullTypeAllFinished:(NSError *)error;
/// 配置被删除
- (void)onConfigDeleted:(NSString *)key;
@end
线程说明
| 项 | 线程行为 |
|---|---|
initSDK: | 必须在主线程调用 |
callbackOnMainThread (ResHubParam) | 默认 NO，progress 回调默认在子线程；设为 YES 切到主线程 |
ResHubCallbackThread 枚举 | OnMain / OnSub / DeterminedByDefault，loadLatest 等接口支持 per-call 线程控制 |
| ResHubResRefreshListener 回调 | 无线程承诺，不可假设回调在主线程 |
callbackOnMainThread仅控制 load 系列接口的 progress/completed 回调线程，不影响 ResHubResRefreshListener 回调。
配置拉取
// 手动全量拉取资源配置
[resHub updateAllConfigsWithCompleted:^(NSError * _Nullable error){}];
// 按 key 拉取配置
[resHub updateConfigWithKeys:@[@"r1"] completedBlock:^(NSArray<ResHubModel *> * _Nullable resConfigs, NSError * _Nullable error){}];
// 仅获取远程最新配置（不下载）
ResHubModel *cfg = [resHub fetchedResConfigWithId:@"my_res"];