Harmony SDK

一、功能概述

应用的文案或者运营策略更新经常需要通过发版解决，为了减少开发者频繁更新应用版本，热力引擎推出参数下发功能，通过参数下发可以随时远程调整应用中的参数值实现应用内容更新

二、导入SDK

有两种方式导入SDK

注意：在线参数SDK版本需和热力引擎主SDK版本保持一致。

方式一：通过鸿蒙仓库导入SDK

进入工程entry目录，执行以下命令：

ohpm install @solarengine/remoteconfig

方式二：通过本地har包导入SDK

2.1 下载SDK

SDK 下载地址：SolarEngine Harmony RC Plugin

2.2 执行ohpm install命令

将下载的 SolarEngineRemotex.x.x.har 放入工程libs目录，再执行以下命令：

//your_project_path/entry/libs/SolarEngineRemoteConfigx.x.x.har   //har包的本地路径
ohpm install ./your_project_path/entry/libs/SolarEngineRemoteConfigx.x.x.har  

三、配置runtimeOnly参数

在entry目录下的build-profile.json5文件的buildOption下添加以下配置：

  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "packages": [
          "@solarengine/remoteconfig"
          ,"@solarengine/core"
        ]
      }
    }
  }

四、初始化

由于参数下发SDK属于热力引擎SDK的一个插件，所以参数下发SDK的初始化是依赖于热力引擎SDK的。开发者可以通过热力引擎SDK的方法来控制是否启用参数下发SDK，并使用参数下发SDK的相关功能。

方法示例

  let solarEngineConfig = new SolarEngineConfig();
  let rcConfig: RemoteConfig = new RemoteConfig();
  rcConfig.enable = true;
  rcConfig.mergeType = MergeType.CACHE;
  
  let customIDProperties: Record<string, string | number | boolean> = {};
  customIDProperties["key1"] = "value1";
  let userIdEventProperties: Record<string, string | number | boolean> = {};
  userIdEventProperties["key1"] = "value1";
  let userIdUserProperties: Record<string, string | number | boolean> = {};
  userIdUserProperties["key1"] = "value1";
  
  rcConfig.customIDProperties = customIDProperties;
  rcConfig.customIDEventProperties = userIdEventProperties;
  rcConfig.customIDUserProperties = userIdUserProperties;
  solarEngineConfig.remoteConfig = rcConfig;
  SolarEngineManager.initialize(getContext(), "your_appkey", solarEngineConfig);

RemoteConfig参数介绍

mergeType(合并策略)介绍

注：开发者使用参数下发SDK需要通过API预置一份默认配置配置到App中，SDK使用该默认配置用来兜底

五、设置默认配置

参数下发SDK需要开发者预置一份默认配置到用户app中，方便参数下发SDK使用此默认配置进行兜底操作。

方法示例

public async setDefaultConfigs(configs:Array<ConfigItem>)

参数相关

调用示例

import { booleanItem,
  ConfigItem,
  jsonItem, numberItem,
  RemoteConfigManager,
  safeBoxingConfigItem, stringItem } from '@solarengine/remoteconfig';

let defaultConfig: Array<ConfigItem> = new Array();
let item1 = stringItem("key_string", "stringText1");
let item2 = numberItem("key_number", 2);
let item3 = booleanItem("key_boolean", true);

let record: Record<string, Object | Record<string, Object>> = {
"name": "John",
"age": 30,
"city": "test",
"hulk inner obj1": {
  "inner name1": "hulk1",
  "inner age1": 332,
}
};
let record2: Record<string, Object> = {
"name2": "John2",
"age2": 30,
"city2": "test2",
};
let record3: Record<string, Object> = {
"name3": 2
}
record2["inner3 inner obj"] = record3;
record["hulk inner obj"] = record2;

let item4 = jsonItem("key_json", record);

safeBoxingConfigItem(defaultConfig, item1);
safeBoxingConfigItem(defaultConfig, item2);
safeBoxingConfigItem(defaultConfig, item3);
safeBoxingConfigItem(defaultConfig, item4);

RemoteConfigManager.sharedInstance().setDefaultConfigs(defaultConfig);

六、设置事件自定义属性

开发者可以为事件设置自定义属性，参数下发SDK在请求服务端配置时会带上该属性，用于服务端参数匹配。

方法示例

public setRemoteConfigEventProperties(configs:Record<string,string|number|boolean>)

参数相关

调用示例

import { RemoteConfigManager } from '@solarengine/remoteconfig';

let eventProperties: Record<string, string | number | boolean> = {};
eventProperties["key1"] = "stringText2";
eventProperties["key2"] = 2;
eventProperties["key3"] = true;

RemoteConfigManager.sharedInstance().setRemoteConfigEventProperties(eventProperties);

注：给事件设置的自定义属性不支持开发者传入"_"下划线开头的key值，SDK会默认丢弃该条属性

七、设置用户自定义属性

开发者可以为用户设置自定义属性，参数下发SDK在请求服务端配置时会带上该属性，用于服务端参数匹配

方法示例

public setRemoteConfigUserProperties(configs:Record<string,string|number|boolean>)

参数相关

调用示例

import { RemoteConfigManager } from '@solarengine/remoteconfig'; 

let userProperties: Record<string, string | number | boolean> = {};
userProperties["user_key1"] = "stringText3";
userProperties["user_key2"] = 3;
userProperties["user_key3"] = true;
RemoteConfigManager.sharedInstance().setRemoteConfigUserProperties(userProperties);

注：给用户设置的自定义属性不支持开发者传入"_"下划线开头的key值，SDK会默认丢弃该条属性

八、获取参数下发配置

参数下发SDK获取参数下发配置分为两种情况，一种是同步获取方法，通过此方法开发者可以直接获取返回结果。另一种是异步获取方法，返回结果需要等待回调完成才可以获取

注：通过同步或异步方式获取参数时，sdk 会触发上报用户命中试验的事件，所以获取参数的时机应该在用户到达试验场景时读取（获取参数代表用户到达试验场景，用户命中该参数对应的试验），请勿提前读取参数

1.同步获取参数下发配置

方法示例

public async fastFetchRemoteConfig(key:string,completion:(configItem: ConfigItem|null) => void)

返回值: void

参数相关

调用示例

import { ConfigItem, RemoteConfigManager } from '@solarengine/remoteconfig';

let key = "key_string";
RemoteConfigManager.sharedInstance().fastFetchRemoteConfig(key, (configItem: ConfigItem | null) => {
  if (configItem == null) {
    console.log("RemoteConfig", "key_string type is:  null");
  } else {
    console.log("RemoteConfig", "key_string type is: " + typeof configItem?.value + " value: " + configItem?.value);
  }
})

2. 异步获取参数下发配置

方法示例

public async asyncFetchRemoteConfig(key:string,completion:(configItem: ConfigItem|null) => void)

返回值: void

参数相关

调用示例

import { ConfigItem, RemoteConfigManager } from '@solarengine/remoteconfig';

let key = "key_string";
RemoteConfigManager.sharedInstance().asyncFetchRemoteConfig(key,(configItem:ConfigItem|null) =>{
  console.log("RemoteConfig","asyncFetchRemoteConfig  open callback, key: " + key+ " value: " + configItem?.value);
})

3. 同步获取所有参数下发配置

方法示例

public async fastAllFetchRemoteConfig(completion:(configItemsMap: Map<string,ConfigItem>) => void)

返回值: void

参数相关

调用示例

import { ConfigItem, RemoteConfigManager } from '@solarengine/remoteconfig'

RemoteConfigManager.sharedInstance().fastAllFetchRemoteConfig((configItemsMap: Map<string, ConfigItem>) => {

  console.log("RemoteConfig", "fastFetchConfig size: " + configItemsMap.size);
  let item: ConfigItem = configItemsMap.get("key_string") as ConfigItem;
  let stringValue = item.value;
  if (stringValue != null) {
    console.log("RemoteConfig", "stringValue type is: " + typeof stringValue + " value: " + stringValue);
  }

  item = configItemsMap.get("key_boolean") as ConfigItem;
  let booleanValue = item.value;
  if (booleanValue != null) {
    console.log("RemoteConfig", "booleanValue type is: " + typeof booleanValue + " value: " + booleanValue);
  }

  item = configItemsMap.get("key_number") as ConfigItem;
  let numberValue = item.value;
  if (numberValue != null) {
    console.log("RemoteConfig", "numberValue type is: " + typeof numberValue + " value: " + numberValue);
  }

  item = configItemsMap.get("key_json") as ConfigItem;
  let obj: Record<string, Object> = item.value as Record<string, Object>;
  if (obj != null) {
    console.log("RemoteConfig", "key_json type is: " + typeof obj + " value: " + JSON.stringify(obj));
  }
})

4. 异步获取所有参数下发配置

方法示例

public async asyncAllFetchRemoteConfig(completion:(configItemsMap: Map<string,ConfigItem>) => void)

返回值: void

参数相关

调用示例

import { ConfigItem, RemoteConfigManager } from "@solarengine/remoteconfig";

RemoteConfigManager.sharedInstance().asyncAllFetchRemoteConfig((configItemsMap: Map<string, ConfigItem>) => {

  console.log("RemoteConfig","asyncAllFetchRemoteConfig open callback");
  let item: ConfigItem = configItemsMap.get("key_string") as ConfigItem;
  let stringValue = item.value;
  if (stringValue != null) {
    console.log("RemoteConfig", "stringValue type is: " + typeof stringValue + " value: " + stringValue);
  }

  item = configItemsMap.get("key_boolean") as ConfigItem;
  let booleanValue = item.value;
  if (booleanValue != null) {
    console.log("RemoteConfig", "booleanValue type is: " + typeof booleanValue + " value: " + booleanValue);
  }

  item = configItemsMap.get("key_number") as ConfigItem;
  let numberValue = item.value;
  if (numberValue != null) {
    console.log("RemoteConfig", "numberValue type is: " + typeof numberValue + " value: " + numberValue);
  }

  item = configItemsMap.get("key_json") as ConfigItem;
  let jsonValue = item.value;

  if (jsonValue != null) {
    console.log("RemoteConfig", "jsonValue type is: " + typeof jsonValue + " value: " + jsonValue);
  }
})

九、混淆配置

如果打包时需要增加混淆，请将下方代码增加到配置中

./oh_modules/@solarengine/remoteconfig

————————————

SDK 更新记录

2025-03-12 1.1.0

• 支持参数下发功能