元服务集成说明

• SDK 版本需要 >= v1.0.0
• 在使用前，请先阅读 数据模型
• HarmonyOS SDK 是付费产品，如需使用，请联系商务或技术顾问
• 由于 HarmonyOS 多线程内存隔离机制的限制，HarmonyOS SDK 不支持 TaskPool 和 Worker 线程初始化或使用

适用范围

本文适用于 HarmonyOS 元服务接入神策 HarmonyOS SDK。

普通 HarmonyOS App 仍参考现有 HarmonyOS SDK 使用文档和集成文档：集成文档（HarmonyOS）

元服务需要额外关注以下差异：

• 元服务设备 ID 来源为 AAID 或 UUID，不使用普通 App ODID。
• 元服务本地事件缓存使用 Preferences，不使用普通 App RDB。
• 元服务访问数据接收域名需要在 AGC 的「基础服务 > 元服务域名管理」配置允许访问的服务器域名。

集成 SDK

选择 SDK 产物

注意：

• 元服务请使用 atomic 或 atomic-pro，不要使用普通 App 的 base 或 pro 产物。
• atomic 不支持 SAAutoTrack、SAAutoTrackType、SAExposure 等文件依赖。
• 需要全埋点或曝光时，请使用 atomic-pro Har 包

添加 SDK 依赖

按发布包选择 atomic 或 atomic-pro 对应 HAR 产物，并在工程 oh-package.json5 中声明依赖。依赖包名保持不变：

{
  "dependencies": {
    "@sensorsdata/analytics": "file:./libs/SensorsAnalyticsSDK_xxx.har"
  }
}

导入 SDK

业务代码中按统一包名导入 SDK：

import sensors from '@sensorsdata/analytics'

如果使用 atomic-pro，并且需要全埋点或曝光能力，可以按需导入下述依赖：

import sensors, {
  SAAutoTrack,
  SAAutoTrackType,
  SAExposurePlugin
} from '@sensorsdata/analytics'

初始化 SDK

元服务初始化方式与普通 HarmonyOS App 基本一致：

import sensors from '@sensorsdata/analytics'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    sensors.init({
      context: this.context,
      // 服务器接收地址
      server_url: 'https://example.datasink.sensorsdata.cn/sa?project=default',
      // 是否显示日志
      show_log: true,
      // 开启 App 打通 H5
      app_js_bridge: true  
    })
  }
}

SDK 只会在调用了 init 后才会触发事件和上报数据，请确保 init 在合适的时机进行调用。

参数说明：

批量发送配置

元服务批量发送默认开启，通常不需要客户主动配置。元服务产物已经内置适合元服务场景的默认发送配置。

元服务与普通 App 的默认发送配置不同：

参数含义：

• max_cache_size：本地最多缓存的事件条数，元服务最终有效上限不超过 100 条。
• flush_interval：定时发送间隔，单位毫秒。
• flush_bulk_size：本地缓存事件达到该条数时触发发送。
• datasend_timeout：数据发送请求超时时间，单位毫秒。

如果确实需要覆盖默认配置，可以在初始化时传入 batch_send：

sensors.init({
  context: this.context,
  server_url: 'https://example.datasink.sensorsdata.cn/sa?project=default',
  show_log: true,
  batch_send: {
    max_cache_size: 100,
    flush_interval: 5000,
    flush_bulk_size: 10,
    datasend_timeout: 30000
  }
})

初始化后也可以动态修改部分 batch 配置。未传入的字段会继续使用当前值：

sensors.setBatchSendParams({
  flush_interval: 5000,
  flush_bulk_size: 5
})

元服务单独调整 batch 配置的主要原因：

• 元服务使用 Preferences 缓存待发送事件，缓存能力不等同于普通 App 的 RDB。
• 元服务属于轻量应用，用户可能即用即走，可用于发送数据的时间窗口通常更短。
• SDK 默认使用更短发送间隔和更小条数触发阈值，尽量降低进程结束前未上报的数据量。
• 元服务本地缓存有效上限不超过 100 条，不建议依赖元服务做长时间、大规模离线缓存。

客户通常不需要主动修改这些参数。如果确实需要调整，应按元服务实际事件量、单条事件大小和发送时机压测后再设置。

配置权限和 AGC 域名

元服务工程需要声明基础网络权限：

ohos.permission.INTERNET

ohos.permission.GET_NETWORK_INFO

ohos.permission.GET_WIFI_INFO

除本地权限外，元服务还需要在 AppGallery Connect 为当前元服务配置允许访问的数据接收域名。

配置位置：

• AppGallery Connect
• 基础服务
• 元服务域名管理
• httpRequest 合法域名

注意：

• server_url 中的数据接收域名必须加入 httpRequest 合法域名。
• SDK 数据上报使用 HTTP POST 请求，不需要为 SDK 数据上报配置 download 合法域名 或文件上传相关域名。
• 如果发送失败并提示 It is not allowed to access this domain，通常说明 AGC 未配置对应域名。

鸿蒙官方配置说明参考：https://developer.huawei.com/consumer/cn/doc/atomic-guides/agc-help-harmonyos-server-domain

SDK 基本配置

代码埋点

调用 track 上报自定义事件：

sensors.track('BuyProduct', {
  product_id: '12345',
  product_name: '商品名称',
  price: 99.9
})

事件属性命名规则与普通 HarmonyOS App 一致。建议使用有业务含义的英文属性名，避免使用 SDK 保留字段。

其他接口使用

关于 元服务的其他接口使用，参考：基础 API 介绍（HarmonyOS）

与普通 App SDK 的差异说明

整体功能

设备 ID 和匿名 ID 差异

元服务无法按普通 App 方式稳定使用 ODID，因此元服务产物使用以下策略：

1. 优先读取本地已保存的设备 ID。
2. 本地不存在时异步获取 AAID。
3. AAID 获取成功时，将 AAID 保存为设备 ID。
4. AAID 获取失败或为空时，生成 UUID 作为兜底设备 ID，并持久化保存。

因此，元服务上报事件中的设备 ID 可能为 AAID 或 UUID。UUID 兜底值会持久化，后续启动复用同一个值。

匿名 ID 仍由 SDK 统一维护，客户侧不需要因为元服务单独调整调用方式。元服务与普通 App 的主要差异在于设备 ID 的取值来源不同。

本地缓存差异

普通 App 使用 RDB 缓存事件；元服务使用 Preferences 缓存事件。

客户需要关注的差异：

• 元服务缓存能力不等同于普通 App RDB，不建议依赖元服务做长时间离线缓存。
• 元服务默认 max_cache_size = 100，最终有效上限不超过 100 条。
• 事件越多、单条事件越大，本地缓存和发送前处理的开销越明显。
• 建议客户按 100 条以内的缓存上限设计和压测。

HarmonyOS Preferences 官方说明：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-data-preferences

预置属性差异

普通 App 和元服务都会采集 HarmonyOS、应用、页面、屏幕、网络、设备型号、系统版本等公共预置属性。

元服务与普通 App 的主要差异：

• 普通 App 会采集 $manufacturer。
• 元服务不采集 $manufacturer，避免访问元服务场景下不可用或不稳定的系统字段。
• 元服务的 $device_id 来自 AAID 或 UUID，普通 App 优先使用  ODID。

常见问题

元服务是否可以使用普通 App Har 产物？

不可以。

元服务需要使用 atomic 或 atomic-pro。普通 App 产物使用 ODID、RDB 和普通 App 默认实现，不适配元服务运行环境

并且部分接口 API，在元服务环境下无法使用，出现报错

元服务数据发送失败，提示不允许访问域名，如何处理？

优先检查 AGC 域名配置，参考鸿蒙文档说明：配置服务器域名

元服务除本地声明网络权限外，还需要在 AGC「基础服务 > 元服务域名管理」的 httpRequest 合法域名 中配置实际数据接收域名，域名应与 server_url 使用的数据接收域名一致。