关联阅读:卡片类快服务开发指南(一)
指南(一)叙述了1、卡片介绍 2、结构说明和 3、第一个卡片,(二)从第4点开始讲解……
4. 附录
(1)IDE下载链接:
(2)快应用开发规范:
5. 卡片类快服务设计规范
卡片是展示内容及操作的容器,针对相同主题,依托于一个应用或服务提供内容。卡片内容形式灵活,展示与当前场景相关、及时且必要的信息,可包含文字、图形、配图及操作,帮助用户快速获取相关信息并执行操作。
请参照:华为快服务审核指南-2.1 UX基本规范。
6. 系统推荐类快应用卡片快服务开发指南
6.1 开发者业务事件触发快服务
6.1.1 介绍
开发者通过调用华为快服务智慧平台事件通知接口,为某个终端用户触发快服务。如开发者向华为快服务智慧平台发送某个用户登机提醒通知消息,当该用户打开华为产品时,即可看到一张登机提醒的卡片。
6.1.2 约束
同一个服务同一时刻在产品上只会展现一张卡片。卡片展示顺序按照触发时间排序,最近触发的卡片会覆盖旧卡片。
对于事件触发的快服务,需要做帐号绑定。帐号绑定请参照:6.2帐号绑定流程章节。
6.1.3 开发事项
在开发者联盟上申请appID。
开发事件通知服务,该服务会根据用户事件调用华为快服务智慧平台事件通知接口发送消息,触发卡片。
开发卡片及卡片其服务器的交互接口。
6.1.4 事件触发服务流程
用户订单事件推荐Ability的流程示例:
开发者服务器获取调用华为快服务智慧平台事件通知接口的访问权限。参考:12.快应用卡片API说明【INF5】。
开发者服务器将用户的订单事件发送给华为快服务智慧平台,事件信息里的主要参数:事件名称(用于和卡片唯一匹配)、用户openID、卡片参数(华为快服务智慧平台透传给卡片)。参考:12.快应用卡片API说明【INF8】。
华为快服务智慧平台服务器收到第三方的事件后,根据事件名称匹配卡片,将匹配的卡片放入缓存中。
用户打开华为产品,产品从华为快服务智慧平台服务器获取用户的卡片信息(卡片模板和卡片参数),获取时校验卡片有效期。
华为快服务智慧平台SDK将卡片参数传给卡片模板。
卡片初始化方法(onInit)中,获取卡片参数(通过this.key获取),调用开发者服务器的接口获取卡片内容。
6.2 帐号绑定流程
6.2.1 介绍
通过帐号绑定实现用户华为帐号和第三方应用帐号的关联。目的是用户如果登录了华为帐号,则无需登录第三方应用就能使用服务。
华为使用openID(华为帐号生成)与第三方应用的帐号做绑定关联。
6.2.2 约束
每个华为帐号对于每个应用(appID区别)的openID是唯一的。
6.2.3 UI流程
参考:《帐号绑定UI流程》。
6.2.4 开发事项
在开发者联盟上申请appID。
在开发者联盟上为对应的RPK产品申请帐号服务。
在快应用里开发帐号绑定的页面和逻辑。
在开发者服务器侧开发帐号绑定的逻辑。
6.2.5 帐号绑定流程
用户在华为产品上点击帐号绑定,跳转到快应用的帐号关联页面。
在快应用的帐号关联页面里调用接口获取用户授权code、用户昵称和头像。参考:12.快应用卡片API说明【INF10、INF11、INF12】。
用户在快应用的帐号关联页面上输入用户帐号信息,并确认授权。
快应用将用户帐号信息、code发送到快应用的云侧服务器。
快应用服务器调用华为鉴权服务器的接口,根据code获取用户openID和AT(AcessToken)。参考:12.快应用卡片API说明【INF2、INF4】。
快应用服务器完成openID和帐号关联绑定。
快应用服务器完成帐号关联后,调用华为快服务智慧平台接口将帐号关联结果发送给华为快服务智慧平台。参考:12.快应用卡片API说明【INF5、INF6】。
6.2.6 登录信息维护的流程
用户完成华为帐号和第三方应用帐号绑定后,如果华为帐号登录,在快应用里就无需登录开发者帐号进行业务操作。避免华为帐号切换后,造成用户数据错乱,需要在快应用每次访问时都获取openID,建议流程如下(可以根据开发者实际情况调整):
6.2.6.1 登录或帐号绑定流程
1、用户打开快应用,快应用调用引擎的方法 account.authorize获取code。参考:12.快应用卡片API说明【INF10】。
2、快应用调用开发者服务器进行业务操作,将code传给服务器。
3、开发者服务器根据code获取openID。参考:12.快应用卡片API说明【INF2、INF4】。
4、开发者服务器完成帐号绑定,关联openID和开发者帐号。调用华为接口通知帐号绑定结果。参考:12.快应用卡片API说明【INF5、INF6】。(可选步骤:登录流程跳过)
5、生成session(建议KV结构) ,session的key由开发者自定义,value保存openid。
6、将session的key下发到快应用端侧。
6.2.6.2 再次打开快应用
1、用户打开快应用,快应用调用引擎的方法 account.authorize获取code。参考:12.快应用卡片API说明【INF10】。
2、快应用调用开发者服务器进行业务操作,将code和sessionKey传给服务器。
3、开发者服务器根据code获取openID。参考:12.快应用卡片API说明【INF2、INF4】。
4、开发者服务器通过sessionKey获取openID,与第3步获取的openID做比较(是否为同一个用户)。
如果一致,则使用openID关联的开发者帐号进行业务操作;
如果不一致,则重新生成session。
7. 用户查询类快应用卡片快服务开发指南
根据用户在华为HiTouch、HiVision、HiVoice、智能家居、场景包等产品的查询意图、查询关键字等查找快服务,并以卡片、语音等多种形式呈现给用户。开发者可以定义自己的快应用在不同的华为产品展现不同的形式,也可以展示相同的卡片。
7.1 通过关键词查询分发快服务流程
7.1.1 介绍
用户在搜索条通过输入关键字查找快服务或者双指按压屏幕通过HiTouch识别的关键字查找快服务。华为根据用户输入中的关键词匹配搜索卡片模板,并将用户完整的查询关键字内容传到卡片里,卡片初始化时将查询关键字内容传给开发者的服务器,开发者的服务器完成内容查询匹配并返回卡片内容进行渲染。
7.1.2 约束
开发者为每个快服务配置的查询关键词上限为300个。
7.1.3 开发事项
开发者定义查询展示的卡片,该卡片可以通过用户的完整查询关键字从开发者服务器端获取数据内容并填充卡片。
开发者需要通过开发者联盟定义Ability服务为查询触发服务,并可以定义服务的查询关键词(300以内)。
7.1.4 关键词触发流程
开发者在联盟上为快服务配置查询关键词(300个以内)。详见:卡片类快服务接入指南。
用户在华为HiTouch、搜索条产品上进行查询。
华为产品根据用户查询意图和查询关键字匹配到的服务卡片,拉起卡片模板。并将用户的查询关键字传给卡片。
卡片onInit时,获取到用户的查询关键字,卡片将用户查询关键字发送到卡片服务器侧获取内容后渲染服务卡片。
卡片内获取用户查询语句的方式为 this.hag_searchParam。
7.2 通过图像查询分发快服务流程
7.2.1 介绍
根据用户在HiVision产品扫图、扫二维码等的查询意图、查询关键字等查找快服务。用户查询时,华为根据用户输入的图片、二维码等信息解析为用户意图和查询关键字匹配快服务信息和卡片模板,并将用户的图片流以及查询关键字(可选)传到卡片里,卡片初始化时将图片流以及查询关键字(可选)传给开发者的服务器,开发者的服务器完成图片流以及查询关键字(可选)的识别查询匹配返回卡片内容进行渲染。
7.2.2 约束
开发者为每个快服务配置的查询关键词上限为300个。
7.2.3 开发事项
开发者定义查询展示的卡片,该卡片可以通过用户的查询关键字从开发者服务器端获取数据内容并填充卡片。
开发者需要通过开发者联盟定义Ability服务为查询触发服务、扫一扫触发服务、扫图触发服务,并可以定义服务的查询关键词(300以内)。
开发者可以在定义Ability服务时选择内容同步,并配置同步方式和服务器地址以及鉴权信息。同步的内容会作为查询索引,可以提升Ability服务的查询命中率。(可选)
7.2.4 图像触发流程
开发者在联盟上为快服务配置查询关键词(300个以内)。详见:卡片类快服务接入指南。
开发者在联盟上配置内容同步的方式和相关配置信息。
服务器对接同步内容信息。详见:7.3内容接入流程。
用户在华为HiVision产品上进行扫图、扫二维码。
华为产品根据用户扫的图或二维码分析出查询关键信息进行Ability匹配,将匹配到的卡片信息返回给HiVision产品,拉起卡片模板。并将用户的图片流以及查询关键字(可选)传给卡片。
卡片onInit时,获取到用户的图片流以及查询关键字(可选)发送给卡片,卡片将图片流和查询关键字(可选)发送到卡片服务器侧获取卡片内容。
卡片内获取用户图片流的方式为this.imgData,获取用户查询关键字的方式为this.hag_searchParam(可选)。
7.3 内容接入流程
7.3.1 介绍
为了提升Ability的查询命中率,开发者可以提供Ability对应的内容数据在华为快服务智慧平台建立查询索引。
7.3.2 约束
内容对接前需要提供的内容品类、内容量级、内容更新频率、更新量级等信息进行评估。
7.3.3 开发事项
开发者在开发者联盟上定义Ability时选择同步内容数据,并且配置同步方式、服务器地址、鉴权信息等。
开发者按照华为的接口规范提供垂类数据的获取接口、协商好调用频次,华为调用该接口获取数据。
开发者按照华为的接口规范实时调用华为提供的垂类数据推送接口,实时向华为快服务智慧平台推送数据。
7.3.4 内容同步流程
开发者在开发者联盟定义Ability时,如果提供内容数据则需要配置提供内容的服务器地址、内容同步方式以及鉴权信息。
华为快服务智慧平台根据配置的地址定时向开发者服务器请求按垂类获取内容数据。同时华为快服务智慧平台也接收开发者服务器推送的内容数据。通过开发者内容数据建查询索引。
用户使用华为手机的HiVision、HiTouch、HiVoice、搜索条等媒体入口查询信息时,华为快服务智慧平台服务器进行内容查询索引的匹配,匹配成功后,将对应的Ability信息返回给端侧,由端侧向用户呈现Ability信息。
8. 酒店垂域快应用卡片内容数据接入接口规范
为了规范华为华为快服务智慧平台面向开发者的内容数据接入开发指南,包括业务流程、接口定义。确保业务理解一致,开放接口定义统一,便于开发者更好的使用。
术语、定义和缩略语:
| 术语 | 英文 | 中文 |
| HAG | Huawei Ability Gallery | 华为快服务智慧平台 |
| HTTP | Hyper Text Transfer Protocol | 超文本传输协议 |
| XML | Extensible Markup Language | 可扩展标记语言 |
| JSON | JavaScript Object Notation | 是一种轻量级的数据交换格式 |
8.1 典型业务场景
8.1.1 开发者内容入库场景
华为通过服务聚合网关定时调用开发者接口获取开发者内容数据入库,同时提供接口供开发者调用,满足开发者需要实时同步内容数据的场景,流程如下图所示:
8.2 开发者内容接入CheckList
8.2.1 开发者内容接入
在开发者内容数据引入前通过Checklist检查数据引入的总数据量级、日变化量级等信息。
| 检查项 | 描述信息 | 结果 |
| 数据总量 | 开发者能够提供给华为的总数据量(条) | |
| 日变化量 | 开发者能够提供给华为数据的日变化量(条) | |
| 数据大小 | 单条数据的最大大小 | |
| 同步频度 | 全量同步、增量同步的频度。 |
8.3 服务器侧接口规范
8.3.1 接口协议
接口协议:HTTPS。
数据格式:请求和响应原则上要求采用Json的报文格式。
请求方法:支持POST(提交类)和DELETE(删除类)两种方式。
8.3.2 URL定义
华为快服务智慧平台服务器提供的接口URL定义如:http[s]://{域名}/{模块}?{参数},URL中各部分的说明如下:
| 字段 | 含义 | 样例 |
| 域名 | 对外提供接口的地址 | hag.cloud.huawei.com |
| 模块 | 服务名称 | ?? |
接口资源和参数名称统一采用驼峰命名法。例如:cardList。
8.3.3 与开发者的状态码/错误码定义
与客户端返回的状态包包括HTTP状态码和业务错误码。
8.3.3.1 HTTP状态码
HTTP的状态码要求使用HTTP协议中的已有定义,参考RFC 2616的规范定义;禁止重复定义HTTP协议中已有的相应代码。
8.3.3.2 业务错误码
当请求错误或执行失败时,需要在Content-body中明确定义相关的错误码。业务错误码的定义和说明如下:
| 参数名 | 参数类型 | 可选 | 说明 |
| code | String | 必选 | 错误码,请求成功时为0。 |
| desc | String | 可选 | 错误原因,请求成功时可以为空。 |
1、错误码定义:
| 业务错误码 | 错误信息 | 备注 |
| 0 | OK | 成功 |
| 1 | Invalid parameter | 无效参数 |
| 2 | Incorrect signature | 签名错误 |
| 3 | Too many parameters | 参数过多 |
| 4 | Unsupported signature method | 不支持此签名方式 |
| 5 | Invalid/Used timestamp parameter | 时间戳无效 |
| 6 | Unsupported open api | 不支持此接口 |
| 12 | Session key invalid or no longer valid | 会话密钥无效 |
| 31 | Forbidden | 信息校验失败 |
| 32 | Data parse error | 数据解析出错 |
| 80 | Request Timeout | 请求超时 |
| 101 | Unknown error | 未知错误 |
| 102 | Server internal error | 服务器错误 |
| 103 | Service temporarily unavailable | 服务暂不可用 |
2、说明:
(1)业务错误
返回错误码非0,则认为是业务处理出错,需要服务器检查错误码,定位错误原因,例如:auth失败,参数不对,超出容量等。需要先解决参数问题,再向服务器端重新发起请求。
(2)http错误
返回的状态码非200,表示服务端内部发生错误,客户端需要重试。
8.4 服务器侧接口定义
8.4.1 酒店类内容数据接口
8.4.1.1 获酒店信息内容数据(hotelInfoList)
1、接口描述
本接口用于华为服务聚合网关从第三方服务器获取酒店内容信息。
2、接口地址
| 项目 | 描述 |
| 调用关系 | “华为服务器” > “第三方服务器” |
| 调用方式 | HTTPS+POST |
| 请求地址 | 开发者在Ability开发平台配置的数据开放地址。 |
| 约束 | 1. 为了节省带宽第三方开发者的响应消息要开启gzip压缩; 2. 为了避免服务器调用的连接的开销,第三方开发者要支持http:keep-alive,华为服务器使用http长连接的方式进行服务的调用。 |
3、请求报文
| 参数列表 | 类型 | M/O | 字段描述 |
| appKey | String | M | 开发者在华为Ability开发平台上配置的访问accessKey。 |
| appSecret | String(256) | M | 参数签名=base64(hmac-sha256(secretKey, ts))secretKey为华为分配给开发者服务器的访问秘钥。 |
| countryCode | String | O | 国家码,不带是默认按照CN处理。 |
| language | String | O | 语言类型,不带时默认按照ZH处理。 |
| abilityId | String | O | 当一个开发者有多个Ability时,支持按照不同的Ability获取内容数据。 |
| ts | String | M | 时间戳,用于加密和缓存穿透。 |
| pageSize | Integer | M | 每页返回记录的数量,默认500条。 如=500 则第三方开发者将200条酒店内容数据返回给华为,实际返回的可以少于500条。 |
| page | Integer | M | 返回记录的开始页数,首次请求带“0” 。 |
| 请求报文 { “appKey”: “ow1oDF6bBgW3CSIh”, “appSecret”: “”, “countryCode”: “CN”, “language”: “ZH”, “abilityId”: “106”, “ts”: “1460032806000”, “pageSize”: “200”, “page”: “1” } | |||
4、响应报文
| 参数列表 | 类型 | M/O | 字段描述 |
| code | String | M | 业务错误码 |
| desc | String | O | 错误结果描述,可以是成功信息ok或失败原因。 |
| totalPage | Integer | M | 满足数据的总页数 |
| currentPage | Integer | M | 当前页数 |
| data | JsonObject | O | 批量获取的数据 |
(1)酒店内容数据data结构体的定义如下所示:
| 参数列表 | 类型 | M/O | 字段描述 |
| contents | JsonArray | O | 酒店内容信息列表 |
(2)hotels的结构体:
| 参数名 | 参数类型 | M/O | 参数描述 | 参数作用 |
| contentId | String | M | 酒店信息唯一标识。最大长度32字节。 | 用于数据修改、删除时的唯一匹配索引。 |
| name | String | O | 酒店名称。最大长度64字节。 | 检索条件、结果展示。 |
| alias | String | O | 酒店别名,可能有多个,以逗号作为分隔符。最大长度64字节。 | 检索条件 |
| description | String | O | 描述(摘要)。最大长度512字节。 | 检索条件 |
| category | String | O | 酒店分类,如经济型、舒适型、高端型等。最大长度32字节。 | 检索条件 |
| tags | String | O | 关键词,逗号作为分隔符,如亲子酒店、临江景观等。最大长度64字节。 | 检索条件 |
| minPrice | Float | O | 最低价格,单位为元,最小价格是0.01元。 | 检索条件、结果展示。 |
| maxPrice | Float | O | 最高价格,单位为元,最小价格是0.01元。 | 检索条件 |
| location | LocationInfo | M | 地理位置信息,同步经纬度信息或具体省区市等位置信息。 | 检索条件、结果展示。 |
| infrastructure | String | O | 酒店设施,如会议室、健身房等,传递多种设施描述时通过逗号分隔。最大长度64字节。 | 检索条件 |
| service | String | O | 酒店服务,如洗衣服、叫醒等。传递多种酒店服务时通过逗号分隔。最大长度64字节。 | 检索条件 |
| roomType | String | O | 酒店提供的房型描述,如标准间、大床房等,传递多种酒店房型时通过逗号分隔。最大长度64字节。 | 检索条件 |
| images | ImageInfo | O | 图片信息 | 结果展示 |
| level | String | O | 酒店星级,如三星级、四星级、五星级等。最大长度32字节。 | 检索条件 |
| phone | String | O | 酒店电话。多个号码用逗号分隔。最大长度32字节。 | 结果展示 |
| aggregateRating | Float | O | 评分信息 | 检索条件 |
| boughtCount | Integer | O | 月销售量 | 结果排序参考 |
| comment | JOSNARRAY | O | 用户评论。最近的200条评论数据,不足200条评论则返回所有评论信息。 | 检索条件、结果排序参考 |
| status | String | O | 状态,如在售、已售完等。最大长度32字节。 | 检索条件 |
| h5Url | String | O | H5页面URL。最大长度512字节。 | 结果展示后的跳转引流,开发者自行提供卡片则无需提供该信息。 |
| webUrl | String | O | Web页面URL。最大长度512字节。 | 结果展示后的跳转引流,开发者自行提供卡片则无需提供该信息。 |
| appUrl | String | O | app页面跳转地址。最大长度512字节。 | 结果展示后的跳转引流,开发者自行提供卡片则无需提供该信息。 |
| refPoints | String | O | 酒店周边。最大长度64字节。 | 检索条件 |
| roomQuantity | Integer | O | 房间总数 | 检索条件 |
| offer | String | O | 优惠活动信息。最大长度64字节。 | 检索条件、结果展示 |
(3)Comment的结构体:
| 参数名 | 参数类型 | M/O | 参数描述 |
| comment | String | O | 评论信息。最大长度128字节。 |
| commentTime | String | O | 评论时间 |
(4)locationInfo的结构体:
| 参数名 | 参数类型 | M/O | 参数描述 |
| country | String | O | 国家名称 |
| province | String | O | 省份名称 |
| city | String | O | 城市名称 |
| district | String | O | 区名称 |
| town | String | O | 乡镇名称 |
| village | String | O | 村名称 |
| detail | String | O | 详细地址 |
| coordinateType | Integer | O | 坐标类型 0:大地坐标系WGS84 1:国家测绘局坐标GCJ02 2:百度坐标系BD09 |
| longitude | String | O | 经度 |
| latitude | String | O | 纬度 |
(5)ImageInfo的结构体:
| 参数名 | 参数类型 | M/O | 参数描述 |
| url | String | M | 图片url |
| height | Float | O | 图片高度 |
| width | Float | O | 图片宽度 |






































苏公安网备 32011402010933号