合作咨询
我们的专家服务团队将竭诚为您提供专业的合作咨询服务
如果想体验快速接入请参考codelab。
登机牌
本文导读
概述
登机牌即在用户购买机票后所产生的电子登机凭据，用户添加登机牌后可以实时获取到航班动态。
Wallet Kit已提供登机牌接入华为钱包的能力，商户可通过多种方式轻松将卡券集成到华为钱包中。
流程概览
接入所需步骤：
| 步骤 | 分类 | 动作 | 用途说明 |
|---|---|---|---|
| 1 | 开发准备 | 配置申请Wallet Kit相关服务。 | |
| 2 | 获取加密数据所需的秘钥或证书。 | ||
| 3 | 创建Wallet Kit服务。 | ||
| 4 | 卡券接入 | 开发者可以根据JSON串映射字段来定制界面显示内容。 | |
| 开发者可以根据指导进行卡券领取操作。 | |||
| 开发者可以根据指导进行卡券更新操作。 | |||
| 卡券过期功能指导。 | |||
| 链接到已添加的卡券详情。 | |||
| 用户领取卡券后可通过此能力在同一帐号下的多设备中共享此卡券。 | |||
| 航班起飞前提醒用户。 | |||
| 航班登机口变更时提醒用户。 | |||
| 航班起飞时间变更提醒用户。 | |||
| 航班登机时间变更提醒用户。 | |||
| 5 | 开发后自检 | 华为提供对应用自动检查的能力。 | |
| 6 | 上架申请 | 开发完成后需要在AppGallery Connect中将应用信息补充完整并提交上架申请。 |
说明
UI设计
| 编号 | 名称 | 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.timeList.[key= departureTime] or fields.timeList.[key= scheduledDepartureTime] | 长度：小于256字节 |
|
| 6 | 到达时间 | fields.timeList.[key= arrivalTime] or fields.timeList.[key= scheduledArrivalTime] | 长度：小于256字节 |
|
| 7 | 出发航站楼 | fields.commonFields[key= departureTerminal] | 长度：小于256字节 |
|
| 8 | 出发城市 | fields.commonFields[key= departureCity] | 长度：小于256字节 |
|
| 9 | 到达航站楼 | fields.commonFields[key= arrivalTerminal] | 长度：小于256字节 |
|
| 10 | 到达城市 | fields.commonFields[key= arrivalCity] | 长度：小于256字节 |
|
| 11 | 航班号 | fields.commonFields[key= flightNumber] | 长度：小于256字节 |
|
| 12 | 登机口 | fields.commonFields[key= boardingGate] | 长度：小于256字节 |
|
| 13 | 乘机人 | fields.commonFields[key= passengerName] | 长度：小于256字节 |
|
| 14 | 起飞日期 | fields.timeList.[key= departureTime] or fields.timeList.[key= scheduledDepartureTime] | 长度：小于256字节 |
|
| 15 | 登机时间 | fields.timeList.[key= boardingTime] | 长度：小于256字节 |
|
| 16 | 座位号 | fields.commonFields[key= seatNumber] | 长度：小于256字节 |
|
| 17 | 条形/二维码 | fields.barCode.type fields.barCode.value | 长度：小于256字节 |
|
| 18 | 备注说明 | fields.barCode.text | 长度：小于256字节 |
|
| 19 | 仓位等级 | fields.commonFields[key= flightClass] | 长度：小于256字节 |
|
| 20 | 登机序号 | fields.commonFields[key= boardingSequence] | 长度：小于256字节 |
|
| 21 | 确认码 | fields.appendFields[key= confirmationNumber] | 长度：小于256字节 |
|
| 22 | 预计起飞日期 | fields.timeList.[key= scheduledDepartureTime] | 长度：小于256字节 |
|
| 23 | 预计到达时间 | fields.timeList.[key= scheduledArrivalTime] | 长度：小于256字节 |
|
| 24 | 到达登机口 | fields.commonFields[key= arrivalGate] | 长度：小于256字节 |
|
| 25 | 消息1 | fields.messageList[key=key1] | 长度：小于256字节 |
|
| 26 | 跳转列表1 | fields.urlList[key=key1] | 长度：小于256字节 |
|
| 27 | 跳转列表2 | fields.urlList[key=key2] | 长度：小于256字节 |
|
| 28 | 轮播图 | fields.imageList | 长度：小于256字节 限制：长宽比3：1 |
|
功能实现
卡券领取
Wallet Kit提供两种卡券领取方式，商户开发者可根据接入方式的媒介来选择适合自己的接入方式。
| 场景 | 功能 | 实现方法 | 步骤 |
|---|---|---|---|
| 登机牌 | 通过网页、短信、Email、App应用内领取卡券 |
说明 模板：用户共有的字段信息，所有用户将共同享有模板信息字段，如logo、merchantName等。 用户特有信息（实例）：用户特有的字段信息，如cardNumber。如果实例和模板中有相同字段则实例信息将覆盖模板信息内容。 | |
| 说明 用户可以不登录华为帐号直接拉起华为钱包进行添卡操作。 | |||
| App应用内、快应用、华为钱包CardStore方式领取卡券 说明 此方式当前仅支持中国大陆区域。 |
| ||
- 网页、短信、Email、App应用内领取卡券
开发场景介绍中定义的模板和用户特有信息实例是以会员卡为示例进行介绍，如商户需推送登机牌请按照下方给出的示例重新定义模板及用户特有信息实例。
推送模板信息至华为服务器
- HwWalletObject hwWalletObject = new HwWalletObject();
- hwWalletObject.setOrganizationName("xxx");
- // 模板标识，唯一值
- hwWalletObject.setPassStyleIdentifier("flight001");
- // 注册时的服务号
- hwWalletObject.setPassTypeIdentifier("hwpass.flight.merchant");
- Fields fields = new Fields();
- fields.setCountryCode("CN");
- List<ValueObject> commonFields = new ArrayList<>();
- ValueObject flightNumber = new ValueObject();
- flightNumber.setKey("flightNumber");
- flightNumber.setValue("MU2887");
- commonFields.add(flightNumber);
- ValueObject departureTerminal = new ValueObject();
- departureTerminal.setKey("departureTerminal");
- departureTerminal.setValue("T2");
- commonFields.add(departureTerminal);
- // 商户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);
- ValueObject boardingGate = new ValueObject();
- boardingGate.setKey("boardingGate");
- boardingGate.setValue("45");
- commonFields.add(boardingGate);
- ValueObject departureCity = new ValueObject();
- departureCity.setKey("departureCity");
- departureCity.setValue("Some merchant name");
- commonFields.add(departureCity);
- ValueObject arrivalTerminal = new ValueObject();
- arrivalTerminal.setKey("arrivalTerminal");
- arrivalTerminal.setValue("T3");
- commonFields.add(arrivalTerminal);
- ValueObject arrivalCity = new ValueObject();
- arrivalCity.setKey("arrivalCity");
- arrivalCity.setValue("shenzhen");
- commonFields.add(arrivalCity);
- fields.setCommonFields(commonFields);
- // 背景颜色
- List<ValueObject> appendFields = new ArrayList<>();
- ValueObject backgroundColor = new ValueObject();
- backgroundColor.setKey("backgroundColor");
- backgroundColor.setValue("#1C2635");
- appendFields.add(backgroundColor);
- fields.setAppendFields(appendFields);
- // 推广图片
- List<ValueObject> imageList = new ArrayList<>();
- ValueObject imagePic = new ValueObject();
- imagePic.setValue("https://www.xxx.com/.../banner.png");
- imageList.add(imagePic);
- fields.setImageList(imageList);
- List<ValueObject> timeList = new ArrayList<>();
- ValueObject time = new ValueObject();
- time.setKey("departureTime");
- time.setValue("2020-05-09T10:30:00.010Z");
- timeList.add(time);
- fields.setTimeList(timeList);
- 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/flight/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);
- List<ValueObject> commonFields = new ArrayList<>();
- ValueObject seatNumber = new ValueObject();
- seatNumber.setKey("seatNumber");
- seatNumber.setValue("12A");
- commonFields.add(seatNumber);
- ValueObject passengerName = new ValueObject();
- passengerName.setKey("passengerName");
- passengerName.setValue("Wang Xiao");
- commonFields.add(passengerName);
- ValueObject boardingSequence = new ValueObject();
- boardingSequence.setKey("boardingSequence");
- boardingSequence.setValue("1");
- commonFields.add(boardingSequence);
- ValueObject boardingSequence = new ValueObject();
- boardingSequence.setKey("flightClass");
- boardingSequence.setValue("First Class");
- commonFields.add(boardingSequence);
- // 商户名称，含多语言样例，例如此处设置字符串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 confirmationNumber = new ValueObject();
- confirmationNumber.setKey("confirmationNumber");
- confirmationNumber.setValue("#ITK919"); // 背景颜色
- appendFields.add(confirmationNumber);
- fields.setAppendFields(appendFields);
- hwWalletObject.setFields(fields);
卡券更新
- 网页、短信、Email、App应用内方式更新卡券
请参见“调用华为服务器接口更新卡券”章节来实现卡券更新操作。
更新登机牌模板接口地址如下，请更换示例代码中的接口地址。
- https://xxx/hmspass/v1/flight/model/{modelId}
更新登机牌用户特有信息的实例（Instance）接口地址如下，请更换示例代码中的接口地址。
- https://xxx/hmspass/v1/flight/instance/{instanceId}
- App应用内、快应用、华为钱包CardStore方式领取卡券
如果需要更新卡券请参考“商户服务器实现接口更新卡券”方式来实现卡券更新操作。
说明此方式当前仅支持中国大陆区域。
处理过期卡券
在钱包应用的卡券详情页下如果卡券已过期则会自动标记一个过期的Icon。如果卡券满足过期或无效中的一个条件，系统就会将其移至“过期卡券”部分。
在HwWalletObject.fields.status.expireTime过期后的 24 小时内，卡券会随时移至“过期卡券”。
HwWalletObject.fields.status.state字段标记为expired、inactive或completed。
链接到已保存的卡券
用户保存某张卡券后，钱包提供二种方式查看卡券。
- 浏览器方式查看卡券
- 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
说明- 如果用户手机安装了华为钱包应用，且当前方式使用Intent加载时会弹出选择框给用户，用户可选择用钱包或者浏览器加载此链接。
- instanceId：卡券实例Id。
- issuerId：对应华为开发者联盟网站上AppId，请参见下图。
- 跳转钱包详情查看卡券（需要安装钱包才可访问）
- wallet://com.huawei.wallet/walletkit/consumer/pass/instance?issuerId=xxx&instanceId=xxxx
跨设备同步能力
当前能力只开放给通过“App应用内、快应用、华为钱包CardStore方式”添加的卡券。
通过卡券包添加时卡片是以端到端的形式将卡券保存到华为钱包，华为服务器没有保存用户推送的卡券，所以无法做到帐号间共享。如果商户需要实现帐号间共享卡券能力则需要实现Wallet Kit提供的托管能力。
- 在开发者联盟开放跨设备同步能力。
在“服务创建”章节配置应用数据时可以选择是否开放跨设备同步能力，此时商户如果想实现此功能则需要开通此服务。
- 实现下载卡券包接口。
商户打开跨设备同步能力后，当商户推送卡券到华为钱包时，华为钱包会将卡券部分信息托管至华为服务器（只上传下载卡券的部分信息）。当用户在当前帐号下的其他设备登录时，华为钱包应用会去商户服务器下载已领取过的卡券包，商户服务器需实现“商户服务器实现接口更新卡券”步骤供华为钱包调用下载卡券包。
起飞提醒通知
华为钱包针对登机牌提供有起飞前提醒，商户为卡券设置PassObject.fields.timeList.scheduledDepartureTime.value后华为钱包会在起飞前4小时提醒用户。
提醒会在00:00-06:00分静默，如果通知是在此时段内则会在静默时间前30分钟提醒。
登机口变更通知
华为钱包针对登机牌提供有登机口变更提醒，商户为卡券设置PassObject.fields.commonFiled.boardingGate.value后华为钱包会在登机口变更时立即提醒用户。
提醒会在00:00-06:00分静默，如果通知是在此时段内则会在静默时间前30分钟提醒。
起飞时间变更通知
华为钱包针对登机牌提供有起飞时间变更提醒，商户为卡券设置PassObject.fields.timeList.departureTime.value后华为钱包会在起飞时间变更时立即提醒用户。
提醒会在00:00-06:00分静默，如果通知是在此时段内则会在静默时间前30分钟提醒。
登机时间变更通知
华为钱包针对登机牌提供有登机时间变更提醒，商户为卡券设置PassObject.fields.timeList.boardingTime.value后华为钱包会在登机时间变更时立即提醒用户。
提醒会在00:00-06:00分静默，如果通知是在此时段内则会在静默时间前30分钟提醒。