Overview

HUAWEI Wallet Kit allows users to claim passes of merchants, including loyalty cards, gift cards, coupons, boarding passes, event tickets, and transit passes, and add them to HUAWEI Wallet. You can provide a button or link in your app for users to add passes to their HUAWEI Wallet and view and manage them.
You need to perform the following operations:

• Register an account on HUAWEI Developer. Create and configure an app and enable the HUAWEI Wallet Kit API in AppGallery Connect.
• Select and register HUAWEI Wallet Kit in the app, and configure a merchant service account and callback address. Use a tool to generate a public key and synchronize the key to the Huawei server.
• Create a project in Android Studio IDE and configure connection to the HMS Core Wallet SDK.
• Call the HUAWEI Wallet Kit API to push a template of merchant information to the Huawei server.
• Call and debug the HMS Core Wallet SDK. For details, please refer to "Integrating the HMS Core Wallet SDK" in the HUAWEI Wallet Kit Development Guide.

What You Will Create

In this codelab, you will use the created demo project to:
Call the HMS Core Wallet SDK to construct instances so that passes can be added to HUAWEI Wallet.

What You Will Learn

• Create an app in AppGallery Connect.
• Enable the HUAWEI Wallet Kit API.
• Call the HUAWEI Wallet Kit API to push a model to the Huawei server.
• Call the HUAWEI Wallet Kit API to send a pass instance to the Huawei server.
• Generate a JWE and add a pass to HUAWEI Wallet.

Hardware Requirements

• A computer (desktop or laptop) that runs Windows 10
• A Huawei mobile phone with Huawei Mobile Services (APK) 4.0.0.300 or later, which will be used for debugging and running the demo project

Software Requirements

• Java JDK (1.8.211 or later)
• IDEA or Eclipse
• Maven (3.4 or later)

To integrate HUAWEI Wallet Kit, you must complete the following preparations:

• Create an app in AppGallery Connect.
• Create an Android Studio project.
• Generate a signing certificate.
• Generate a signing certificate fingerprint.
• Configure the signing certificate fingerprint.
• Add the app package name and save the configuration file.
• Importing the JWE Sample Code into a Maven Project

For details, please refer to Preparations for Integrating HUAWEI HMS Core.

Enabling the HUAWEI Wallet Kit API

To use Wallet Kit services on your app, you first need to enable Wallet Kit services.
For details, please refer to Enabling Services.

Generating a Public-Private Key Pair

• Download the RSAUtils.zip package generated in the step of generating security keys in Applying for Security Components. Decompress the package and open the RSAUtils folder.
  
• Double-click the start.bat file.

• After the file is successfully executed, the path to the generated public and private key files is displayed. By default, the keys are in the out folder in the current path.

• The following figure displays files in the out folder.

Registering HUAWEI Wallet Kit

• Sign in to AppGallery Connect and go to My apps.

• Click the Develop tab and go to Earning > Wallet Kit from the navigation panel on the left. Click Apply for Wallet Kit in the upper right corner on the page displayed. For details about the application, please refer to Applying for the HUAWEI Wallet Kit Service.
  
• Configure basic service information, such as the service type, service ID, and callback URL, enter the public key, and click Next. Note that the value of Service ID is the value of passTypeIdentifier in the HUAWEI Wallet Kit API and will be used for creating models and saving passes.

Obtaining the Sample Code of the HUAWEI Wallet Kit API

• Download the demo source code from Java Sample Code and decompress it.

Setting Parameters

• Before running the sample code, you need to set the gw.appid, gw.appid.secret, gw.tokenUrl, and walletServerBaseUrl parameters in the src\test\resources\release.config.properties file.
• gw.appid and gw.appid.secret: correspond to the App ID and App secret parameters respectively of an app. Sign in to AppGallery Connect, click My apps, select the target app, and click App information. On the page displayed, you can find the App ID and App secret parameters of the app.
  
• gw.tokenUrl: Set it to https://oauth-login.cloud.huawei.com/oauth2/v3/token. This URL is used to obtain the authentication token of the RESTful API.
• walletServerBaseUrl: URL of the Huawei server. It is in the common part in an HTTP request of the RESTful API. The value of walletServerBaseUrl is in the format of https://{walletkit_server_url}/hmspass/v1/.
  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 sites. For details, please refer to the wallet server addresses.
  

  Site	Domain Name
  Chinese mainland	wallet-passentrust-drcn.cloud.huawei.com.cn
  Asia	wallet-passentrust-dra.cloud.huawei.asia
  Europe	wallet-passentrust-dre.cloud.huawei.eu
  Latin America	wallet-passentrust-dra.cloud.huawei.lat
  Russia	wallet-passentrust-drru.cloud.huawei.ru

Compiling the Sample Code with Maven

• After setting the preceding parameters, compile the sample code with Maven.
  
• Input parameters are configured in the model file (in JSON format) that is stored in src/test/resources/data. Before running the test method, ensure that the value of passTypeIdentifier in the JSON file is the same as that of Service ID set in Applying for the HUAWEI Wallet Kit Service.
  Mandatory parameters:
  

  Parameter	Description
  passVersion	Version number, which is defined yourself. Example: 1.0
  passTypeIdentifier	Service ID set in Applying for the HUAWEI Wallet Kit Service.
  passStyleIdentifier	Model ID, which is defined yourself. Example: loyaltyModelTest
  organizationName	Merchant name, which is defined yourself. Example: HUAWEI

Pushing a Model

• The Huawei server provides the Wallet Kit API, a RESTful API, for you to create a pass model. For example, you can call the HwLoyaltyModelTest.createLoyaltyModel method to create a loyalty card model using the API. The methods for creating the models of other types of passes are similar.
• In the sample code, model data is transferred through JSON files. You can modify these JSON files to push model data as required. The data type of all models is HwWalletObject. For details about its format, please refer to HwWalletObject Parameters.
• Now, you have enabled the HUAWEI Wallet Kit API and pushed the loyalty card model to the Huawei server.

Configuring Data

Input parameters are configured in the model file (in JSON format) that is stored in target/classes/hmspass. Before running the test method, ensure that the value of passTypeIdentifier in the JSON file is the same as that of Service ID set in Applying for the HUAWEI Wallet Kit Service.
Mandatory parameters:

Pushing the Pass Instance

Method 1: Generating a JWE containing complete pass instance information and sending the JWE to the Huawei server
Call the JweTest.generateJWEToAddInstanceAndBindUser method to push a new pass instance to the Huawei server. You need to enter the name of the pass instance JSON file to be read, the RSA private key generated in Applying for Security Components, and the link corresponding to the region where your server is located.

The following is a sample HTTPS link:
https://{walletkit_website_url}/walletkit/consumer/pass/save?jwt={jwe_content}

Note that the JWE contained in the link cannot exceed 2000 characters. If the JWE generated using this method is too long, use method 2 to generate a JWE.
Method 2: Using the server API to generate a pass instance and sending a thin JWE containing only the pass instance ID (serialNumber) to the Huawei server

1. The Huawei server provides the Wallet Kit API, a RESTful API, for you to create a pass model. For example, you can call the HwLoyaltyInstanceTest.addLoyaltyInstance method to create a loyalty card instance using the API. The methods for creating the instances of other types of passes are similar.
   
2. Call the JweTest.generateThinJWEToBindUser() method to send a thin JWE that contains only the pass instance ID (serialNumber). You need to enter the pass instance ID (serialNumber), RSA private key generated in Generating the Public and Private Keys, and link corresponding to the region to which the server belongs.
   

• Register a Huawei ID in your country or region. After you enter the verification code sent by the Huawei server, the registration is successful.

• Visit the link generated in 6 Generating and Pushing a JWE to the Huawei Server from your browser. You will be navigated to the sign-in page.
  
• After signing in, you will be navigated to the pass addition page. Click the ADD button to add the pass.
  
• After the pass is added, the VIEW button will be displayed. You can click the button to view the added pass. Or, you can sign in to the HUAWEI Wallet app and view the pass there.
  

Well done. You have successfully completed this codelab and learned:

• Create an app in AppGallery Connect.
• Enable HUAWEI Wallet Kit.
• Invoke the API to add a voucher.

Wallet Kit-related APIs

Demo source code used in this codelab