场景介绍

如今衣食住行娱乐影音应用占据了大多数人的手机,一部手机可以满足日常大多需求,但对需要经常查看或进行简单操作的应用来说,总需要用户点开应用体验较繁琐。针对此种场景,HarmonyOS提供了Form Kit(卡片开发服务),您可以将应用的重要信息或操作前置到卡片,以达到服务直达、减少体验层级的目的。

面对需要实时更新信息的应用卡片,Push Kit向开发者提供了卡片刷新服务。应用通过集成Push Kit后获取Push Token,基于Push Kit的系统级通道,便可以在合适场景向用户即时推送卡片内容,从而提升用户的感知度和活跃度。

cke_4665.png

频控规则

调测阶段,每个项目每日全网最多可推送1000条测试消息。发送测试消息需设置testMessage为true。

正式发布阶段,单设备单应用下每日推送消息总条数受设备消息频控限制,所有场景化消息发送条数不超过3000条。

单张服务卡片刷新消息受应用是否上架影响:

  • 已上架:单设备单应用下单张卡片每日限制发送2条消息。
  • 未上架:单设备单应用下单张卡片每日限制发送5条消息。

说明

不论是测试消息还是正式消息,卡片刷新消息单次发送仅能携带一个Token。

开发步骤

开发卡片

推送卡片刷新消息前,您需先完成本地卡片的开发。

  1. 参见创建一个ArkTS卡片,完成本地服务卡片的创建。
  2. 在项目模块级别下的src/main/resources/base/profile/form_config.json中配置dataProxyEnabled字段为true,开启卡片代理刷新功能。
    {
    "forms": [
    {
    "name": "WidgetCard",
    "src": "./ets/widget/pages/WidgetCard.ets",
    "uiSyntax": "arkts",
    "window": {
    "designWidth": 720,
    "autoDesignWidth": true
    },
    "colorMode": "auto",
    "isDefault": true,
    "updateEnabled": true,
    "updateDuration": 1,
    "scheduledUpdateTime": "10:30",
    "defaultDimension": "2*2",
    "supportDimensions": ["2*2"],
    "dataProxyEnabled": true
    }
    ]
    }

  3. 在卡片生命周期管理文件(下以EntryFormAbility为例)的onAddForm()回调中获取formId,定义需要在卡片页面文件(下以WidgetCard为例)中和通过Push Kit要刷新的字段,如下以text_keyimage_key为例。

    import { formBindingData, formInfo, FormExtensionAbility } from '@kit.FormKit';
    import { Want } from '@kit.AbilityKit';
    export default class EntryFormAbility extends FormExtensionAbility {
    onAddForm(want: Want): formBindingData.FormBindingData {
    // 获取formId
    const formId = want.parameters![formInfo.FormParam.IDENTITY_KEY] as string;
    // 定义需要在WidgetCard中刷新的字段
    class CreateFormData {
    formId: string = '';
    text_key: string = '';
    image_key: string = '';
    }
    const obj: CreateFormData = {
    formId: formId,
    text_key: '默认文本',
    image_key: ''
    }
    const bindingData: formBindingData.FormBindingData = formBindingData.createFormBindingData(obj);
    // 定义需要通过Push Kit代理刷新的字段,每个key均需要在上面bindingData中定义
    const text_key: formBindingData.ProxyData = {
    key: 'text_key',
    subscriberId: formId
    };
    const image_key: formBindingData.ProxyData = {
    key: 'image_key',
    subscriberId: formId
    };
    bindingData.proxies = [text_key, image_key];
    return bindingData;
    }
    }

  4. 卡片页面文件( src/main/ets/widget/pages/WidgetCard.ets为例)中,创建LocalStorage变量并与@Entry装饰器绑定,使用@LocalStorageProp装饰器创建key-value的变量。

    本文创建了formId、text和image三个变量,对应的key为formIdtext_keyimage_key,需要注意的是卡片页面布局中image对应的组件是Image图片组件,图片组件传递的变量必须以 memory:// 开头。

    // 定义页面级的UI状态存储LocalStorage
    const storage = new LocalStorage();
    // 绑定
    @Entry(storage)
    @Component
    struct WidgetCard {
    @LocalStorageProp('formId') formId: string = '';
    @LocalStorageProp('text_key') text: string = '';
    @LocalStorageProp('image_key') image: string = '';
    build() {
    Flex({ direction: FlexDirection.Column }) {
    Row() {
    Text() {
    // Span是Text组件的子组件,用于显示行内文本
    Span('formID:')
    Span(this.formId)
    }
    .fontSize(10)
    }
    Row() {
    Text() {
    Span('文本:')
    Span(this.text)
    }
    .fontSize(10)
    }
    Row() {
    if (this.image) {
    Image('memory://' + this.image).height(80)
    }
    }
    }
    .padding(10)
    }
    }

推送卡片刷新消息

  1. 参见指导获取Push Token
  2. (可选)建议您将formIdpushToken等信息上报到应用服务端,用于向应用发送卡片刷新消息。

    // 以下为伪代码
    import { Want } from '@kit.AbilityKit';
    import { pushService } from '@kit.PushKit';
    import { hilog } from '@kit.PerformanceAnalysisKit';
    import { BusinessError } from '@kit.BasicServicesKit';
    import { formInfo } from '@kit.FormKit';
    async function saveFormInfo(want: Want): Promise<void> {
    try {
    const formId = want.parameters![formInfo.FormParam.IDENTITY_KEY] as string;
    const moduleName = want.moduleName;
    const abilityName = want.abilityName;
    const formName = want.parameters![formInfo.FormParam.NAME_KEY] as string;
    const pushToken: string = await pushService.getToken();
    // 将formId, moduleName, abilityName, formName, pushToken 上报到应用服务端
    } catch (err) {
    let e: BusinessError = err as BusinessError;
    hilog.error(0x0000, 'testTag', 'Failed to save form info: %{public}d %{public}s', e.code, e.message);
    }
    }

  3. 应用服务端调用REST API推送卡片刷新消息,消息详情可参见场景化消息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: 1
    // Request Body
    {
    "payload": {
    "moduleName": "entry",
    "abilityName": "EntryFormAbility",
    "formName": "widget",
    "formId": 423434262,
    "version": 123456,
    "formData": {
    "text_key": "刷新文本内容"
    },
    "images": [
    {
    "keyName": "image_key",
    "url": "***",
    "require": 1
    }
    ]
    },
    "target": {
    "token": [
    "IQAAAAC*************************dRH7_bPbfMrVfsYw"
    ]
    },
    "pushOptions": {
    "testMessage": true
    }
    }
    ​
    • [projectId]:项目ID,登录AppGallery Connect网站,选择“我的项目”,在项目列表中选择对应的项目,左侧导航栏选择“项目设置”,在该页面获取。
    • Authorization:JWT格式字符串,可参见Authorization获取。
    • push-type:1表示服务卡片刷新场景。
    • moduleName:项目模块级别下的 src/main/module.json5 中的 module 标签下的name值。

      cke_10864.png

    • abilityName:项目模块级别下的src/main/module.json5中的extensionAbilities标签下的服务卡片的ability名称。

      cke_16651.png

    • formName:项目模块级别下的src/main/resources/base/profile/form_config.json中的forms标签下的服务卡片的名称。下图以卡片配置文件form_config为例:

      cke_22225.png

    • version:当前卡片刷新消息的版本号,新的卡片刷新消息的版本号需大于当前卡片刷新消息版本号,否则会刷新失败。详情参见version
    • formId:服务卡片的实例ID,当卡片的onAddForm()方法被调用时(卡片使用方添加卡片至桌面)进行获取。最大值为2^31-1
    • formData:填写待刷新服务卡片的业务数据,该数据来源于项目模块级别下的src/main/ets/widget/pages/WidgetCard.ets文件下的声明式范式组件名称。下图以卡片页面文件WidgetCard为例:

      cke_27907.png

    • images:待刷新服务卡片业务数据中的图片数据,其中keyName为您服务卡片中图片控件的key值,url为图片的地址(需替换为图片风控验证后的downloadUrl),下图以卡片页面文件WidgetCard为例:

      cke_33688.png

    • require:图片刷新策略控制,“0”表示如果图片下载失败,仅刷新文字;“1”表示如果图片下载失败,则不进行刷新操作。
    • token:Push Token,可参见获取Push Token获取。
    • testMessage:测试消息标识,true表示测试消息。每个项目每天限制发送1000条测试消息,单次推送仅能发送一个Token。详情请参见testMessage

点赞(0) 打赏

评论列表 共有 0 条评论

暂无评论

微信公众账号

微信扫一扫加关注

发表
评论
返回
顶部