文档中心 登录/注册 SDK下载 个推学堂

当前位置：个推文档 > 客户端 > HarmonyOS > 集成指南

集成指南

集成指南

前言   

  • 本文档介绍DevEco Studio版本5.0 ，鸿蒙API 12，个推推送SDK集成方式
  • 本文档适用 GTSDK 版本：1.0.2.0 及以后

  • 本文默认读者已经具有基础的鸿蒙知识，以及项目工程结构如下：

    GtsdkDemo/
    |- entry/ （项目主模块）
    |    |- libs/ （第三方库,用户手动创建）
    |    |- src/ （代码目录）
    |    |- oh-package.json5（模块级oh-package.json5文件）
        |- build-profile.json5
    |- hvigorfile.ts
    |- oh-package.json5 （顶层oh-package.json5文件）
    | ......

    注：其中 “......” 表示省略其他与本教程无关的内容，以下 “......” 表示相同意义，不再重复说明。

1.重点提示

1.1开发环境配置

  • DevEco Studio版本5.0及以上，鸿蒙API 12及以上。 早期需要联系华为技术人员获取，在其指导下搭建好开发环境

2. 创建个推应用

请参考 创建应用 获取相应的AppID信息。该信息在之后的步骤配置中将会使用。

3. 本地集成

注意：当前只支持本地集成

3.1 下载配置SDK的har包

  • 通过官网下载或技术支持获取gtsdk.har

  • 在项目主模块entry下创建libs文件夹

  • 将下载好的har包gtsdk.har放到libs文件夹下

    GtsdkDemo/
  |- entry/ （项目主模块）
  |    |- libs/ （第三方库,用户手动创建）
  |                         |-GT-HM-1.0.2.0-beta.har (个推推送SDK)
    | ......

3.2 配置依赖

  1. 找到entry模块级oh-package.json5文件，依赖gtsdk.har

    GtsdkDemo/
  |- entry/ （项目主模块）
  |    |- libs/ （第三方库,用户手动创建）
  |         |- src/ （代码目录）
  |    |- oh-package.json5（模块级oh-package文件）
      | ......

  2. oh-package.json5 配置如下：

    {
"license": "",
"devDependencies": {},
"author": "",
"name": "entry",
"description": "Please describe the basic information.",
"main": "",
"version": "1.0.0",
"dependencies": {
  //依赖gtsdk.har
  "library": "file:./libs/GT-HM-1.0.2.0-beta.har"
}
}

  3. 运行指令ohpm install

  • 在控制台进入entry目录，执行ohpm install
  • 在entry目录下出现oh_modules文件夹，代表依赖成功

4. 编写集成代码

4.1初始化 SDK

  • 调用个推初始化代码：PushManager.initialize(Context context) 进行 SDK 的初始化。

    • 我们建议开发者在 EntryAbility.onCreate()` 方法中初始化个推 SDK。多次调用 SDK 初始化并无影响。
    import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import hilog from '@ohos.hilog';
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import window from '@ohos.window';
import common from '@ohos.app.ability.common';
//引入个推SDK对外接口类PushManager
import PushManager from 'library';

export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  hilog.info(0x0000, 'EntryAbility', '%{public}s', 'Ability onCreate');
   //初始化GTSDK
   PushManager.initialize({
    appId: '在个推官网注册的APPID',
    context: this.context as common.UIAbilityContext,
    onSuccess: (cid:string) => {
      hilog.debug(0x0000, "EntryAbility", '%{public}s', "个推SDK初始化成功，cid = " + cid);
    },
    onFailed: (error:string) => {
      hilog.debug(0x0000, "EntryAbility", '%{public}s', "个推SDK初始化失败，error = " + error);
    }
  })

}
}

  • 另外，为了保证推送通知更好的触达用户，降低用户对于通知开关设置的难度。

    • 我们建议在应用代码中引导用户打开允许应用通知开关。

      
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  hilog.info(0x0000, 'EntryAbility', '%{public}s', 'Ability onCreate');
  //开启应用通知开关
  notificationManager.requestEnableNotification().then(() => {
    hilog.debug(0x0000, "EntryAbility", '%{public}s', 'requestEnableNotification success');
  }).catch((err: BusinessError) => {
    hilog.debug(0x0000, "EntryAbility", '%{public}s', "error = " + err);
  })

}
}

4.2自定义接收推送服务事件

  • 在项目源码中调用PushManager.setPushCallback，用于接收 CID、透传消息以及其他推送服务事件。请参考下列代码实现各个事件回调方法：

    //引入个推SDK对外封装类
import PushManager, { GTCmdMessage, GTTransmitMessage, GTNotificationMessage } from 'library';

export default class EntryAbility extends UIAbility {

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
    PushManager.setPushCallback({
      // 接收 cid
      onReceiveClientId: (clientId：string) => {
        hilog.debug(0x0000, 'EntryAbility', '%{public}s', "clientId = " + clientId);
      },
      //接收厂商token
      onReceiveDeviceToken: (token:string) => {
        hilog.debug(0x0000, 'EntryAbility', '%{public}s', "token = " + token);
      },
      // cid 离线上线通知
      onReceiveOnlineState: (onLine:boolean) => {
        hilog.debug(0x0000, 'EntryAbility', '%{public}s', "onLine = " + onLine);
      },
      //命令相应回复
      onReceiveCommandResult: (result: GTCmdMessage) => {
        hilog.debug(0x0000, 'EntryAbility', '%{public}s', "cmd = " + JSON.stringify(result));
      },
      //sdk 收到透传消息
      onReceiveMessageData: (message: GTTransmitMessage) => {
        hilog.debug(0x0000, 'EntryAbility', '%{public}s', "message = " + JSON.stringify(message));
      },
       //通知到达回调
      onNotificationMessageArrived: (message: GTNotificationMessage)  => {
        hilog.debug(0x0000, 'EntryAbility', '%{public}s', "message = " + JSON.stringify(message));
      },
       //通知点击回调, 需要配合PushManager.setClickWant(want)使用
      onNotificationMessageClicked: (message: GTNotificationMessage) => {
        hilog.debug(0x0000, 'EntryAbility', '%{public}s', "message = " + JSON.stringify(message));
      },
    })
    }
}

4.3 上报个推在线通知点击

  • 通过个推在线渠道展示的通知类消息，待通知点击打开目的页面后，由客户必须调用PushManager.setClickWant(want)完善报表和完成后续业务，以免影响消息业务使用（重要）

    • 通知点击打开应用页面（目的页面由下发通知时决定）
    • 通知点击打开浏览器
    • .....
   //引入个推SDK对外封装类
  import PushManager, { GTCmdMessage, GTTransmitMessage, GTNotificationMessage } from 'library';

  export default class EntryAbility extends UIAbility {

    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
      hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');

          if (want && want.parameters && want.parameters['gtdata']) {
            if (JsonUtils.hasGttask(want.parameters['gtdata'])) {
                PushManager.setClickWant(want);
               hilog.info(0x0000, 'EntryAbility', 'onCreate PushManager.setClickWant');
            }
      }
    }
    onNewWant(){
          if (want && want.parameters && want.parameters['gtdata']) {
        if (JsonUtils.hasGttask(want.parameters['gtdata'])) {
                PushManager.setClickWant(want);
               hilog.info(0x0000, 'EntryAbility', 'onCreate PushManager.setClickWant');
            }
      }
    }
  }

   //上述的JsonUtils.hasGttask方法，需要您创建一个ts类来处理解析json数据，示例代码如下
    static hasGttask(gtdata: any): boolean {
    return gtdata['gttask'] !== undefined;
  }

4.4 上报透传消息的展示和点击数据

透传消息：个推只传递数据，不做任何处理，客户端接收到透传消息后需要自己去做后续动作处理，如通知栏展示、弹框等。

如果开发者自己本地将 “透传消息” 创建了通知栏展示，建议执行相应动作后，将 ”展示“ 和 ”点击“ 回执上报给个推。可帮助您完善推送数据、且支持更精确的运营场景。

以下是上报 展示和点击 数据的示例代码，taskid 和 messageid 字段从 GTTransmitMessage 获取：

PushManager.setPushCallback({
    /**
     *sdk 收到透传消息
     */
     onReceiveMessageData: (message: GTTransmitMessage) => {
       hilog.debug(0x0000, 'EntryAbility', '%{public}s', "message = " + JSON.stringify(message));

       //上报自定义回执使用，PushManager.sendFeedbackMessage
       let taskid = message.taskId
       let messageid = message.messageId
     }
 })


/**
 * 上报个推透传消息的展示回执。如果透传消息本地创建通知栏消息“展示”了，则调用此方法上报。
 */     
let gtactionid = 60001;//gtactionid传入60001表示个推渠道消息展示了
let result = PushManager.sendFeedbackMessage(taskid,messageid,gtactionid);

/**
 * 上报个推透传消息的点击回执。如果透传消息本地创建通知栏消息“点击”了，则调用此方法上报。
 */     
let gtactionid = 60002;//gtactionid传入60002表示个推渠道消息点击了
let result = PushManager.sendFeedbackMessage(taskid,messageid,gtactionid);

4.5 鸿蒙厂商离线通知消息报表补全

  • 如果服务端使用 通知+want 方式推送消息。需要在 want/parameters 中添加"gttask":""参数，添加后个推会自动在 [want] 里拼接 taskid 和 actionid，app 端接收到参数以后，上报埋点。
    app 端接收到拼接之后的 want示例 如下:

{"deviceId":"","bundleName":"com.getui.push","abilityName":"TestAbility","uri":"https://www.test.com:8080/push/test","action":"com.test.action","parameters":{"name":"Getui","age":12,"gtdata":{"gtaction": "60090","gttask": "RASS_0514_5e49aa9c73ac8a8881dd95d3c27216af"}}}

由于鸿蒙没有点击数报表返回，所以需要您在客户端埋点 上报点击数据。点击厂商通知以后，在触发的Ability的 onCreate() 和 onNewWant方法里面接收相关参数，上报离线厂商消息的点击数据。

客户端示例代码:

   //引入个推SDK对外封装类
  import PushManager, { GTCmdMessage, GTTransmitMessage, GTNotificationMessage } from 'library';

  export default class EntryAbility extends UIAbility {

    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
      hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');

          if (want && want.parameters && want.parameters['gtdata']) {
            if (JsonUtils.hasGttask(want.parameters['gtdata'])) {
               JsonUtils.feedback(want.parameters['gtdata'], this.context);
               hilog.info(0x0000, 'EntryAbility', 'onCreate PushManager feedback');
            }
      }
    }
    onNewWant(){
          if (want && want.parameters && want.parameters['gtdata']) {
        if (JsonUtils.hasGttask(want.parameters['gtdata'])) {
                JsonUtils.feedback(want.parameters['gtdata'], this.context);
               hilog.info(0x0000, 'EntryAbility', 'onCreate PushManager feedback');
            }
      }
    }
  }

   //上述的JsonUtils.hasGttask、JsonUtils.feedback方法，需要您创建一个ts类来处理解析json数据、封装、上报埋点，示例代码如下

    static hasGttask(gtdata: any): boolean {
           return gtdata['gttask'] !== undefined;
    }

   static async feedback(gtdata: any, con: common.UIAbilityContext) {
    try {
      let taskid = gtdata['gttask'];
      let uuid = util.generateRandomUUID(true).replace("-", "");
      let clientid = PushManager.getClientId();
      let md5str =  await md5Str(taskid + uuid + clientid, 'hex'); //md5方法需要您编写，返回hex类型
      let mesageId = md5str.substring(0, 16);
      console.log('mesageId = ' + mesageId);
      PushManager.initialize({
        appId: '您应用的appid', //填写您应用的appid
        context: con,
        onSuccess:
        (cid)=> {
          // this.cid = '推送ID： ' + cid;
        },
        onFailed: (err)=> {

        }
      })
      PushManager.sendFeedbackMessage(taskid, mesageId, gtdata['gtaction']);
    } catch (e) {
      console.log('err = ' + JSON.stringify(e));
    }
  }

5.Ability页面skills标签配置规范

建议按照如下说明进行配置，以免鸿蒙系统包管理模块找不到对应的Ability，影响消息展示、页面跳转等。

  1. module.json5文件中的skills标签下的可以存在多个对象， 每一个skill对应一种能力；
  2. Push的action跳转可以单独写一个：
    "skills":[
{
"actions": [
  "action.push"
]
}
]

  3. Push的uris跳转可以这么设置：

    "skills":[
{
"actions": [
  ""
],
"uris": [
  {
    "scheme": "https",
    "port": "8080",
    "host": "com.xx.xx.push",
    "path": "notify_detai"
  }
]
}
]

  4. Push既有action跳转，又有uris跳转，也需要分开写{action的skill}，{uri的skill}

    "skills":[
{
"actions": [
  "action.push"
]
},
{
"actions": [
  ""
],
"uris": [
  {
    "scheme": "https",
    "port": "8080",
    "host": "com.xx.xxx.push",
    "path": "notify_detai"
  }
]
}
]

6.Ability页面中接收自定义参数

//此处是您需要打开的应用Ability页面的onCreate方法
 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    //接收自定义参数
    if (want && want.parameters && want.parameters['自定义key']) {
      let key = want.parameters['自定义key']
      hilog.info(0x0000, 'TestAbility-onCreate', '%{public}s', '接收鸿蒙自定义参数:'+key)
    }
  }

//或者在onNewWant接收
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    //接收自定义参数
    if (want && want.parameters && want.parameters['自定义key']) {
      let key = want.parameters['自定义key']
      hilog.info(0x0000, 'TestAbility-onNewWant', '%{public}s', '接收鸿蒙自定义参数:'+key)
    }
  }

7.厂商开通

略，详情参考《鸿蒙系统华为推送厂商开通&集成指南》

8. 验证推送

  1. 查看调试日志信息

    • EntryAbility.onCreate()` 方法中初始化个推 SDK

      //引入个推SDK对外接口类PushManager
import PushManager from 'library';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'EntryAbility', '%{public}s', 'Ability onCreate');

    //初始化GTSDK
    PushManager.initialize({
      appId: '在个推官网注册的APPID',
      context: this.context as common.UIAbilityContext,
      onSuccess: cid => {
        hilog.debug(0x0000, "EntryAbility", '%{public}s', "个推SDK初始化成功，cid = " + cid);
      },
      onFailed: error => {
        hilog.debug(0x0000, "EntryAbility", '%{public}s', "个推SDK初始化失败，error = " + error);
      }
    })
  }
}

    • 连接手机或启动鸿蒙模拟器，编译运行你的工程，查看 logcat 信息。如果看到 个推SDK初始化成功，cid = = xxx 日志输出，则说明 SDK 初始化成功。

        D     个推SDK初始化成功，cid = c3dbb50ec68c3c45b86559c47eb859d9
  D     clientId = c3dbb50ec68c3c45b86559c47eb859d9
  D     token =
  D     onLine = true

  1. 测试推送功能

    • 登录 个推 ，点击相应应用创建推送，进入待测试应用的推送通知界面：

      img_getui_mobile_android_androidstudio_0

    • 依次填写通知标题和通知内容，点击发送按钮即可向该推送应用名下所有 CID 推送通知消息。具体推送操作方法详见：创建推送通知，下拉通知栏，如果手机或模拟器收到消息，那么恭喜您，个推 SDK 接入测试已经成功完成！

在这篇文章中： 前言    1.重点提示 2. 创建个推应用 3. 本地集成 4. 编写集成代码 5.Ability页面skills标签配置规范 6.Ability页面中接收自定义参数 7.厂商开通 8. 验证推送
开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询