SDK 集成指南
使用提示
本文是 JPush HarmonyOS SDK 标准的集成指南文档。用以指导 SDK 的使用方法,默认读者已经熟悉 DevEco Studio 的基本使用方法,以及具有一定的 HarmonyOS 编程知识基础。
本篇指南匹配的 JPush HarmonyOS SDK 版本为:1.0.0 及以后版本。
- 极光推送 文档网站 上,有极光推送相关的所有指南、API、教程等全部的文档。包括本文档的更新版本,都会及时地发布到该网站上。
产品功能说明
极光推送(JPush)是一个端到端的推送服务,使得服务器端消息能够及时地推送到终端用户手机上,让开发者积极地保持与用户的连接,从而提高用户活跃度、提高应用的留存率。极光推送客户端支持 Android,iOS,HarmonyOS,QuickApp 多个平台。
本 HarmonyOS SDK 方便开发者基于 JPush 来快捷地为 HarmonyOS App 增加推送功能。
主要功能
- 保持与服务器的长连接,以便消息能够即时推送到达客户端
- 接收通知,并向开发者 App 传递相关信息
主要特点
- 客户端维持连接占用资源少、耗电低
- SDK 丰富的接口,可定制通知栏提示样式
- 服务器大容量、稳定
集成方式
集成压缩包下载链接:前往下载
jpush-hmos-x.x.x-release.zip 集成压缩包内容
jpush-hmos-x.x.x-release.har
- 极光开发者服务的核心包。
doc
- 文档
entry
- 是一个 hmos demo 项目代码,通过这个演示了 JPush SDK 的基本用法,可以用来做参考。
har 文件集成
- 解压缩 jpush-hmos-x.x.x-release.zip 集成压缩包。
- 复制 jpush-hmos-x.x.x-release.har 到你的工程的 entry/hars/ 目录下。(hars这个目录可以自定义)
说明:关联jpush-hmos-x.x.x-release.har,如,你复制 har 到 entry/hars/ 目录下,那么在 entry 模块下的 oh-package.json5 文件添加
"dependencies": {
"jg_harmony_har": "./hars/jpush-hmos-x.x.x-release.har" //这里的路径是你存放jpush-hmos-x.x.x-release.har的位置
}
配置 hmos平台信息
想要推送功能,需要配置 HarmonyOS 平台信息
主要步骤为:
- 在hmos平台获取到client_id
- 在hmos平台开通推送服务
- 在本地工程配置client_id
- 配置签署
说明1:
在本地工程配置 client_id,在 entry 模块下的 module.json5 文件添加
"module": { "metadata": [ { "name": "client_id", "value": "你的id" } ] }"module": { "metadata": [ { "name": "client_id", "value": "你的id" } ] }
此代码块在浮窗中显示说明2:
在本地工程配置签署,如图
配置 极光平台信息
想要推送功能,还需要配置极光平台信息
主要步骤为:
- 在极光平台创建 app,有两个信息包名和 appKey
说明1:
在本地工程配置包名,方式, 在 AppScope 工程下的 app.json5 文件添加
{ "app": { "bundleName": "你的包名", } }{ "app": { "bundleName": "你的包名", } }
此代码块在浮窗中显示说明2:
在本地工程配置appKey,代码配置 如:
export default class MyAbilityStage extends AbilityStage { onCreate() { JPushInterface.setAppKey("你的appKey") //在init之前调用 } }export default class MyAbilityStage extends AbilityStage { onCreate() { JPushInterface.setAppKey("你的appKey") //在init之前调用 } }
此代码块在浮窗中显示说明3:
在本地工程配置接收回调信息, 代码配置 如:
export default class MyAbilityStage extends AbilityStage { onCreate() { JPushInterface.setCallBackMsg(继承CallBackMsg的实体类) //接收回调信息,在init之前调用 } }export default class MyAbilityStage extends AbilityStage { onCreate() { JPushInterface.setCallBackMsg(继承CallBackMsg的实体类) //接收回调信息,在init之前调用 } }
此代码块在浮窗中显示
配置通知跳转页
通知支持跳转到指定页面
主要步骤为:
- 要配置 uris,目前主要通过uri来匹配页面,推送时 url=你的scheme://你的host/你的port/你的path
- actions 一定要配置,没有可以配置空字符串
{
"exported": true,
"skills": [
{
"actions": [""], //actions一定要配置,没有可以配置空字符串
"uris": [
{
"scheme": "你的scheme",
"host": "你的host",
"port": "你的port",
"path": "你的path"
}
]
}
]
}
申请打开通知开关
如果没有打开通知开关,将收不到通知
主要步骤为:
- 在首页申请
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
notificationManager.requestEnableNotification().then(() => {
hilog.info(0x0000, TAG, '%{public}s', `requestEnableNotification success`);
}).catch((err: Base.BusinessError) => {
hilog.error(0x0000, TAG, '%{public}s', `requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);
});
}
}
启用推送业务功能
主要步骤为:
- 在 init 之前要先设置 appKey
- 在 init 之前要先设置接收回调信息类
export default class MyAbilityStage extends AbilityStage {
onCreate() {
JPushInterface.setCallBackMsg(继承CallBackMsg的实体类)//接收回调信息//在init之前调用
JPushInterface.setAppKey("你的appKey")//在init之前调用
JPushInterface.init(this.context.getApplicationContext())
}
}
配置权限
可选,为了更精准推送,申请结束后再调用 init 启用推送业务功能接口
主要步骤为:
- 配置文件权限声明
- 向用户申请授权,申请结束后再调用 init 启用推送业务功能接口
说明1:
配置文件权限声明, 在 entry 模块下的 src/main/module.json5 文件添加
{ "module": { "requestPermissions": [ { "name": "ohos.permission.APP_TRACKING_CONSENT", "reason": "$string:reason", "usedScene": { "abilities": [ "EntryAbility" //一般要用首页 ], "when": "always" } } ] } }{ "module": { "requestPermissions": [ { "name": "ohos.permission.APP_TRACKING_CONSENT", "reason": "$string:reason", "usedScene": { "abilities": [ "EntryAbility" //一般要用首页 ], "when": "always" } } ] } }
此代码块在浮窗中显示说明2:
向用户申请授权,在首页 EntryAbility 中申请,然后再启用推送业务功能,如:
const permissions: Array<Permissions> = ['ohos.permission.APP_TRACKING_CONSENT']; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { let context:Context = this.context; let atManager:abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); atManager.requestPermissionsFromUser(context, permissions).then((data: PermissionRequestResult) => { // 授权成功 //然后启用推送业务功能 JPushInterface.init(this.context.getApplicationContext()) }).catch((err: BusinessError) => { //然后启用推送业务功能 JPushInterface.init(this.context.getApplicationContext()) }) }const permissions: Array<Permissions> = ['ohos.permission.APP_TRACKING_CONSENT']; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { let context:Context = this.context; let atManager:abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); atManager.requestPermissionsFromUser(context, permissions).then((data: PermissionRequestResult) => { // 授权成功 //然后启用推送业务功能 JPushInterface.init(this.context.getApplicationContext()) }).catch((err: BusinessError) => { //然后启用推送业务功能 JPushInterface.init(this.context.getApplicationContext()) }) }
此代码块在浮窗中显示
进阶功能
获取 Registration ID 交互建议
由于极光推送所有形式的推送最后都会转化为对 Registration ID 推送,因此排查客户问题的时候需要提供 Registration ID。为了方便线上客户准确提供信息,减少沟通成本,我们建议您完成 SDK 集成后,在 App 的【关于】、【意见反馈】、【我的】等比较不常用的 UI 中展示客户的 Registration ID 。
示例代码:
JPushInterface.getRegistrationID();
其他功能
请参考:
技术支持
当出现问题时:
- 你可以到极光社区搜索类似问题
- 给我们的 support 发邮件 support@jiguang.cn
为了更快速的解决问题,在寻求帮助时,请提供下列信息:
- 你需要咨询的产品是 JPush,是否同时使用了极光其他的产品
- 你所调用的是什么 API,所传参数,完整的报错信息,出现异常的时间点
- 如果收不到消息,提供应用的 Appkey,消息的 Message ID,设备的 registration ID 信息
- 如果是 SDK 问题请提供对应的 SDK 版本和完整的日志记录,日志信息请使用 TXT 文件上传
- 出现异常的设备是 HarmonyOS ,列出具体的机型和系统