通用概念
Shiply 各平台 SDK 共享的核心概念。接入任何平台前先理解这些概念，可避免跨平台混淆。
凭证与标识
| 概念 | 含义 | 获取方式 | 各平台字段名 |
|---|---|---|---|
| appId | 应用唯一标识 | Shiply Web 控制台 → 项目设置 → 应用信息 | iOS/Android appId；Harmony appId |
| appKey | 应用鉴权密钥 | 同上 | appKey |
| guid / userId | 用户标识，用于按号码包/规则匹配灰度 | 业务自定义（如 uin/openid） | iOS guid；Android/Harmony userId |
| qimei / deviceId | 设备标识，用于上报与设备维度规则 | 业务注入（隐私合规，SDK 不主动获取） | iOS qimei；Android/Harmony deviceId |
隐私合规：系统版本、设备型号、设备标识等隐私信息，SDK 不主动获取，需业务方注入。这是各平台的共同约定。
环境标识
| 概念 | 含义 | 各平台字段 |
|---|---|---|
| envId | 环境数字 ID | iOS envId（默认 RDeliveryReleaseEnvId 正式环境，另有 RDEnvironmentIotRelease = 3 IoT 发布环境） |
| logicEnvironment | 逻辑环境字符串 | Harmony logicEnvironment（""=正式，"1"=测试，其他=自定义环境数字 ID） |
| environment | 资源 SDK 环境 | Windows ResHub environment（0=Release，1=Test，2=Pre(预发布)） |
iOS 配置用 envId；Harmony 用 logicEnvironment（字符串）。不要混用。资源 SDK 的 environment 与配置的 logicEnvironment 是两套字段，各自独立。
更新策略
配置 SDK 通过位掩码组合更新策略，资源 SDK 类似。
| 策略 | iOS 枚举 | Android 枚举 | 说明 |
|---|---|---|---|
| 启动时更新 | RDCONFIG_UPDATE_MODE_APP_START (1<<0) | START_UP | App 启动时拉取 |
| 定时更新 | RDCONFIG_UPDATE_MODE_SCHEDUAL (1<<1) | PERIODIC | 按间隔定时拉取 |
| 切前台更新 | RDCONFIG_UPDATE_MODE_ENTER_FOREGROUND (1<<2) | HOT_RELOAD（后台超阈值切前台） | Android 称 HOT_RELOAD |
| 网络恢复更新 | RDCONFIG_UPDATE_MODE_NETWORK_CHANGE (1<<3) | NETWORK_RECONNECT | 从无网恢复联网时拉取 |
- 默认间隔：定时更新默认 4 小时（iOS
updateDuration=14400s；AndroidupdateInterval建议大于 1 小时） - 位掩码组合：iOS
updateMode = APP_START | SCHEDUAL | NETWORK_CHANGE；AndroidupdateStrategy同理位运算
systemId（子系统区分）
systemId 区分同一 App 下不同子系统，避免配置数据混用：
| systemId | 子系统 | 说明 |
|---|---|---|
| 10001 | 配置（RDelivery 默认） | iOS/Android 默认值 |
| 10010 | 资源（ResHub） | 资源 SDK 内部使用 |
| 10021 | 热修复（Fix） | 热修复 SDK 内部使用 |
| 10016 | 鸿蒙升级 | 升级 SDK 内部硬编码 |
| 10013 | TAB 模式 | 配置 SDK 可设 |
接入配置 SDK 通常无需显式设 systemId（用默认 10001）。接入资源/升级 SDK 时由 SDK 内部处理。
拉取目标（PullTarget / target）
C++ 配置层（RDeliveryConfig.target）与资源层（ResHubAppInfo.target）共享同一概念，决定拉取范围：
| 枚举值 | C++ RDPullTarget | 含义 |
|---|---|---|
| 项目级 (0) | RDPullTargetProject | 只拉取当前项目下的配置/资源（默认值） |
| App 级 (1) | RDPullTargetApp | 拉取整个 App 维度的配置/资源 |
| 全部 (2) | RDPullTargetBoth | 项目级 + App 级都拉取 |
- iOS 对应
RDConfigServerPullTarget（Project/App/AppAndProject） - 资源 SDK 的
ResHubTarget与此同构，由reshub_rdelivery_creater映射 - 大多数场景用默认 Project 即可；需要跨项目共享配置时切 App/Both
依赖注入模式
所有平台 SDK 都支持关键组件依赖注入，并提供默认实现。这是 Shiply SDK 的核心设计：
| 组件 | 作用 | 默认实现 |
|---|---|---|
| 网络 | HTTP 请求 | iOS RDNetworkImpl(NSURLSession)；Android HttpsURLConnectionNetwork；C++ INetwork |
| 存储 | KV 缓存 | iOS RDMMKVFactoryImpl(MMKV)；Android MmkvStorageFactory；C++ RAFTKVStorageProtocol |
| 日志 | SDK 日志输出 | iOS RDLoggerImpl(NSLog)；Android SystemLog；C++ ILog |
| JSON | 模型转换 | iOS RDeliveryJsonModelImpl(YYModel) |
| RSA/AES | 加解密 | C++ IRSA/IAES（默认实现由平台注入） |
C++ 层提供
IRSA/IAES接口用于加解密注入，各平台在初始化时注入对应实现。
强烈建议注入业务日志实现：默认日志实现（NSLog/SystemLog）线上不可用，应注入业务日志组件，将 SDK 日志输出到业务日志系统，便于线上排查。这是各平台共同的最佳实践。
何时需要自定义注入：
- 接入方使用修改版 MMKV/YYModel 产生依赖冲突
- 需要自定义网络层（如走业务统一网络通道、加代理）
- 全局已初始化 MMKV，不希望 SDK 重复初始化
资源加载策略（资源 SDK 通用）
ResHub 的资源加载有三套语义，跨平台一致：
| 语义 | 方法前缀 | 行为 |
|---|---|---|
| 锁定版本(Lock) | resWithId / loadWithId | 进程内多次调用返回同一版本，适合需体验一致的场景 |
| 最新版本(Latest) | latestResWithId / loadLatestWithId | 返回本地配置中最新的资源，多次调用可能不同版本 |
| 实时最新(Realtime Latest) | loadRealtimeLatestWithId | 强制实时请求配置再取最新包，频繁调用成本高，仅对实时性要求极高的资源用 |
res/get系：同步读本地，不发网络请求load系：异步，可能触发网络拉取loadLatest返回的是"本地配置中的最新"，与平台最新可能有延迟；要实时最新用loadRealtimeLatest
自定义属性（custom_properties）
custom_properties 是 RequestFullRemoteData 调用的关键参数，用于按自定义属性匹配灰度规则：
- 业务方在拉取全量数据时传入
custom_properties（键值对），服务端根据属性值匹配对应的灰度规则，下发不同的配置/资源 - 典型属性：用户等级（vip_level）、地域（region）、AB 实验分组等
- 不传等价于不参与自定义属性匹配，仅按默认维度（userId/deviceId 等）匹配
- 各平台实现：iOS
RDeliverySDKSettings.customProperties；AndroidRDeliverySetting.customProperties；Harmonycustom_properties
配置缺省值
配置读取时，远端不存在 key / 未拉到 / Web 未设置值时返回 defaultValue：
- 带
defaultValue参数：返回 defaultValue - 不带：返回对应空值（对象 nil、int 0 等）