目录

每张卡券的内容分为两个部分,商户固定信息(模板)及用户特有信息(实例)。

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

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

商户将卡劵模板数据通过REST API接口推送到华为服务器,并在网页展示“添加到华为钱包”按钮,当用户点击时将卡劵实例的数据封装成JWE通过Wallet Kit服务与用户的华为账号绑定。用户可以在任意手机上登录该华为账号,并打开华为钱包App查看所绑定的卡券。用户删除卡券时,所有领取过此卡券的设备上都会同步删除。

用户点击“添加到华为钱包”按钮后,会发送包含用户特有信息的JWE实例到华为服务器。华为服务器收到后,关联模板,生成实际的卡券并与华为帐号关联,用户可以在华为钱包中查看此卡券。

具体步骤如下:

1 定义模板信息

抽取卡券信息中通用的商户信息作为模板。

  1. HwWalletObject hwWalletObject = new HwWalletObject();

  2. //HwWalletObject可以在服务器示例代码中查看具体定义。

  3. hwWalletObject.setFormatVersion("10.0");

  4. hwWalletObject.setOrganizationName("xxxx");

  5. hwWalletObject.setPassStyleIdentifier("Loyalty001"); // 模板标识,唯一值
  6. hwWalletObject.setPassTypeIdentifier("hwpass.loyalty.merchant"); // 注册时的服务号
  7. hwWalletObject.setWebServiceURL("https://www.xxx.com"); // 用户领取卡券时的回调地址


  8. Fields fields = new Fields();
  9. fields.setCountryCode("CN");
  10. // 地理围栏信息
  11. List<Location> locationList = new ArrayList<>();
  12. Location location = new Location();
  13. location.setLongitude("11x.0679603815");
  14. location.setLatitude("2x.6592051284");
  15. locationList.add(location);
  16. fields.setLocationList(locationList);
  17. List<CommonFields> commonFields = new ArrayList<>();
  18. CommonFields cardImage = new CommonFields();
  19. cardImage.setKey("backgroundImage");
  20. cardImage.setValue("https://www.xxx.com/.../cardImage.png"); // 商户会员卡卡面图片URI
  21. commonFields.add(cardImage);
  22. CommonFields logo = new CommonFields();
  23. logo.setKey("logo");
  24. logo.setValue("https://www.xxx.com/.../logo.png"); // 商户LOGO URI
  25. commonFields.add(logo);
  26. // 商户名称,含多语言样例,例如此处设置字符串id为merchantNameI18N,用于在Localized中获取对应语言取值进行展示
  27. CommonFields merchantName = new CommonFields();
  28. merchantName.setKey("merchantName");
  29. merchantName.setValue("Some merchant name");
  30. merchantName.setLocalizedValue("merchantNameI18N");
  31. commonFields.add(merchantName);
  32. // 卡片名称
  33. CommonFields name = new CommonFields();
  34. name.setKey("name");
  35. name.setValue("Loyalty Card");
  36. commonFields.add(name);
  37. fields.setCommonFields(commonFields);
  38. List<AppendFields> appendFields = new ArrayList<>();
  39. AppendFields nearbyLocations = new AppendFields();
  40. nearbyLocations.setKey("nearbyLocations");
  41. nearbyLocations.setValue("https://www.xxx.com/.../nearbyLocation.html"); // 附近门店地址URI
  42. nearbyLocations.setLabel("Nearby Locations");
  43. appendFields.add(nearbyLocations);
  44. AppendFields website = new AppendFields();
  45. website.setKey("website");
  46. website.setValue("https://www.xxx.com/.../merchantMainPage.html"); // 商户主页URI
  47. website.setLabel("Website");
  48. appendFields.add(website);
  49. AppendFields hotline = new AppendFields();
  50. hotline.setKey("hotline");
  51. hotline.setValue("400820XXXX"); // 商户热线
  52. hotline.setLabel("Hotline");
  53. appendFields.add(hotline);
  54. fields.setAppendFields(appendFields);
  55. List<ValueObject> imageList = new ArrayList<>();
  56. ValueObject imagePic = new ValueObject();
  57. imagePic.setValue("https://www.xxx.com/.../banner.png"); // 推广图片
  58. imageList.add(imagePic);
  59. fields.setImageList(imageList);
  60. List<Localized> localizedList = new ArrayList<>();
  61. // 商户中文名称,例如中文语言时,通过上面指定的字符串Id merchantNameI18N匹配到此Value用于展示
  62. Localized merchantNameChinese = new Localized();
  63. merchantNameChinese.setKey("merchantNameI18N");
  64. merchantNameChinese.setLanguage("zh-CN");
  65. merchantNameChinese.setValue("Merchant name in Chinese");
  66. localizedList.add(merchantNameChinese);
  67. // 商户英文名称,例如英文语言时,通过上面指定的字符串Id merchantNameI18N匹配到此Value用于展示
  68. Localized merchantNameEnglish = new Localized();
  69. merchantNameEnglish.setKey("merchantNameI18N");
  70. merchantNameEnglish.setLanguage("en-GB");
  71. merchantNameEnglish.setValue("Merchant name in English");
  72. localizedList.add(merchantNameEnglish);
  73. fields.setLocalized(localizedList);
  74. hwWalletObject.setFields(fields);

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

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

备注:请求地址中的{walletkit_server_url}变量需要开发者根据服务器所属区域自行选择,如果商户有全球发卡需求,因为隐私政策,不同区域的数据不能共享。建议商户向下列所有区域推送JWE数据, 参考钱包服务器地址列表。

China

passentrust-drcn.wallet.hicloud.com

Russia

passentrust-drru.wallet.hicloud.com

Asia, Africa, and Latin America

passentrust-dra.wallet.hicloud.com

Europe

passentrust-dre.wallet.hicloud.com

推送hwWalletObject代码如下:

  1. boolean validateClass = HwWalletObjectUtil.validateHwWalletObjectClass(hwWalletObject);
  2. if (validateClass) {
  3. // post hwWalletObject to Huawei server
  4. WalletBuildService walletBuildService = new WalletBuildServiceImpl();
  5. HwWalletObject loyaltyClass = walletBuildService.postHwWalletClassToWalletServer("loyalty/model", hwWalletObject);
  6. }

2 集成“添加到华为钱包”按钮

在网页中增加如下脚本,展示“添加到华为钱包”按钮。

  1. <script src="savetohuaweipay.min.js"></script>

JS文件下载:savetohuaweipay.zip

加入如下标记,用于传入JWE内容,在用户点击按钮时作为参数。

  1. <hw-savetohuaweipay jwt="{jwt_content}" theme="light"></hw-savetohuaweipay>

网页上会出现“添加到华为钱包”按钮。

3 生成JWE并发送到华为服务器

用户点击“添加到华为钱包”按钮时,生成包含用户特有信息的对象。

生成用户特有信息的实例前请先将模板推送至华为服务器,并在用户特有信息的实例中传入模板唯一标识PassStyleIdentifier。

  1. HwWalletObject hwWalletObject = new HwWalletObject();
  2. hwWalletObject.setSerialNumber("854687156"); // 对象唯一标识,在模板下唯一

  3. hwWalletObject.setPassStyleIdentifier("Loyalty001"); // 模板标识,唯一

  4. //实例唯一标识,在模板下唯一,如果未在fields.commonFields[key= cardNumber]定义则钱包详情页将取OrganizationPassId作为卡号

  5. hwWalletObject.setOrganizationPassId("1231");

  6. hwWalletObject.setPassTypeIdentifier("hwpass.loyalty.merchant"); // 注册时的服务号


  7. Fields fields = new Fields();

  8. // 状态,失效的不能添加
  9. Status status = new Status();
  10. status.setState("active");
  11. status.setEffectTime("2019-11-11T00:00:00.000Z");
  12. status.setExpireTime("2029-11-10T23:59:59.999Z");
  13. fields.setStatus(status);
  14. // 关联优惠券,填入关联优惠券的模板和对象标识
  15. List<LinkedPassId> relatedPassIds = new ArrayList<>();
  16. LinkedPassId linkedCoupon = new LinkedPassId();
  17. linkedCoupon.setTypeId("Coupon template id");
  18. linkedCoupon.setId("Coupon instance id");
  19. relatedPassIds.add(linkedCoupon);
  20. fields.setRelatedPassIds(relatedPassIds);
  21. // 条形码/二维码
  22. BarCode barCode = new BarCode();
  23. barCode.setText("Refresh every ten minutes");
  24. barCode.setType("codabar"); // codabar or qrCode
  25. barCode.setValue("829383819844342342");
  26. fields.setBarCode(barCode);
  27. List<CommonFields> commonFields = new ArrayList<>();
  28. // 会员名称,含多语言样例
  29. CommonFields memberName = new CommonFields();
  30. memberName.setKey("memberName");
  31. memberName.setValue("Member name");
  32. memberName.setLocalizedValue("memberName18N");
  33. commonFields.add(memberName);
  34. // 卡号
  35. CommonFields cardNumber = new CommonFields();
  36. cardNumber.setKey("cardNumber");
  37. cardNumber.setValue("4527809736");
  38. commonFields.add(cardNumber);
  39. fields.setCommonFields(commonFields);
  40. List<AppendFields> appendFields = new ArrayList<>();
  41. // 会员积分
  42. AppendFields points = new AppendFields();
  43. points.setKey("points");
  44. points.setLabel("Points");
  45. points.setValue("1299");
  46. appendFields.add(points);
  47. AppendFields balance = new AppendFields();
  48. balance.setKey("balance");
  49. balance.setValue("$19");
  50. balance.setLabel("Balance");
  51. appendFields.add(balance);
  52. // 等级
  53. AppendFields level = new AppendFields();
  54. rewardsLevel.setKey("level");
  55. level.setValue("Gloden");
  56. level.setLabel("Level");
  57. appendFields.add(level);
  58. fields.setAppendFields(appendFields);
  59. List<Localized> localizedList = new ArrayList<>();
  60. // 会员中文名称
  61. Localized memberNameChinese = new Localized();
  62. memberNameChinese.setKey("memberName18N");
  63. memberNameChinese.setLanguage("zh-CN");
  64. memberNameChinese.setValue("Member name in Chinese");
  65. localizedList.add(memberNameChinese);
  66. // 会员英文名称
  67. Localized memberNameEnglish = new Localized();
  68. memberNameEnglish.setKey("memberName18N");
  69. memberNameEnglish.setLanguage("en-GB");
  70. memberNameEnglish.setValue("Member name in English");
  71. localizedList.add(memberNameEnglish);
  72. fields.setLocalized(localizedList);
  73. hwWalletObject.setFields(fields);

采用JWE格式生成数据,总共分为5段,sessionKey和IV部分建议每次动态变换。。

以下代码中引用但未实现的类(“CommonUtil”,“RandomUtils”,“JweUtil”)均可以在服务器示例代码中查看具体定义。

  1. // 在华为AppGallery Connect网站上注册的应用ID。
  2. String appId = "Replace with your app ID";
  3. //生成一个新的实例并将其绑定到用户,示例代码中使用直接读取json文件的形式来设置Instance,商户接入时建议使用定义HwWalletObject形式来生成JWE数据
  4. //HwWalletObject可以在服务器示例代码中查看具体定义。
  5. //String newInstanceJson = CommonUtil.readWalletObject("LoyaltyInstance.json");
  6. String newInstanceJson = CommonUtil.toJson(hwWalletObject);
  7. JSONObject newInstanceJsonObject = JSONObject.parseObject(newInstanceJson);
  8. newInstanceJsonObject.put("iss", appId);
  9. //生成会话密钥以加密有效载荷数据。 会话密钥是一串随机的十六进制数字。  
  10. String sessionKey = RandomUtils.generateSecureRandomFactor(16);
  11. System.out.println("sessionKey: " + sessionKey);
  12. //华为固定的公开密钥,用于加密会话密钥。
  13. String sessionKeyPublicKey =        "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAgBJB4usbO33Xg5vhJqfHJsMZj44f7rxpjRuPhGy37bUBjSLXN+dS6HpxnZwSVJCtmiydjl3Inq3Mzu4SCGxfb9RIjqRRfHA7ab5p3JnJVQfTEHMHy8XcABl6EPYIJMh26kztPOKU2Mkn6yhRaCurhVUD3n9bD8omiNrR4rg442AJlNamA7vgKs65AoqBuU4NBkGHg0VWWpEHCUx/xyX6hIwqc1aD7P2f62ZHsKpNZBOek/riWhaVx3dTAa9ZS+Av3IGLOZiplhYIow9f8dlWyqs8nff9FZoJO03QhXLvOORT+lPAkW6gFzaoeMaGb40HakkZn3uvlAEKrKrtR0rZEok+N1hnboaAu8oaKK0rF1W6iNrXcFrO0rcrCsFTVF8qCa/1dFmIXwUd2M6cUzT9W0YkNyb6ZBbwEhjwBL4DNW4JfeF2Dzj0eZYlSuYV7e7e1e+XEO8lwPLAiy4bEFAWCaeuDVIhbIoBaU6xHNVQoyzct98gaOYxE4mVDqAUVmhfAgMBAAE=";
  14. //您在AGC上申请服务时生成了一对密钥。在此使用该私钥。
  15. String jweSignPrivateKey = "Replace with your private key.";
  16. //生成JWE
  17. String jweStrByInstanceIds = JweUtil.generateJwe(sessionKey, jweSignPrivateKey,newInstanceJsonObject.toJSONString(), sessionKeyPublicKey);

JWE数据需要经过URLEncoder.encode(jweStrByInstanceIds, StandardCharsets.UTF_8.toString())编码。

编码后的内容拼接Https链接作为参数发送即可。注意携带JWE的链接长度需控制在2000以内。Https链接样例如下:

  1. https://{walletkit_website_url}/walletkit/consumer/pass/save?jwt={jwt_content}

备注:请求地址中的{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