目录

You can add a button to your app. When a user taps the button, a WebView page is displayed, and your server sends a JWE to the Huawei server through an intent to obtain and display the pass claiming result.

The procedure is as follows:

1 Define a Template

Define a template of common merchant information about all passes. The following uses loyalty cards of a merchant as an example.

  1. HwWalletObject hwWalletObject = new HwWalletObject(); 
  2. hwWalletObject.setPassVersion("10.0"); 
  3. hwWalletObject.setOrganizationName("xxx");
  4. hwWalletObject.setPassStyleIdentifier("Loyalty001"); // Template ID, which is unique. 
  5. hwWalletObject.setPassTypeIdentifier("hwpass.loyalty.merchant"); // Service ID specified during service registration. 
  6. hwWalletObject.setWebServiceURL("https://www.xxx.com"); // Callback URL used when a user claims a loyalty card. 
  7. Fields fields = new Fields(); 
  8. fields.setCountryCode("CN"); 
  9. // Geofence information. 
  10. List<Location> locationList = new ArrayList<>(); 
  11. Location location = new Location(); 
  12. location.setLongitude("11x.0679603815"); 
  13. location.setLatitude("2x.6592051284"); 
  14. locationList.add(location); 
  15. fields.setLocationList(locationList); 
  16. List<CommonFields> commonFields = new ArrayList<>(); 
  17. CommonFields cardImage = new CommonFields(); 
  18. cardImage.setKey("backgroundImage"); 
  19. cardImage.setValue("https://www.xxx.com/.../cardImage.png"); // URI of the background image of a loyalty card issued by the merchant. 
  20. commonFields.add(cardImage); 
  21. CommonFields logo = new CommonFields(); 
  22. logo.setKey("logo"); 
  23. logo.setValue("https://www.xxx.com/.../logo.png"); // URI of the merchant's logo. 
  24. commonFields.add(logo); 
  25. // Merchant name. The following provides sample code for defining merchant names in multiple languages. You can specify a random string here, for example, merchantNameI18N, for obtaining the merchant name in the corresponding language from the value of Localized. 
  26. CommonFields merchantName = new CommonFields(); 
  27. merchantName.setKey("merchantName"); 
  28. merchantName.setValue("Some merchant name"); 
  29. merchantName.setLocalizedValue("merchantNameI18N"); 
  30. commonFields.add(merchantName); 
  31. // Loyalty card name. 
  32. CommonFields name = new CommonFields(); 
  33. name.setKey("name"); 
  34. name.setValue("Loyalty Card"); 
  35. commonFields.add(name); 
  36. fields.setCommonFields(commonFields); 
  37. List<AppendFields> appendFields = new ArrayList<>(); 
  38. AppendFields nearbyLocations = new AppendFields(); 
  39. nearbyLocations.setKey("nearbyLocations"); 
  40. nearbyLocations.setValue("https://www.xxx.com/.../nearbyLocation.html"); // URI of the page listing nearby stores of the merchant. 
  41. nearbyLocations.setLabel("Nearby Locations"); 
  42. appendFields.add(nearbyLocations); 
  43. AppendFields website = new AppendFields(); 
  44. website.setKey("website"); 
  45. website.setValue("https://www.xxx.com/.../merchantMainPage.html"); // URI of the merchant's main page. 
  46. website.setLabel("Website"); 
  47. appendFields.add(website); 
  48. AppendFields hotline = new AppendFields(); 
  49. hotline.setKey("hotline"); 
  50. hotline.setValue("400820XXXX"); // Merchant's hotline. 
  51. hotline.setLabel("Hotline"); 
  52. appendFields.add(hotline); 
  53. fields.setAppendFields(appendFields); 
  54. List<ValueObject> imageList = new ArrayList<>(); 
  55. ValueObject imagePic = new ValueObject(); 
  56. imagePic.setValue("https://www.xxx.com/.../banner.png"); // Promotion image. 
  57. imageList.add(imagePic); 
  58. fields.setImageList(imageList); 
  59. List<Localized> localizedList = new ArrayList<>(); 
  60. // Merchant name in Chinese, which can be obtained based on the previously specified string merchantNameI18N. 
  61. Localized merchantNameChinese = new Localized(); 
  62. merchantNameChinese.setKey("merchantNameI18N"); 
  63. merchantNameChinese.setLanguage("zh-CN"); 
  64. merchantNameChinese.setValue("Merchant name in Chinese"); 
  65. localizedList.add(merchantNameChinese); 
  66. // Merchant name in English, which can be obtained based on the previously specified string merchantNameI18N. 
  67. Localized merchantNameEnglish = new Localized(); 
  68. merchantNameEnglish.setKey("merchantNameI18N"); 
  69. merchantNameEnglish.setLanguage("en-GB"); 
  70. merchantNameEnglish.setValue("Merchant name in English"); 
  71. localizedList.add(merchantNameEnglish); 
  72. fields.setLocalized(localizedList); 
  73. hwWalletObject.setFields(fields);

Push the template to the Huawei server through the following REST API using POST:

  1. POST 
  2. https://{walletkit_server_url}/hmspass/v1/loyalty/model

Note: You need to replace {walletkit_server_url} in the preceding URL based on the region to which the server belongs. For privacy considerations, data of a region is kept within the region. It is recommended that you push the JWE to all of the following regions.For details, please refer to Wallet Server Address.

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

The code for pushing hwWalletObject to the Huawei server is as follows:

  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 Adding the Add to HUAWEI Wallet Button

Add a button to your app. A tap on the button will start an activity via the ACTION_VIEW intent. You can add either of the following URIs to the button:

  1. hms://www.huawei.com/payapp/{jwt_content}

Or

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

Note: The former URI only applies to mobile phones with HMS Core (APK) installed. When the button is tapped, a page specified by HMS Core (APK) will be displayed, guiding the user to claim the card. The latter URI does not have such a restriction. It allows the user to claim the card by using a browser or the HUAWEI Wallet app that is installed on the user device.

3 Generating a JWT and Sending It to the Huawei Server

Generate an instance of a user's personalized information when a user taps the Add to HUAWEI Wallet button.

  1. HwWalletObject hwWalletObject = new HwWalletObject(); 
  2. hwWalletObject.setSerialNumber("854687156"); // Instance ID unique to the associated template. 
  3. hwWalletObject.setPassStyleIdentifier("Loyalty001"); // Template ID, which is unique.
  4. hwWalletObject.setPassTypeIdentifier("hwpass.loyalty.merchant"); // Service ID specified during service registration.
  5. hwWalletObject.setOrganizationPassId("1231")

  7. Fields fields = new Fields(); 
  8. // Loyalty card status, which cannot be specified for an expired loyalty card. 
  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. // Template IDs and instance IDs of coupons associated with the loyalty card. 
  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(relatedPassIdss); 
  21. // Barcode or QR code. 
  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. // Member name. The following provides sample code for defining member names in multiple languages. 
  29. CommonFields accountName = new CommonFields(); 
  30. accountName.setKey("accountName"); 
  31. accountName.setValue("Member name"); 
  32. accountName.setLocalizedValue("accountName18N"); 
  33. commonFields.add(accountName); 
  34. // Loyalty card number. 
  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. // Loyalty points. 
  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. // Loyalty level. 
  53. AppendFields level = new AppendFields(); 
  54. level.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. // Member name in Chinese. 
  61. Localized accountNameChinese = new Localized(); 
  62. accountNameChinese.setKey("accountName18N"); 
  63. accountNameChinese.setLanguage("zh-CN"); 
  64. accountNameChinese.setValue("Member name in Chinese"); 
  65. localizedList.add(accountNameChinese); 
  66. // Member name in English. 
  67. Localized accountNameEnglish = new Localized(); 
  68. accountNameEnglish.setKey("accountName18N"); 
  69. accountNameEnglish.setLanguage("en-GB"); 
  70. accountNameEnglish.setValue("Member name in English"); 
  71. localizedList.add(accountNameEnglish); 
  72. fields.setImageList(localizedList); 
  73. hwWalletObject.setFields(fields);

Convert the generated instance to a JWE, which consists of five parts:

Each part is Base64-encoded.

Note: It is recommended that you change the session key and IV each time.

Note: Classes CommonUtil, RandomUtils, and JweUtil are referenced but not implemented in the following code. For their definitions, please refer to Server Sample Code.

  1. // The app ID registered in AppGallery Connect. 
  2. String appId = "Replace with your app ID"; 
  3. // Create a loyalty card instance and link it to a user. 
  4. String newInstanceJson = CommonUtil.readWalletObject("LoyaltyInstance.json"); 
  5. JSONObject newInstanceJsonObject = JSONObject.parseObject(newInstanceJson); 
  6. newInstanceJsonObject.put("iss", appId); 
  7. // Generate a session key to encrypt payload data. A session key is a string of random hex numbers. 
  8. String sessionKey = RandomUtils.generateSecureRandomFactor(16); 
  9. System.out.println("sessionKey: " + sessionKey); 
  10. // The public key provided by Huawei, which is used to encrypt the session key. 
  11. String sessionKeyPublicKey = 
  12.           "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAgBJB4usbO33Xg5vhJqfHJsMZj44f7rxpjRuPhGy37bUBjSLXN+dS6HpxnZwSVJCtmiydjl3Inq3Mzu4SCGxfb9RIjqRRfHA7ab5p3JnJVQfTEHMHy8XcABl6EPYIJMh26kztPOKU2Mkn6yhRaCurhVUD3n9bD8omiNrR4rg442AJlNamA7vgKs65AoqBuU4NBkGHg0VWWpEHCUx/xyX6hIwqc1aD7P2f62ZHsKpNZBOek/riWhaVx3dTAa9ZS+Av3IGLOZiplhYIow9f8dlWyqs8nff9FZoJO03QhXLvOORT+lPAkW6gFzaoeMaGb40HakkZn3uvlAEKrKrtR0rZEok+N1hnboaAu8oaKK0rF1W6iNrXcFrO0rcrCsFTVF8qCa/1dFmIXwUd2M6cUzT9W0YkNyb6ZBbwEhjwBL4DNW4JfeF2Dzj0eZYlSuYV7e7e1e+XEO8lwPLAiy4bEFAWCaeuDVIhbIoBaU6xHNVQoyzct98gaOYxE4mVDqAUVmhfAgMBAAE="; 
  13. // The private key you obtained during service application in AppGallery Connect.  
  14. String jweSignPrivateKey = "Replace with your private key."; 
  15. // Generate a JWE. 
  16. String jweStrByInstanceIds = JweUtil.generateJwe(sessionKey, jweSignPrivateKey,newInstanceJsonObject.toJSONString(), sessionKeyPublicKey);

Send the encoded JWE to the Huawei server through an intent.

Note: The JWE must be encoded using URLEncoder.encode(jweStrByInstanceIds, StandardCharsets.UTF_8.toString()).

  1. Intent intent = new Intent(Intent.ACTION_VIEW); 
  2. intent.setData(Uri.parse("hms://www.huawei.com/payapp/{" + jwe_content + "}")); 
  3. try { 
  4.     startActivityForResult(intent, requestCode) 
  5. } catch (ActivityNotFoundException e) { 
  6. ... 
  7. } 
  8. Or 
  9. Intent intent = new Intent(Intent.ACTION_VIEW); 
  10. intent.setData(Uri.parse("https://{walletkit_website_url}/walletkit/consumer/pass/save?jwt={" + jwe_content + "}")); 
  11. try { 
  12.     startActivityForResult(intent, requestCode) 
  13. } catch (ActivityNotFoundException e) { 
  14. ... 
  15. }