目录

优惠券

概述

商家在开展促销业务时所制作、投放的有效凭证,用户可以领取多种形式的优惠券后对原有商品/服务的价格进行减免。

Wallet Kit已提供优惠券接入华为钱包的能力,商户可通过多种方式轻松将卡券集成到华为钱包中。

流程概览

接入所需步骤:

步骤

分类

动作

用途说明

1

开发准备

配置AppGallery Connect

配置申请Wallet Kit相关服务。

2

安全组件申请

获取加密数据所需的秘钥或证书。

3

服务创建

创建Wallet Kit服务。

4

卡券接入

UI设计

开发者可以根据JSON串映射字段来定制界面显示内容。

卡券领取

开发者可以根据指导进行卡券领取操作。

卡券更新

开发者可以根据指导进行卡券更新操作。

处理过期卡券

卡券过期功能指导。

地理围栏通知

用户到达商户地理围栏附近时弹出通知栏提醒用户。

链接到已保存的卡券

链接到已添加的卡券详情。

优惠结束通知

优惠劵过期前提醒用户。

5

开发后自检

开发后自检

华为提供对应用自动检查的能力。

6

上架申请

上架申请

开发完成后需要在AppGallery Connect中将应用信息补充完整并提交上架申请。

如果想体验快速接入请参考codelab。

UI设计

[h2]字段定义

编号

名称

JSON串映射字段

规格

说明

1

外框背景色

fields.appendFields[key= backgroundColor]

长度:小于256字节

  1. 6位十六进制色值,以#开头,如#483D8B
  2. 为保证展示效果,建议使用深色

2

卡面背景色

-

-

  1. 固定为白色,非用户输入内容

3

卡面LOGO

fields.commonFields[key= logo]

图片规格:90*90px

大小:小于等于20kb

  1. Value传入图片URI
  2. URI需要为HTTPS地址

4

商户名称

fields.commonFields[key= merchantName]

长度:小于256字节

  1. Value传入默认取值
  2. Value支持多语言,在localizedValue设置字符串Id,并在fields.localized[key="字符串Id"]处设置各个语言的取值

5

优惠券标题

fields.commonFields[key= name]

长度:小于256字节

  1. Value传入默认取值
  2. Value支持多语言

6

优惠券副标题

fields.commonFields[key= subName]

长度:小于256字节

  1. Label字段已固定,商户不可更改
  2. Value支持多语言

7

有效期

fields.status.effectTime -fields.status.expireTime

长度:小于256字节

  1. Label字段已固定,商户不可更改
  2. Value传入UTC时间,格式为yyyy-MM-ddTHH:mm:ss.SSSZ

8

条形/二维码

fields.barCode.type

fields.barCode.value

长度:小于256字节

  1. type为codabar时,展示条形码,取值为qrCode展示二维码
  2. 取值为fields.barCode.value

9

备注说明

fields.barCode.text

长度:小于256字节

  1. 条形/二维码下内容

10

详情

fields.appendFields[key= details]

长度:小于256字节

  1. Label字段已固定,商户不可更改
  2. Value支持多语言

11

免责声明

fields.appendFields[key= declaration]

长度:小于256字节

  1. Label字段已固定,商户不可更改
  2. Value支持多语言

12

消息1

fields.messageList[key=key1]

长度:小于256字节

  1. Label支持多语言,必传不可为空
  2. Value支持多语言,必传不可为空
  3. key为用户自定义,此处只举例说明,非固定值

13

跳转列表1

fields.urlList[key=key1]

长度:小于256字节

  1. urlList中可设置商户跳转链接,如H5地址、快应用地址、Shcema地址,多条都可展示,跳转设置请参考UrlList跳转配置。
  2. key用户自定义,必传不可为空,urlList列表支持传入多个key不相同的对象
  3. Label支持多语言,必传不可为空
  4. type跳转类型,必传不可为空,支持URL,APP,FASTAPP
  5. Value跳转链接,必传不可为空,根据type类型设置

14

跳转列表2

fields.urlList[key=key2]

长度:小于256字节

  1. urlList中可设置商户跳转链接,如H5地址、快应用地址、Shcema地址,多条都可展示,跳转设置请参考UrlList跳转配置。
  2. key用户自定义,必传不可为空,urlList列表支持传入多个key不相同的对象
  3. Label支持多语言,必传不可为空
  4. type跳转类型,必传不可为空,支持URL,APP,FASTAPP
  5. Value跳转链接,必传不可为空,根据type类型设置

15

轮播图1

fields.imageList[key=key1]

长度:小于256字节

限制:长宽比3:1

  1. 多张图片时,在华为钱包详情页面自动轮播
  2. key用户自定义,必传不可为空,imageList列表支持传入多个key不相同的对象
  3. value资源地址需要为HTTPS地址,必传不可为空

[h2]卡面自定义

优惠券卡面可以展示二维码、条形码、二维码&条形码、使用按钮、优惠码五种,通过fields.commonFields[key= use_type]字段控制。

当进行如下配置时,展示优惠码。

{
    "commonFields": [
        {
            "key": "use_type",
            "value": "3"
        }
    ],
    "barCode": {
        "text": "",
        "type": "",
        "value": "1709874502",
        "encoding": "UTF-8"
    }
}

页面展示:

功能实现

[h2]卡券领取

场景

功能

实现方法

步骤

优惠券

通过网页、短信、Email、App应用内领取卡券

网页集成“添加到华为钱包”按钮领取卡券

  1. 开发者将卡券模板推送至华为服务器。
  2. 开发者将实例用密钥加密为JWE数据推送给用户。
说明:

模板:用户共有的字段信息,所有用户将共同享有模板信息字段,如logo、merchantName等。

用户特有信息(实例):用户特有的字段信息,如cardNumber。如果实例和模板中有相同字段则实例信息将覆盖模板信息内容。

短信/邮件跳转链接领取卡券

App应用集成Wallet Kit SDK后推送JWE数据到华为服务器

在App应用内集成Schema链接领取卡券

说明:

用户可以不登录华为帐号直接拉起华为钱包进行添卡操作。

开发场景介绍中定义的模板和用户特有信息实例是以会员卡为示例进行介绍,如商户需推送优惠券请按照下方给出的示例重新定义模板及用户特有信息实例。

推送模板信息至华为服务器。

接口定义请参考优惠券模板请求示例。

HwWalletObject字段定义请参考服务器API。

领取流程可参见添加卡券章节,因为添加卡券章节是以会员卡的数据作为示例提供,如需推送优惠券请参考下方提供的模型类和接口定义重新修改后推送。

HwWalletObject hwWalletObject = new HwWalletObject();  
hwWalletObject.setOrganizationName("xxx");
// 模板标识,唯一值
hwWalletObject.setPassStyleIdentifier("offer001");  
// 注册时的服务号
hwWalletObject.setPassTypeIdentifier("hwpass.offer.merchant");   
         
Fields fields = new Fields(); 
fields.setCountryCode("CN"); 
         
// 地理围栏信息 
List<Location> locationList = new ArrayList<>(); 
Location location = new Location(); 
location.setLongitude("113.0679603815"); 
location.setLatitude("25.6592051284"); 
locationList.add(location); 
fields.setLocationList(locationList); 
        
List<ValueObject> commonFields = new ArrayList<>();
ValueObject name = new ValueObject();
name.setKey("name");
name.setValue("50%-Off Coupon");
commonFields.add(name);
 
ValueObject subName = new ValueObject();
subName.setKey("subName");
subName.setValue("XXX Company");
commonFields.add(subName);
// 商户LOGO URI
ValueObject logo = new ValueObject();
logo.setKey("logo");
logo.setValue("https://www.xxx.com/.../logo.png"); 
commonFields.add(logo);
 
// 商户名称,含多语言样例,例如此处设置字符串id为merchantNameI18N,用于在Localized中获取对应语言取值进行展示
ValueObject merchantName = new ValueObject();
merchantName.setKey("merchantName");
merchantName.setValue("Some merchant name");
merchantName.setLocalizedValue("merchantNameI18N");
commonFields.add(merchantName);
fields.setCommonFields(commonFields);

// 背景颜色 
List<ValueObject> appendFields = new ArrayList<>();
ValueObject backgroundColor = new ValueObject();
backgroundColor.setKey("backgroundColor");
backgroundColor.setValue("#1C2635"); 
appendFields.add(backgroundColor);
 
ValueObject details = new ValueObject();
details.setKey("details");
details.setValue("Detail information of this coupon.");
appendFields.add(details);
 
ValueObject declaration = new ValueObject();
declaration.setKey("declaration");
declaration.setValue("Coupon disclaimer provided by merchant.");
appendFields.add(declaration);
// 推广图片 
List<ValueObject> imageList = new ArrayList<>();
ValueObject imagePic = new ValueObject();
imagePic.setKey("image1");
imagePic.setValue("https://www.xxx.com/.../banner.png"); 
imageList.add(imagePic);
fields.setImageList(imageList);
 
List<Localized> localizedList = new ArrayList<>();
// 商户中文名称,例如中文语言时,通过上面指定的字符串Id merchantNameI18N匹配到此Value用于展示
Localized merchantNameChinese = new Localized();
merchantNameChinese.setKey("merchantNameI18N");
merchantNameChinese.setLanguage("zh-CN");
merchantNameChinese.setValue("Merchant name in Chinese");
localizedList.add(merchantNameChinese);
fields.setLocalized(localizedList);
 
hwWalletObject.setFields(fields);

通过如下POST接口推送到华为服务器

POST 
https://{walletkit_server_url}/hmspass/v1/offer/model

定义用户特有信息的实例

接口定义请参考优惠劵模板请求示例。

HwWalletObject hwWalletObject = new HwWalletObject(); 
// 实例唯一标识,在模板下唯一
hwWalletObject.setSerialNumber("854687156");  
// 模板标识,唯一
hwWalletObject.setPassStyleIdentifier("Loyalty001"); 
hwWalletObject.setOrganizationPassId("1231");
// 注册时的服务号
hwWalletObject.setPassTypeIdentifier("hwpass.loyalty.merchant"); 
         
Fields fields = new Fields();
// 状态,有效期内的卡券才能推送到华为服务器
Status status = new Status();
status.setState("active");
status.setEffectTime("2019-11-11T00:00:00.000Z");
status.setExpireTime("2029-11-10T23:59:59.999Z");
fields.setStatus(status);
 
// 条形码/二维码
BarCode barCode = new BarCode();
barCode.setText("Refresh every ten minutes");
// setType的值为codabar或qrCode
barCode.setType("codabar"); 
barCode.setValue("829383819844342342");
fields.setBarCode(barCode);
 
hwWalletObject.setFields(fields);

[h2]卡券更新

请参考“调用华为服务器接口更新卡券”方式来实现卡券更新操作。

更新优惠券模板接口地址如下,请更换示例代码中的接口地址。

https://xxx/hmspass/v1/offer/model/{modelId}

更新优惠券用户特有信息的实例(Instance)接口地址如下,请更换示例代码中的接口地址。

https://xxx/hmspass/v1/offer/instance/{instanceId}

[h2]处理过期卡券

在钱包应用的卡券详情页下如果卡券已过期则会自动标记一个过期的Icon。如果卡券满足过期或无效中的一个条件,系统就会将其移至“过期卡券”部分。

在HwWalletObject.fields.status.expireTime过期后的 24 小时内,卡券会随时移至“过期卡券”。

HwWalletObject.fields.status.state字段标记为expired、inactive或completed。

[h2]地理围栏通知

当前地理围栏通知暂时只支持通过REST API方式添加的卡券。

地理围栏概念

基于华为定位能力,当商户开发者通过REST API接口在模板中设置LocationList时,当前卡券即具备了地理围栏通知的能力,当用户距离设定的目标200米范围内即可触发地理围栏通知。

每种卡券每天最多通知5次,超过次数当天不会再下发地理围栏通知。

使用REST API接口添加地理围栏目标点坐标

定义模板信息时商户可设置LocationList,每个模板LocationList最多可设置3个目标点。

HwWalletObject hwWalletObject = new HwWalletObject(); 
…..
// 地理围栏信息 
List<Location> locationList = new ArrayList<>(); 
Location location = new Location(); 
location.setLongitude("113.0679603815");
location.setLatitude("25.6592051284");
locationList.add(location); 
fields.setLocationList(locationList); 
……
hwWalletObject.setFields(fields);

[h2]链接到已保存的卡券

用户保存某张卡券后,钱包提供二种方式查看卡券。

[h2]优惠结束通知

华为钱包针对优惠券提供有优惠结束提醒,商户为卡券设置PassObject.Status.expireTime后华为钱包会在优惠结束24小时提醒用户优惠即将到期。

提醒会在00:00-06:00分静默,如果通知是在此时段内则会在静默时间前30分钟提醒。