Sharetrace HarmonyOS SDK

Sharetrace HarmonyOS SDK 为 HarmonyOS 应用提供安装归因与链接唤醒参数解析能力。接入后，应用可获取用户安装时携带的渠道和自定义参数，并在通过 Sharetrace 链接启动时取得对应的唤醒参数。

集成 SDK

在工程根目录执行以下命令安装：

ohpm install @sharetrace/sdk

应用配置

在宿主应用的 src/main/module.json5 中配置 SDK 所需权限和 App Key：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      },
      {
        "name": "ohos.permission.GET_BUNDLE_INFO"
      }
    ],
    "metadata": [
      {
        "name": "com.sharetrace.APP_KEY",
        "value": "<你的 App Key>"
      }
    ]
  }
}

功能集成

初始化 SDK

在 UIAbility.onCreate 中尽早初始化 SDK。使用 module.json5 中的 App Key 时：

import { Sharetrace } from '@sharetrace/sdk';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want): void {
    Sharetrace.init(this.context);
  }
}

也可以跳过 metadata 配置，在初始化时直接传入 App Key：

Sharetrace.init(this.context, '<你的 App Key>');

每次调用获取安装参数或解析唤醒参数前，都应确保已完成初始化。

获取安装参数

安装参数用于识别用户安装应用时携带的渠道信息和自定义数据。建议在 SDK 初始化完成后调用。

Promise 方式

import { Sharetrace } from '@sharetrace/sdk';

const data = await Sharetrace.getInstallTrace();
console.info(`paramsData=${data.paramsData}`);
console.info(`channel=${data.channel}`);

回调方式

Sharetrace.getInstallTrace({
  onInstall: (data) => {
    console.info(`paramsData=${data.paramsData}`);
    console.info(`channel=${data.channel}`);
  },
  onError: (code, message) => {
    console.error(`获取安装参数失败：${code}，${message}`);
  }
});

一键拉起

配置 URL Scheme

要接收 Sharetrace 唤醒链接，请在应用入口 UIAbility 的 skills 中注册后台为该应用生成的 URL Scheme 或 App Linking 域名。链接会以 Want 的 uri 传入应用。下面是 URL Scheme 的示例：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "skills": [
          {
            "actions": [
              "ohos.want.action.viewData"
            ],
            "entities": [
              "entity.system.browsable"
            ],
            "uris": [
              {
                "scheme": "st<你的 App Key>"
              }
            ]
          }
        ]
      }
    ]
  }
}

集成 App Linking

使用 HarmonyOS App Linking 前，请完成以下配置：

1. 登录 AppGallery Connect，进入目标应用，选择 增长 > App Linking > 应用链接，启用服务并完成 URL 前缀配置。
2. 从 Sharetrace 管理后台获取该应用的 App Linking 域名。
3. 在入口 Ability 的 skills 中新增 https 链接配置，将 host 替换为实际域名，并启用 domainVerify：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "skills": [
          {
            "actions": [
              "ohos.want.action.viewData"
            ],
            "entities": [
              "entity.system.browsable"
            ],
            "uris": [
              {
                "scheme": "https",
                "host": "<你的 App Linking 域名>"
              }
            ],
            "domainVerify": true
          }
        ]
      }
    ]
  }
}

host 仅填写域名，不包含 https://。完成配置并重新安装应用后，可使用 Sharetrace 生成的 App Linking 进行测试。

代码示例

当应用由 Sharetrace 链接唤醒时，将系统传入的 Want 交给 SDK 解析。冷启动在 onCreate 中处理，已启动应用则在 onNewWant 中处理。

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { Sharetrace } from '@sharetrace/sdk';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want): void {
    Sharetrace.init(this.context);
    void this.handleWakeUp(want);
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    void this.handleWakeUp(want);
  }

  private async handleWakeUp(want: Want): Promise<void> {
    const data = await Sharetrace.getWakeUpTrace(want);
    console.info(`paramsData=${data.paramsData}`);
    console.info(`channel=${data.channel}`);
  }
}

如需使用回调方式：

Sharetrace.getWakeUpTrace(want, {
  onWakeUp: (data) => {
    console.info(`paramsData=${data.paramsData}`);
    console.info(`channel=${data.channel}`);
  }
});

如果传入的 Want 不是当前 App Key 对应的 Sharetrace 链接，Promise 会返回字段为空的 AppData；回调方式不会触发 onWakeUp。

返回数据

安装参数和唤醒参数均以 AppData 返回：

字段	类型	说明
paramsData	string	后台配置或链接携带的自定义参数。
channel	string	渠道标识。

未获取到参数时，字段值为空字符串。