目录
4.5.3 AppGallery Connect在线推送通知消息
1 简介
Push Kit（推送服务）是华为提供的消息推送平台，建立了从云端到终端的消息推送通道。所有HarmonyOS应用可通过集成Push Kit，实现向应用实时推送消息，使消息易见，构筑良好的用户关系，提升用户的感知度和活跃度。
1.1 产品优势
- 稳定的消息发送通道
Push Kit通过提供系统级长链接，即使应用进程不在也能实时推送消息。
- 丰富的消息呈现样式
支持文本样式、通知大图标样式、多行文本样式、角标样式等多种消息展示方式，满足您多样化、个性化的消息发送需求。
- 灵活的场景化消息
开发者可以根据实际场景灵活接入场景化消息。如通过应用内通话消息实现音视频通话，通过通知扩展消息实现语音播报，通过后台消息实现配置更新等。
1.2 推送消息提示场景
推送消息指的是应用通过Push Kit发送的，在华为终端设备上显示的通知消息。显示场景主要包括通知中心、锁屏、横幅、桌面图标角标与通知图标。
有关各场景的详细说明请参见通知提示场景。
1.3 推送消息类型
Push Kit支持以下消息类型：
| 消息类型 | 说明 |
|---|---|
| 通知消息由Push Kit直接下发，在终端设备的通知中心、锁屏、横幅等展示，用户点击后拉起应用。 您可以设置通知消息样式来吸引用户。 常用场景：行程提醒、账号动态等。 | |
| 授权订阅消息是一种特殊的通知消息，Push Kit为开发者提供了一次性授权订阅能力，当且仅当用户同意订阅后，开发者可向用户推送对应的消息，从而实现服务闭环。 常用场景：订阅内容。 | |
| 当用户终端收到您发送的通知扩展消息后，Push Kit会拉起应用的子进程，您可以在子进程中自行处理业务。 常用场景：语音播报。 | |
| 通过卡片刷新服务，在合适场景向用户即时推送卡片内容，提升用户的感知度和活跃度。 常用场景：打车出行、快递动态等。 | |
| 消息到达终端后，如果应用进程在运行，将消息内容传给应用，如果不在运行则缓存消息，等待应用启动后再传给应用，不显示通知。 常用场景：用于告知应用更新配置参数。 | |
| 应用服务端向Push Kit服务端发送创建或更新实况窗的请求，创建实况窗，或更新实况窗内容。 常用场景：赛事比分更新，出行打车状态更新等。 | |
| 支持应用实现网络音视频通话的能力。 常用场景：网络音视频通话。 |
1.4 业务流程
使用Push Kit的主要业务流程如下：
- 应用调用Push Kit，获取Push Token。
- 应用成功获取Token后，建议及时上报Token等信息至应用服务端。
- 应用服务端向华为Push Kit服务端（Push Cloud）发送推送消息请求。应用的通知开关默认关闭，发送请求前，请先请求通知授权，详情请参见请求通知授权。
- Push Kit服务端下发消息到Push Kit。
- Push Kit进行消息处理。
1.5 约束和限制
1.5.1 影响送达率的因素说明
Push Kit致力于提供安全可靠的系统级消息发送通道，保障消息成功送达。影响消息送达率的因素：
- 终端设备是否在线。如果设备离线，Push Kit会缓存消息，待设备上线后，再将消息推送给设备。
- 终端设备上应用是否被卸载。
- 终端设备的网络状况是否稳定。
- 终端设备的安全控制策略。
1.5.2 推送消息的及时性
在终端设备网络条件良好且不拥堵情况下，Push Kit将使用智能推送策略以减少推送消息的时延。
说明
为降低夜间推送对用户的干扰，推送服务在每日凌晨 0:00 至 6:00 期间实施夜间管控策略。
在此期间，若设备处于非活跃状态（如熄屏），推送服务将缓存该时段内发送的消息。管控时段结束后，推送服务会将缓存的消息重发至端侧。
1.5.3 推送消息长度与数量限制
- 消息体最大不能超过4096Bytes（不包括Token）。
- 消息发送量，测试消息（参考消息体pushOptions.testMessage）每个项目限制所有应用共享1000条/天，正式消息区分场景有不同的配额，参考消息频控说明。
1.5.4 网络受限说明
如果终端设备连接的网络配置了防火墙，也会影响消息的送达率，请检查以下端口号是否被禁用。
端口号：
- 5223
- 423
1.5.5 支持的国家/地区
Push Kit当前仅支持中国境内（不包含中国香港、中国澳门、中国台湾）。
1.5.6 模拟器版本说明
Push Kit当前仅支持ARM版本的模拟器。详细请参考应用服务模拟器列表。
1.6 与相关Kit的关系
- Push Kit建立了从云端到终端的消息推送通道，支持开发者从云侧实时推送消息。如果开发者希望从本地推送通知，可通过Notification Kit（用户通知服务）创建本地通知。
- 开发者推送卡片刷新消息时，需要通过Form Kit（卡片开发服务）提前创建应用的服务卡片。
- 开发者推送实况窗更新消息时，需要通过Live View Kit（实况窗服务）提前创建本地实况窗。
- 开发者推送应用内通话消息时，通过Call Service Kit（通话服务）管理应用通话能力。
2 开发准备
2.1 开通推送服务
2.1.1 操作步骤
- 登录AppGallery Connect网站，选择“我的项目”。
- 在项目列表中找到您的项目，在项目下的应用列表中选择需要配置推送服务参数的应用。
- 在左侧导航栏选择“增长 > 推送服务”，点击“立即开通”，在弹出的提示框中点击“确定”。至此，您已可以向应用推送通知消息。
说明
推送服务权益为项目级，若您已有开通过推送服务的项目，当您在项目中添加新的应用时，无需再次开通推送服务。
- 若项目当前未配置数据处理位置，请在提示中点击“确定”，会弹出设置数据处理位置的弹窗。完成数据处理位置的设置，点击“确定”。
注意
推送服务当前仅支持中国境内（不包含中国香港、中国澳门、中国台湾），数据处理地固定为中国，请您选择数据处理位置为中国。
- 在“项目设置 > API管理”中，确认已经开启“推送服务”开放能力，并完成手动签名。
说明
若使用原有的Profile文件，请确保在申请Profile文件之前已开启“推送服务”，否则开启后需要重新申请调试Profile文件，并重新配置签名信息。
- （可选）您还可以通过“增长 > 推送服务 > 配置”，在“配置”页签开通或关闭您的项目级和应用级的消息回执，开通应用级的通知消息自分类权益。
说明
- 若项目级的消息回执权益开通，应用级的消息回执权益未开通，则该应用消息回执权益取项目级的。
- 若项目级的消息回执权益开通，应用级的消息回执权益开通，则该应用消息回执权益取应用级的。
2.1.2（可选）设置数据处理位置
您可以在“项目设置 > 数据处理位置”页面设置或更新数据处理位置，步骤如下：
- 登录AppGallery Connect，选择“我的项目”。
- 在项目列表中点击您需要设置数据处理位置的项目。
- 进入“项目设置 > 数据处理位置”页面，点击“管理”。
- 按需设置数据处理位置。
- 设置完成后，点击“保存”。
注意
如果设置的数据处理位置与您的服务器位置不一致，或者设置的数据处理位置与应用所服务的用户所在地不一致，都会导致推送消息无法下发。
2.2 申请推送场景化消息权益
2.2.1 场景化消息权益简介
Push Kit支持多种场景化消息类型，其中部分场景化消息类型需要您申请特殊权益才能正常发送。具体见下表：
| 场景化消息权益名称 | 功能描述 | 开放申请场景 |
|---|---|---|
| 通知消息自分类权益 | 允许开发者自行对通知消息进行分类，以改善终端用户推送体验。您无须申请此权益也能推送通知消息，未开通权益时，Push Kit默认您推送的是资讯营销类消息。 | 所有应用可申请，部分自分类申请需与应用分类相关。 |
| 推送通知扩展消息权益 | 消息到达后，推送通知消息，同时唤醒应用执行语音播报等动作。您必须申请此权益才能推送通知扩展消息。 | 仅为有商家新订单提醒、商家收款场景的应用开放。 |
| 推送应用内通话消息权益 | 应用内通话消息到达用户设备后，唤醒目标应用，弹出呼叫接听界面，实现音视频通话。您必须申请此权益才能推送应用内通话消息。 | 仅用于具备应用内音视频通话功能场景的沟通类、告警类应用。 仅服务于自身企业或政府组织单位内部。 |
有关场景化消息权益的权益内容及申请方式，请见下方具体章节。
说明
如果您在申请过程中遇到任何问题，请发送邮件至hwpush@huawei.com与我们取得联系。
2.2.2 申请通知消息自分类权益
1、通知消息分类方式
为了改善终端用户推送体验、营造良好可持续的通知生态，Push Kit对通知消息进行分类管理。根据消息内容，Push Kit将通知消息分类为服务与通讯、资讯营销两大类别。如您希望通知消息能更精准地符合业务需要，可以根据通知消息分类标准，自行对消息进行分类。
未开通通知消息自分类权益的应用，通知消息类型将会默认归为资讯营销类消息。
分类方式示意图：
说明
通知消息分类标准仅适用于推送通知消息，若您的应用涉及推送通知消息，则需按照标准进行分类。其他场景化消息可按照相应的指导完成开发适配。
2、通知消息分类标准与提醒方式
结合应用的消息内容和消息发送场景，Push Kit将通知消息分类为服务与通讯类和资讯营销类，并对不同类别的通知消息的提醒方式、消息展示位置、推送数量进行差异化管理，具体如下：
| 消息类型 | 场景说明 | 提醒方式与消息展示位置 | 推送数量限制 |
|---|---|---|---|
| 服务与通讯 | 包括社交通讯与服务提醒类消息，指应用借助通知中心及时向用户传递重要通知提醒，通常用户对接收此类消息有预期。 | 锁屏、铃声、振动等 | 与资讯营销消息、其他场景化消息合计不超过应用每日可向每设备发送的最大消息数量3000条。 |
| 资讯营销 | 包括资讯类消息和营销类消息，指的是运营人员向用户发送的活动信息、内容推荐、资讯等。 | 静默通知，仅在通知中心展示消息 | 根据应用类别限制每日推送数量，单个应用每日每设备推送数量为2条或5条。 |
说明
随着应用的消息发送场景不断变化，Push Kit的分类标准也将不断演进和补充，请及时留意本文档最新的分类说明。
服务与通讯类-社交通讯
| 消息类型 | 云端通知category取值 | 场景说明 | 消息提醒方式 |
|---|---|---|---|
| 即时聊天 | IM | 用户间点对点聊天消息（或私信）、群聊天消息。 注：需承诺不包括未关注人的私信、官方号或者商家批量推送给用户的私信或广告。 | 表示通知消息为服务与通讯类中的社交通讯。消息提醒方式默认为锁屏+铃声+振动（实际提醒方式以应用在通知管理中的设置为准）。 |
| 音频、视频通话 | VOIP | 语音通话邀请、视频通话邀请、来电提醒等。 注：仅为用户通知提醒，不涉及在后台拉起应用进程建立通话过程。 |
服务与通讯类-服务提醒
| 消息类型 | 云端通知category取值 | 场景说明 | 消息提醒方式 |
|---|---|---|---|
| 订阅 | SUBSCRIPTION | 用户主动订阅的内容并确认会收到推送（订阅仅开放以下场景，其他场景不支持申请）。
注意 申请订阅类消息需要满足以下所有条件并提供完整截图证明：
| 表示通知消息为服务与通讯类中的服务提醒。消息提醒方式默认为锁屏+铃声+振动（实际提醒方式以应用在通知管理中的设置为准）。 |
| 出行 | TRAVEL | 用户出行产生的通知提醒，推送对象为消费者。
| |
| 健康 | HEALTH | 用户主动测量的健康数据通知，仅限运动类、健康类应用使用。
| |
| 工作事项提醒 | WORK | 用户下一步需要做某件事项的提醒、待处理的业务流程。
| |
| 账号动态 | ACCOUNT | 用户账号和账号下资源资产的动态信息。
| |
| 订单&物流 | EXPRESS | 正在交易或完成交易的订单信息及物流状态信息。
| |
| 财务 | FINANCE | 金额变化的交易提示，仅限金融银行类、支付类应用使用。 收付款、银行到账&扣款、交易提醒、催缴&退款信息、充值、待支付账单、贷款受理进度、还款/逾期提醒、资金冻结提醒、资金限制提醒、缴纳保证金提醒。 | |
| 设备提醒 | DEVICE_REMINDER | IoT设备发出的设备状态/信息/提示/告警等提醒消息。 | |
| 邮件 | | 新收到的邮件，仅限邮箱类应用、办公软件应用使用。 | |
| 语音播报 | PLAY_VOICE | 需要用户特别注意的语音提醒，语音由应用本身进行播报。商家运营：用户支付金额提醒，用户取消支付提醒，来订单通知提醒。 | 表示通知消息为服务与通讯类中的服务提醒。消息提醒方式默认为锁屏+振动（实际提醒方式以应用在通知管理中的设置为准）。为了避免和应用中的语音播报冲突，此种类型消息无铃声提醒。 |
资讯营销类-内容资讯
| 消息类型 | 云端通知category取值 | 场景说明 | 消息提醒方式 |
|---|---|---|---|
| 财经动态 | MARKETING | 股票、彩票、期货、期权、外汇类通知，包括交易信息、行业公告等。 | 表示通知消息为资讯营销类。消息提醒方式为静默通知，仅在通知中心展示。 |
| 生活资讯 |
| ||
| 调研 | 发送问卷以获得受访者的态度和意见，包括使用习惯、产品满意度、服务满意度等。 | ||
| 其他 | 面向广大用户发布的产品功能推荐、平台公告、应用更新升级提醒等。 | ||
| 内容推荐 | 非用户主动订阅，应用向用户推送的内容。 包括点评、书籍、广告、视频、音频、节目、课程、直播、社区话题、游戏宣传等。 | ||
| 新闻 | 及时地报道新近发生的、有价值的事实。 包括政治新闻、经济新闻、法律新闻、军事新闻、科技新闻、文教新闻、体育新闻、社会新闻等。 | ||
| 社交动态 |
|
资讯营销类-营销活动
| 消息类型 | 云端通知category取值 | 场景说明 | 消息提醒方式 |
|---|---|---|---|
| 功能推荐 | MARKETING | 推荐用户使用当前产品的某一个功能。 | 表示通知消息为资讯营销类。消息提醒方式为静默通知，仅在通知中心展示。 |
| 运营活动 | 非用户主动设置，由应用发起需由用户参与的运营活动、提醒消息、游戏提醒、服务等。 | ||
| 产品促销 | 产品信息相关推广、产品优惠，例如满减、低至、促销、买一送一、返利、优惠券、代金券、送红包相关的通知。 |
3、通知消息推送数量管理规则
根据通知消息分类标准，Push Kit将通知消息分为服务与通讯、资讯营销两大类别。对这两类通知消息，Push Kit有不同的频控规则。
- 服务与通讯类消息推送数量没有上限，但受设备消息频控限制，所有场景化消息单日单设备推送数量不超过3000条。更多频控说明请参见消息频控。
- 资讯营销类消息会根据应用类型对每日推送数量进行上限管理。详情请见下表。
说明
- 关于应用类别信息，请参见华为应用市场应用分类示例。
- 单个应用每日每设备消息发送数量限制中的“每日”指的是自然日。
- 如应用不在下述分类中，或者未申请自分类权益，单个应用每日每设备推送数量默认为2条。
- 为避免在调测阶段消息被频控，建议调测阶段发送测试消息，详情请参见消息频控。
| 二级分类 | 三级分类 | 单个应用每日每设备通知推送数量（单位：条） |
|---|---|---|
| 新闻阅读 | 新闻（需具备《互联网新闻信息服务许可证》） | 5 |
| 电子书、杂志、有声读物、动漫、幽默、体育、分类信息 | 2 | |
| 休闲益智 | 所有 | 2 |
| 经营策略 | 所有 | 2 |
| 体育竞技 | 所有 | 2 |
| 棋牌桌游 | 所有 | 2 |
| 动作射击 | 所有 | 2 |
| 角色扮演 | 所有 | 2 |
| 影音娱乐 | 所有 | 2 |
| 实用工具 | 所有 | 2 |
| 社交通讯 | 所有 | 2 |
| 教育 | 所有 | 2 |
| 拍摄美化 | 所有 | 2 |
| 美食 | 所有 | 2 |
| 出行导航 | 所有 | 2 |
| 旅游住宿 | 所有 | 2 |
| 购物比价 | 所有 | 2 |
| 商务 | 所有 | 2 |
| 儿童 | 所有 | 2 |
| 金融理财 | 所有 | 2 |
| 运动健康 | 所有 | 2 |
| 便捷生活 | 所有 | 2 |
| 汽车 | 所有 | 2 |
| 主题个性 | 所有 | 2 |
4、申请通知消息自分类权益
申请原则
了解了通知消息分类方式，准备申请通知消息自分类权益前，建议先确认申请是否满足以下原则：
- 应用的推送消息按照一定维度进行分类，且分类符合通知消息分类标准。
- 应用遵守《华为推送服务使用协议》和相关规范，且未产生违规记录。
- 部分自分类申请需与应用分类相关：
- 健康：仅限运动类、健康类应用使用。
- 财务：仅限金融银行类、支付类应用使用。
- 邮件：仅限邮箱类、办公软件应用使用。
- 场景描述需包括以下关键信息：应用分类、应用主要业务、推送对象（同时注明推送对象为服务提供方或消费者）、推送时机和推送触发条件。
- 推送场景需与分类规则要求一致，消息模板需与推送场景描述对应，一个模板对应一个场景。
申请流程
- 登录AppGallery Connect网站，点击“我的项目”。
- 在项目列表中找到您的项目，通过“增长 > 推送服务 > 配置”，在“配置”页签下选择需要申请自分类权益的应用，点击自分类权益后的“申请”。
- 开发者可以选择标准场景或自定义场景填写对应的消息类型（建议优先选择标准场景）。部分场景（例如订阅）仅能通过自定义场景申请。
- 自定义场景审核期限为15个工作日内，您可以点击自分类权益后的“详情”，从“申请记录”中查看申请进展。
- 若您的申请已经审核通过（审核通过5分钟后，您申请的自分类权益生效），请根据申请自分类类型适配云端category字段。
- 适配完成后，点击界面上方的“激活功能”进行激活。若超过两个月未激活，需要重新申请。若过去已经激活权益，再次申请新的自分类权益时无需进行激活。
适配云端category字段
自分类权益生效后，应用推送的通知消息类型将根据您发送消息时的云端category字段进行归类。
category字段取值为大写的英文单词，且仅可填写在分类权益页面中已审批通过的category值，若出现分类错误或违反通知消息分类标准的场景，将被判为违规。
违规行为及相应的处理措施请参见通知违规处罚标准。
说明
如果您对上述规则有任何疑问，请发送邮件至hwpush@huawei.com与我们取得联系。
5、申请推送通知扩展消息权益
当用户终端收到您发送的通知扩展消息后，Push Kit会拉起应用的子进程，您可以在子进程中自行处理业务，执行语音播报等动作，每次拉起通知扩展子进程的时长默认为10秒，每次拉起通知扩展子进程后，请在10秒内完成事务处理，超出10秒子进程生命周期结束。
申请推送通知扩展消息存在以下限制：
- 该场景化消息仅为有商家新订单提醒、商家收款场景的应用开放。
- 应用不得以推送消息为手段，利用通知扩展消息能力拉起应用主进程。
申请邮件模板
注意
- 当前通知扩展消息处于Beta阶段，仅提供邮件申请方式。
- 企业内部应用申请特殊权限需要在邮件正文中附带应用下载二维码，并提供应用登录测试账号。
请提供如下信息到hwpush@huawei.com进行申请，我们会在15个工作日内回复申请结果，请您留意邮箱消息。
邮件主题：【场景化消息特殊权益申请】 - 通知扩展消息
邮件正文：
申请权限名称：通知扩展消息
企业名称：***
应用名称：***
应用包名：com.***.***
AppID：1****12
使用场景：***是商家交易平台，提供订单交易和收付款功能，希望借助通知扩展消息，实现对新订单和收款场景进行语音播报的功能。
承诺信息：
1.（应用名称）的通知扩展消息仅用于符合规定的场景中（具体场景）。
2.业务结束后，应用不再阻止系统休眠。
3.如有违反上述1、2的其他行为，同意华为Push Kit将该权益收回。
备注： 申请权益为“通知扩展消息”，需要根据具体使用场景，附带语音消息通知界面截图或语音播报录像。
5、申请推送应用内通话消息权益
应用内通话消息到达用户设备后，唤醒目标应用，弹出呼叫接听界面，实现音视频通话。
该场景仅用于具备应用内音视频通话功能场景的沟通类、告警类应用，仅服务于自身企业或政府组织单位内部。
说明
- 申请权益时需提供应用的应用内音视频通话界面截图。
- 提供包含被服务主体盖章的证明函（无固定模板），证明该App申请此权益仅服务于该公司/该组织单位内部。
- 依照《中华人民共和国电信条例》《互联网信息服务管理办法》，国家对电信业务经营按照电信业务分类，实行许可制度。经营电信业务，必须依照本条例的规定取得国务院信息产业主管部门或者省、自治区、直辖市电信管理机构颁发的电信业务经营许可证。未取得电信业务经营许可证，任何组织或者个人不得从事电信业务经营活动。其中，开展多方通信业务需取得《增值电信业务经营许可证》（B22国内多方通信服务业务），因此申请该权益需提供《增值电信业务经营许可证》（B22 国内多方通信服务业务）。具体资质的要求应由电信管理机构审核确定，华为将遵从监管指示对不符合上架资质要求的给以下架处理。
- 企业内部应用申请特殊权益需要在邮件正文中附带应用下载二维码，并提供应用登录测试账号。
申请邮件模板
注意
当前应用内通话消息处于Beta阶段，仅提供邮件申请方式。
请提供如下信息到hwpush@huawei.com进行申请，我们会在15个工作日内回复申请结果，请您留意邮箱消息。
邮件主题：【场景消息特殊权益申请】 - 应用内通话消息
邮件正文：
申请权限名称：应用内通话消息
企业名称：***
应用名称：***
应用包名：com.***.***
AppID：1****12
使用场景：***办公类软件，提供音视频通话功能，希望借助应用内通话消息，实现音视频通话功能。
承诺信息：
- （应用名称）的应用内通话消息仅用于符合规定的场景中（具体场景）。
- 业务结束后，应用不再阻止系统休眠。
- 本次提供的证明函以及《增值电信业务经营许可证》（B22国内多方通信服务业务）真实有效，不存在造假。
- 如有违反上述1、2、3的其他行为，同意华为Push侧将该权益收回。
备注：
- 申请权益为“应用内通话消息”，需要附带应用内音视频通话界面截图。
- 提供包含被服务主体盖章的证明函（无固定模板），证明该App申请此权限仅服务于该公司/该组织单位内部。
- 企业内部应用申请特殊权益需要在邮件正文中附带应用下载二维码，并提供应用登录测试账号。
2.3 获取Push Token
2.3.1 概述
Push Token标识了每台设备上每个应用，开发者调用getToken()接口向Push Kit服务端请求Push Token，获取到之后使用Push Token来推送消息。
Push Token一般情况不会变化，仅下列场景Push Token会发生变化：
- 卸载应用后重新安装。
- 设备恢复出厂设置。
- 应用显式调用deleteToken()接口后重新调用getToken()接口。
- 应用显式调用deleteAAID()接口后重新调用getToken()接口。
在应用启动时调用getToken()接口，若设备的Push Token发生变化，及时上报到应用服务器更新Push Token。
2.3.2 注意事项
2.3.3 接口说明
接口返回值有两种返回形式：Callback和Promise回调。下表中仅展示Promise回调形式的接口，Promise和Callback只是返回值方式不一样，功能相同。
| 接口名 | 描述 |
|---|---|
| getToken(): Promise<string> | 以Promise形式获取Push Token。 |
| deleteToken(): Promise<void> | 以Promise形式删除Push Token。 |
2.3.4 获取Push Token
1. 导入pushService模块及相关公共模块。
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
2. 建议在您的UIAbility（例如EntryAbility）的onCreate()方法中调用getToken()接口获取Push Token并上报到您的服务端，方便您的服务端向终端推送消息。代码示例：
export default class EntryAbility extends UIAbility {
// 入参 want 与 launchParam 并未使用，为初始化项目时自带参数
async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
// 获取Push Token
try {
const pushToken: string = await pushService.getToken();
hilog.info(0x0000, 'testTag', 'Succeeded in getting push token');
} catch (err) {
let e: BusinessError = err as BusinessError;
hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', e.code, e.message);
}
// 上报Push Token并上报到您的服务端
}
}
2.3.5 删除Push Token
1. 导入pushService模块
import { pushService } from '@kit.PushKit';
2. 调用PushService.deleteToken()接口删除Push Token。代码示例：
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
async myDeletePushToken() {
try {
await pushService.deleteToken();
hilog.info(0x0000, 'testTag', 'Succeeded in deleting push token');
} catch (err) {
let e: BusinessError = err as BusinessError;
hilog.error(0x0000, 'testTag', 'Failed to delete push token: %{public}d %{public}s', e.code, e.message);
}
}
}
3 推送场景化消息
3.1 推送通知消息
通知消息通过Push Kit通道直接下发，可在终端设备的通知中心、锁屏、横幅等展示，用户点击后拉起应用。
3.1.1 开通权益
Push Kit根据消息内容，将通知消息分类为服务与通讯、资讯营销两大类别，开放通知消息自分类权益。
两种类型的通知消息在提醒方式、消息展示位置、推送数量上皆存在差异
3.1.2 频控规则
调测阶段，每个项目每日全网最多可推送1000条测试消息。发送测试消息需设置testMessage为true。
正式发布阶段，单设备单应用下每日推送消息总条数受设备消息频控限制，所有场景化消息发送条数不超过3000条。
服务通讯类消息与资讯营销类消息存在不同的频控策略，详情请参见通知消息推送数量管理规则。
3.1.3 开发步骤
- 获取Push Token。
- 为确保应用可正常收到消息，建议应用发送通知前调用requestEnableNotification()方法弹出提醒，告知用户需要允许接收通知消息。详情请参见Notification Kit-请求通知授权。
- 为确保点击消息可以正常跳转应用页面，在应用项目中完成skills标签配置，详情请参见点击消息动作。
- 应用服务端调用Push Kit服务端的REST API推送通知消息，请求示例如下：
// Request URL
POST https://push-api.cloud.huawei.com/v3/[projectId]/messages:send
// Request Header
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type: 0
// Request Body
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0
},
"notifyId": 12345
}
},
"target": {
"token": ["IQAAAA**********4Tw"]
},
"pushOptions": {
"testMessage": true,
"ttl": 86400
}
}
- [projectId]：项目ID，登录AppGallery Connect网站，选择“我的项目”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取。
- Authorization：JWT格式字符串，可参见Authorization获取。
- push-type：0表示Alert消息，此处为通知消息场景。
- category：表示通知消息自分类的类别，MARKETING为资讯营销类消息，更多类别可参见category获取。
- actionType：0表示点击消息打开应用首页。
- token：Push Token，可参见获取Push Token获取。
- testMessage：测试消息标识，true表示测试消息。每个项目每天限制发送1000条测试消息，单次推送可发送Token数不超过10个。详情请参见testMessage。
- ttl：消息缓存时间，详见ttl。
- notifyId：（选填）自定义消息标识字段，仅支持数字，范围 [0, 2147483647]，若要用于消息撤回则必填。详情请参见notifyId。
5. 发送消息推送请求，请求响应请参见响应参数。请求发送成功后，可检查设备是否收到通知消息，如果设备未收到通知消息，请参见常见问题进行排查。
3.1.4 点击消息动作
1、点击消息进入应用首页并传递数据
1. 检查项目模块级别下的src/main/module.json5中关于应用首页Ability的skills标签配置（可以同时存在多个skill对象），其中某个skill对象的entities中应包含"entity.system.home"、actions中应包含"action.system.home"，如果在该skill对象中又已经配置了uris属性，建议将uris属性配置迁移到其他skill中，或者可以参考点击消息进入应用内页并传递数据中的方式实现点击消息进入应用首页的功能。
{
"name": "TestAbility",
"srcEntry": "./ets/abilities/TestAbility.ets",
"exported": false,
"startWindowIcon": "$media:icon",
"startWindowBackground": "$color:start_window_background",
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}, // 保证该skill对象中无uris配置
{
"actions": [
"com.app.action"
],
"uris": [
{
"scheme": "https",
"host": "www.app.com",
"port": "8080",
"path": "app/test"
}
]
} // 新增一个skill对象，配置actions和uris用于其他业务场景
]
}2. 发送消息时clickAction中携带data字段并设置actionType字段为0：
// Request URL
POST https://push-api.cloud.huawei.com/v3/[projectId]/messages:send
// Request Header
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type: 0
// Request Body
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0,
"data": {"testKey": "testValue"}
}
}
},
"target": {
"token": ["IQAAAA**********4Tw"]
},
"pushOptions": {
"testMessage": true
}
}- actionType：点击消息的动作，0表示点击消息后进入首页。
- data：点击消息时携带的JSON格式的数据。
3. 在应用首页中（通常为项目模块级别下的src/main/module.json5中mainElement的值）的onCreate()方法中覆写如下代码：
import { UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
export default class MainAbility extends UIAbility {
onCreate(want: Want): void {
// 获取消息中传递的data数据
const data = want.parameters;
const value = want.parameters?.["testKey"]; // value: "testValue"
hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
// 根据实际业务场景对data进行处理
}
}onNewWant()方法中覆写如下代码：
import { UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
export default class MainAbility extends UIAbility {
onNewWant(want: Want): void {
// 获取消息中传递的data数据
const data = want.parameters;
const value = want.parameters?.["testKey"]; // value: "testValue"
hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
// 根据实际业务场景对data进行处理
}
}4 端云调试
4.1 业务流程
Push Kit云侧主要业务流程如下：
- 应用服务端向华为Push Kit云侧推送场景化消息，发送后应用服务端将收到云侧返回的响应消息。
- Push Kit云侧将应用的场景化消息下发给应用终端，终端（Push Kit端侧）向云侧返回消息响应状态。
- Push Kit云侧将消息响应状态回执给应用服务端。开发者可以选择（可选）开发消息回执，以便您的服务端能收到云侧消息下发到端侧后的响应状态。未开通消息回执不会影响消息下发。
4.2 基于服务账号生成鉴权令牌
4.2.1 概述
服务账号（Service Account）是一种可实现服务器与服务器之间接口鉴权的账号，在华为开发者联盟的API Console上创建服务账号，您可根据返回的公私钥在业务应用中生成鉴权令牌，调用支持此类鉴权的华为公开API。
服务账号令牌为JWT（JSON Web Token）格式字符串，JWT数据格式包括三个部分：
- Header（头部）
- Payload（负载）
- Signature（签名）
这三个部分通过“.”进行连接，其中Signature为通过SHA256withRSA/PSS算法对Header与Payload拼接的字符串签名生成的字符串。
示例
eyJra*****JjNjBjMXXX.
eyJhd*****JodHRXXX.
BRNss*****7az5oU7-Zp5g9X2WJVXXX4.2.2 开发步骤
1. 创建服务账号密钥文件。
需要在华为开发者联盟的API Console上创建并下载推送服务API的服务账号密钥文件，相关创建步骤请参见API Console操作指南-服务账号密钥。
申请后的服务账号密钥样例文件形式可参考（文件内容已经经过脱敏处理）：
{
"project_id": "*****",
"key_id": "*****",
"private_key": "-----BEGIN PRIVATE KEY-----\nMIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQCKw6kJKtCh7qmMvp1u1dI27z2TKZrPOzHbQaXO/Eez0AWZ2EN+ouF496R3pfo7fQXC1XOT/YTbVC4DNZwWSMA54fu3/AOCY9Zzyi46OK*****==\n-----END PRIVATE KEY-----\n",
"sub_account": "*****",
"auth_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/authorize",
"token_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/token",
"auth_provider_cert_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/certs",
"client_cert_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/x509?client_id=*****"
}2. 生成JWT Header数据。
根据服务账号密钥文件中的key_id字段拼接以下JSON体，对JSON体进行BASE64编码。
示例
{
"kid": "*****",
"typ": "JWT",
"alg": "PS256"
}| 字段名 | 描述 |
|---|---|
| kid | 服务账号密钥文件中key_id字段。 |
| typ | 数据类型，固定为：JWT。 |
| alg | 算法类型，固定为：PS256。 |
3. 生成JWT Payload数据。
根据服务账号密钥文件中的sub_account字段拼接以下JSON体，对JSON体进行BASE64编码。
示例
{
"aud": "https://oauth-login.cloud.huawei.com/oauth2/v3/token",
"iss": "*****",
"exp": 1581410664,
"iat": 1581407064
}| 字段名 | 描述 |
|---|---|
| iss | 服务账号密钥文件中sub_account字段，标识数据生成者。 |
| aud | 固定为：https://oauth-login.cloud.huawei.com/oauth2/v3/token。 |
| iat | JWT签发UTC时间戳，为自UTC时间1970年1月1日00:00:00的秒数（您的服务器时间需要校准为标准时间）。 |
| exp | JWT到期UTC时间戳，比iat晚3600秒。 |
4.生成JWT。
将完成BASE64编码后的Header字符串与Payload字符串，通过“.”进行连接，您可在业务应用中，通过服务账号密钥文件中的private_key（华为不进行存储，请您妥善保管），使用SHA256withRSA/PSS算法对拼接的字符串签名。
至此，您已经完成服务账号鉴权令牌JWT的生成。
4.3 在线生成服务账号鉴权令牌
若想在正式开发前调试功能，可使用在线生成工具获取JWT Token。
请注意，生成JWT Token时Algorithm请选择PS256。
4.4 调用推送服务REST API
应用调用推送服务REST API时，需要把已获得的服务账号鉴权令牌放在Authorization头部来进行鉴权。
示例
POST https://push-api.cloud.huawei.com/v3/3158882***52863/messages:send
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type:04.5 端云调试推送场景化消息
4.5.1 场景介绍
Push Kit支持使用HTTPS协议接入云侧，使用场景化V3接口发送场景化消息，并将不同场景定义为不同push-type。
可发送的场景化消息类型如下表：
| push-type | 名称 |
|---|---|
| 0 | Alert消息（通知消息、授权订阅消息） |
| 1 | 卡片刷新 |
| 2 | 通知扩展消息 |
| 6 | 后台消息 |
| 7 | 实况窗消息 |
| 10 | 应用内通话消息 |
4.5.2 开发步骤
- 您的服务端获取鉴权令牌，详情请参见基于服务账号生成鉴权令牌。
- 您的服务端调用API发送Push场景化消息，更多消息内容请参见REST API-场景化消息API接口。
HTTPS POST URL：
POST https://push-api.cloud.huawei.com/v3/[projectId]/messages:send“[projectId]”请替换为您应用的项目ID。登录AppGallery Connect网站，选择“我的项目”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取“项目ID”。
请求消息头示例：
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type: 0- 请求消息头中的Authorization参数为"Bearer "拼接上您在上一步中获取的鉴权令牌。
- 请求消息头中的push-type参数为场景化消息类型，0代表Alert消息（包括通知消息、授权订阅消息）。
通知消息体示例：
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0
},
"notifyId": 12345
}
},
"target": {
"token": ["IQAAAA**********4Tw"]
},
"pushOptions": {
"testMessage": true
}
}- 更多场景化消息示例可参见请求示例。
- 建议在开发代码前先使用Postman等调试工具发送消息，测试功能。
4.5.3 AppGallery Connect在线推送通知消息
注意
当前仅支持配置Alert消息。
- 登录AppGallery Connect网站，点击“我的项目”。
- 在项目列表中找到您的项目，通过“增长 > 推送服务 > 推送通知（V3 Beta）”导航到“推送通知（V3 Beta）”页签。在该页签下点击“添加推送通知”新建推送任务。
- 这里以Alert消息举例，配置参数如下。
- 配置推送任务
字段值
说明
选择应用
必填字段，消息发送的目标应用。
名称
必填字段，用于在管理台中标识通知，此名称不会给用户显示。
场景化类型
场景化消息类型，当前仅支持Alert消息。
- 配置推送内容-通用参数
字段值
说明
是否测试消息 (testMessage)
必选字段，对应场景化接口中的testMessage参数；
测试消息标识：
- false：正式消息
- true：测试消息（默认值）
离线消息缓存机制 (collapseKey)
可选字段，对应场景化接口中的collapseKey参数；
离线消息缓存控制方式，取值范围-1~100：
- 0：对每个应用发送到该用户设备的离线消息只会缓存最新的一条；
- -1：对所有离线消息都缓存（默认值）；
- 1~100：离线消息缓存分组标识，对离线消息进行分组缓存，每个应用每一组最多缓存一条离线消息。
消息缓存时间 (ttl)
可选字段，对应场景化接口中的ttl参数；
消息缓存时间，单位是秒。在用户设备离线时，消息在Push服务器进行缓存，在消息缓存时间内用户设备上线，消息会下发，超过缓存时间后消息会丢弃，默认值为86400秒（1天），最大值为15天。
批量任务消息标识 (biTag)
可选字段，对应场景化接口中的biTag参数；
批量任务消息标识，消息回执时会返回给应用服务器，长度最大64字节。
回执ID (receiptId)
可选字段，对应场景化接口中的receiptId参数；
回执ID指定本次下行消息的回执地址及配置。该回执ID可以在配置回执参数中查看。
- 配置推送内容-发送目标设备
字段值
说明
设备Token (token)
必填字段，对应场景化接口中的token参数；
按照Token向目标用户推送消息。
样例：IQAAA*******
- 配置推送内容-消息内容
字段值
说明
消息类别 (category)
必填字段，对应场景化接口中的category参数；
通知消息类别。完成申请通知消息自分类权益后，用于标识消息类型，不同的通知消息类型影响消息展示和提醒方式。取值如下：
- 即时聊天：IM
- 音视频通话：VOIP
- 订阅：SUBSCRIPTION
- 出行：TRAVEL
- 健康：HEALTH
- 工作事项提醒：WORK
- 账号动态：ACCOUNT
- 订单&物流：EXPRESS
- 财务：FINANCE
- 设备提醒：DEVICE_REMINDER
- 邮件：MAIL
- 新闻、内容推荐、社交动态、产品促销、财经动态、生活资讯、调研、功能推荐、运营活动（仅对内容进行标识，不会加快消息发送），统称为资讯营销类消息：MARKETING
消息标题 (title)
必填字段，对应场景化接口中的title参数；
通知消息标题。
消息内容 (body)
必填字段，对应场景化接口中的body参数；
通知消息内容。
点击通知动作 (actionType)
必填字段，对应场景化接口中的clickAction中actionType参数；
点击消息后触发的动作，可选择打开应用首页、自定义action页面或自定义intentUri页面。
- 当您完成上述步骤后，点击右上方“提交”按钮即可推送消息。
扫一扫
1554
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
