1. Introduction
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.
2. What You Will Need
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)
3. Preparing for the Integration
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.
4. Enabling HUAWEI Wallet Kit
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.
5. Creating a Model
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.
6. Generating and Pushing a JWE 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:
Parameter | Description | Remarks |
passTypeIdentifier | Service ID set in Applying for the HUAWEI Wallet Kit Service. | Its value must be the same as that in the model. |
passStyleIdentifier | Model ID, which is defined yourself. | Its value must be the same as that in the model. |
organizationPassId | Pass ID in a pass instance, which is unique in your system. | - |
serialNumber | Pass instance ID, which is unique in your system. | - |
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}
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 |
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
- 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.
- 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.
7. Packing and Testing
- 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.
8. Congratulations
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.