商家在开展促销业务时所制作、投放的有效凭证,用户可以领取多种形式的优惠券后对原有商品/服务的价格进行减免。
Wallet Kit已提供优惠券接入华为钱包的能力,商户可通过多种方式轻松将卡券集成到华为钱包中。
接入所需步骤:
| 步骤 | 分类 | 动作 | 用途说明 |
|---|---|---|---|
| 1 | 开发准备 | 配置申请Wallet Kit相关服务。 | |
| 2 | 获取加密数据所需的秘钥或证书。 | ||
| 3 | 创建Wallet Kit服务。 | ||
| 4 | 卡券接入 | 开发者可以根据JSON串映射字段来定制界面显示内容。 | |
| 开发者可以根据指导进行卡券领取操作。 | |||
| 开发者可以根据指导进行卡券更新操作。 | |||
| 卡券过期功能指导。 | |||
| 用户到达商户地理围栏附近时弹出通知栏提醒用户。 | |||
| 链接到已添加的卡券详情。 | |||
| 优惠劵过期前提醒用户。 | |||
| 5 | 开发后自检 | 华为提供对应用自动检查的能力。 | |
| 6 | 上架申请 | 开发完成后需要在AppGallery Connect中将应用信息补充完整并提交上架申请。 |

| 编号 | 名称 | JSON串映射字段 | 规格 | 说明 |
|---|---|---|---|---|
| 1 | 外框背景色 | fields.appendFields[key= backgroundColor] | 长度:小于256字节 |
|
| 2 | 卡面背景色 | - | - |
|
| 3 | 卡面LOGO | fields.commonFields[key= logo] | 图片规格:90*90px 大小:小于等于20kb |
|
| 4 | 商户名称 | fields.commonFields[key= merchantName] | 长度:小于256字节 |
|
| 5 | 优惠券标题 | fields.commonFields[key= name] | 长度:小于256字节 |
|
| 6 | 优惠券副标题 | fields.commonFields[key= subName] | 长度:小于256字节 |
|
| 7 | 有效期 | fields.status.effectTime -fields.status.expireTime | 长度:小于256字节 |
|
| 8 | 条形/二维码 | fields.barCode.type fields.barCode.value | 长度:小于256字节 |
|
| 9 | 备注说明 | fields.barCode.text | 长度:小于256字节 |
|
| 10 | 详情 | fields.appendFields[key= details] | 长度:小于256字节 |
|
| 11 | 免责声明 | fields.appendFields[key= declaration] | 长度:小于256字节 |
|
| 12 | 消息1 | fields.messageList[key=key1] | 长度:小于256字节 |
|
| 13 | 跳转列表1 | fields.urlList[key=key1] | 长度:小于256字节 |
|
| 14 | 跳转列表2 | fields.urlList[key=key2] | 长度:小于256字节 |
|
| 15 | 轮播图1 | fields.imageList[key=key1] | 长度:小于256字节 限制:长宽比3:1 |
|
优惠券卡面可以展示二维码、条形码、二维码&条形码、使用按钮、优惠码五种,通过fields.commonFields[key= use_type]字段控制。
{
"commonFields": [
{
"key": "use_type",
"value": "0"
}
],
"barCode": {
"text": "barCode Text",
"type": "qrCode",
"value": "1700855542",
"encoding": "UTF-8"
}
} 页面展示:

{
"commonFields": [
{
"key": "use_type",
"value": "0"
}
],
"barCode": {
"text": "barCode Text",
"type": "codabar",
"value": "1700855542",
"encoding": "UTF-8"
}
} 页面展示:

{
"commonFields": [
{
"key": "use_type",
"value": "0"
}
],
"barCode": {
"text": "barCode Text",
"type": "qrCode|codabar",
"value": "1700855542",
"encoding": "UTF-8"
}
} 页面展示:

当进行如下配置时(配置请参见按钮跳转配置),展示使用按钮,点击使用按钮后支持APP页面跳转、H5跳转、快应用跳转。
页面展示:

当进行如下配置时,展示优惠码。
{
"commonFields": [
{
"key": "use_type",
"value": "3"
}
],
"barCode": {
"text": "",
"type": "",
"value": "1709874502",
"encoding": "UTF-8"
}
} 页面展示:

| 场景 | 功能 | 实现方法 | 步骤 |
|---|---|---|---|
| 优惠券 | 通过网页、短信、Email、App应用内领取卡券 |
说明: 模板:用户共有的字段信息,所有用户将共同享有模板信息字段,如logo、merchantName等。 用户特有信息(实例):用户特有的字段信息,如cardNumber。如果实例和模板中有相同字段则实例信息将覆盖模板信息内容。 | |
| 说明: 用户可以不登录华为帐号直接拉起华为钱包进行添卡操作。 |
开发场景介绍中定义的模板和用户特有信息实例是以会员卡为示例进行介绍,如商户需推送优惠券请按照下方给出的示例重新定义模板及用户特有信息实例。
推送模板信息至华为服务器。
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); 请参考“调用华为服务器接口更新卡券”方式来实现卡券更新操作。
更新优惠券模板接口地址如下,请更换示例代码中的接口地址。
https://xxx/hmspass/v1/offer/model/{modelId} 更新优惠券用户特有信息的实例(Instance)接口地址如下,请更换示例代码中的接口地址。
https://xxx/hmspass/v1/offer/instance/{instanceId} 在钱包应用的卡券详情页下如果卡券已过期则会自动标记一个过期的Icon。如果卡券满足过期或无效中的一个条件,系统就会将其移至“过期卡券”部分。
在HwWalletObject.fields.status.expireTime过期后的 24 小时内,卡券会随时移至“过期卡券”。
HwWalletObject.fields.status.state字段标记为expired、inactive或completed。
当前地理围栏通知暂时只支持通过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);
用户保存某张卡券后,钱包提供二种方式查看卡券。
https://{walletkit_website_url}/walletkit/consumer/pass/instance?issuerId=xxx&instanceId=xxxx 请求地址中的{walletkit_website_url}变量需要开发者根据服务器所属区域自行选择,列表如下:
| 地区 | 域名 |
|---|---|
| China | walletpass-drcn.cloud.huawei.com |
| Russia | walletpass-drru.cloud.huawei.com |
| Asia, Africa, and Latin America | walletpass-dra.cloud.huawei.com |
| Europe | walletpass-dre.cloud.huawei.com |

wallet://com.huawei.wallet/walletkit/consumer/pass/instance?issuerId=xxx&instanceId=xxxx