广点通转化鸿蒙SDK开发指引

SDK 信息

SDK名称：广点通转化 SDK
开发者：深圳市腾讯计算机系统有限公司
版本号：0.0.1
主要功能：广告监测、广告归因、广告效果优化
合规使用说明：https://datanexus.qq.com/doc/develop/compliance/android/compliance_guide
个人信息处理规则：https://datanexus.qq.com/doc/develop/compliance/android/privacy_policy

1 前置条件

1.1 完成 SDK 接入流程文档阅读

查看 SDK 接入流程。

1.2 拥有华为开发者账号

如未有开发者账号，请进入AppGallery Connect，完成 AppID新建。

1.3 SDK 要求的系统版本

SDK 要求最低系统版本为API 12（HarmonyOS 5.0.0）。

2 接入开发

2.1 引入SDK

2.1.1 离线引入

点击 下载 最新版鸿蒙SDK最新版本har包，SDK版本号可在oh-package.json5文件中查看。

1. 将下载的 dnSDK.min.har 放到工程的指定目录下（比如 entry/libs 文件夹内）
2. 在entry模块的oh-package.json5中添加har包依赖

"dependencies": {
  "@dn-sdk/harmony": "file:./libs/dnSDK.min.har"
}

2.1.2 在线引入

在项目的跟目录下执行如下命令：

ohpm install @dn-sdk/harmony

2.2 添加 SDK 权限

在entry模块的 module.json5 中声明所需权限

  "requestPermissions": [
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      },
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.APP_TRACKING_CONSENT",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "Ability1", "Ability2"
          ],
          "when": "always"
        }
      }
    ]

在界面中向用户弹框申请APP_TRACKING_CONSENT权限授权

onPageShow(): void {
    let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
    let context: Context = getContext(this) as common.UIAbilityContext;
    atManager.requestPermissionsFromUser(context, ['ohos.permission.APP_TRACKING_CONSENT'])
      .then((data: PermissionRequestResult) => {
        console.log("PermissionRequestResult：", JSON.stringify(data))

      }).catch((error: BusinessError) => {
      console.error("error：", error)
    });
  }

权限	说明	是否必须
ohos.permission.INTERNET	允许使用Internet网络	必选
ohos.permission.GET_NETWORK_INFO	允许应用获取数据网络信息	必选
ohos.permission.APP_TRACKING_CONSENT	允许应用获取OAID	可选

2.3 初始化SDK

请在用户同意隐私政策后再初始化SDK，初始化接口中仅会执行SDK初始化，不会进行任何信息收集。只有完成SDK初始化后，SDK其他接口才可以使用。以下是在Ability的onCreate方法中初始化示例：

import { dnSDK } from '@dn-sdk/harmony';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {

    dnSDK.init({
      context: this.context,// context上下文，必填
      user_action_set_id: 123xxxx, //数据源ID，数字，必填
      secret_key: '9c6f7ef44xxxxxx', //数据源秘钥，字符串，必填
      show_log: false, // 是否展示日志，开发期间建议打开，默认为false，选填
    });
  }
}

init 方法参数说明：

参数名	类型	说明	必填
context	Context	context 上下文	是
user_action_set_id	number	在 DataNexus 获得的行为数据源ID	是
secret_key	string	在 DataNexus 数据接入获得的行为数据源 secret_key	是
show_log	boolean	是否打印日志，建议仅在调试阶段开启	否
user_unique_id	string	业务用户ID	否

2.4 启动SDK

请在调用init方法后尽快调用start方法，否则影响设备号填充率，降低归因成功率。

dnSDK.start(); // 启动SDK，允许SDK采集个人信息

2.5 按行为清单埋点上报数据

2.5.1 logAction 示例

import { dnSDK, ActionType } from '@dn-sdk/harmony';

// 上报 【应用启动】 行为
dnSDK.logAction(ActionType.START_APP);

// 上报 【付费】 行为， 付费金额参数名 value， 单位：分
dnSDK.logAction(ActionType.PURCHASE, {value: 600});

2.5.2 logAction接口定义

init 方法参数说明：

参数名	类型	说明	必填
actionType	string	行为类型名， 系统支持的actionType： 行为枚举值	是
actionParam	Object	为行为事件添加参数	否

• 行为参数 actionParam 是【Key-Value】类型；Key只可以为String类型，只能包含字母、数字和下划线，必须以字母开头，长度不能超过255；Value可以是String/Number/Boolean/Object其中一种，当Value为Object时，它的元素只能为String/Number/Boolean中的一种。

• 广告主在上报时需要做自定义去重时可以在 ActionParam 中设置 outer_action_id 的 Key，value 为任意自定义如订单号的字符串作为自定义去重 id ，系统会根据该id进行去重。
  

分行业上报行为类型和行为参数规范

为优化广告投放效果，不同行业需上报特定的行为类型，且需携带对应行为的相关参数。详见 应用规范 。

2.5.3 预置行为

• START_APP（应用启动）
• TICKET（心跳）
• ENTER_FOREGROUND（APP进入前台）
• ENTER_BACKGROUND（APP退到后台）
• APP_QUIT（应用退出）

以上 5 种行为无需您手动上报。

2.5.4 上报结果确认

如果开启调试模式，SDK会以info级别的日志输出上报的结果，日志的TAG为[@dn-sdk/harmony v1.x.x]。以下为常见的日志输出：

• 如果数据上报失败，会有logAction failed xxxx的日志输出
• 如果数据上报成功，会有logAction success xxxx的日志输出

3 SDK 主要 API

方法名	说明
init({context: Context, user_action_set_id: Number, secret_key:String, user_unique_id: String, show_log: Boolean})	初始化方法，建议在App的入口调用一次
start	启动SDK，运行开始采集和上报数据
logAction( actionType: String, actionParam: Object)	行为上报接口，支持上报行为参数 @param actionType : 行为类型，详细描述同上 @param actionParam : 行为参数，行为参数是"Key-Value"类型，Key只可以为String类型，只能包含字母、数字和下划线，必须以字母开头，长度不能超过64，且不得以amsreserved开头（SDK内置参数将以它开头）；Value可以是String/Number/Boolean/JSONArray其中一种，当Value为JSONArray时，它的元素只能为String/Number/Boolean中的一种，且所有元素必须是同一个类型
setUserUniqueId	设置客户自定义的用id

该内容是否有帮助？