@hmscore/hms-js-identity v5.2.0-300
JSB identity
Contents
- 1. Introduction
- 2. Installation Guide
- 3. API Reference
- 4. Configuration and Description
- 5. Questions or Issues
- 6. Licensing and Terms
1. Introduction
JSSDK enables communication between HUAWEI Identity Kit and React Native, Cordova and Ionic platforms. This plugin exposes all capabilities provided by HUAWEI Identity Kit. Detailed information about data types, constants and methods provided by this document.
2. Installation Guide
Creating a Project in AppGallery Connect
Creating an app in AppGallery Connect is required in order to communicate with the Huawei services. To create an app, perform the following steps:
Step 1. Sign in to AppGallery Connect and select My projects.
Step 2. Select your project from the project list or create a new one by clicking the Add Project button.
Step 3. Go to Project Setting > General information, and click Add app. If an app exists in the project and you need to add a new one, expand the app selection area on the top of the page and click Add app.
Step 4. On the Add app page, enter the app information, and click OK.
- A signing certificate fingerprint is used to verify the authenticity of an app when it attempts to access an HMS Core service through the HMS Core SDK. Before using HMS Core (APK), you must locally generate a signing certificate fingerprint and configure it in AppGallery Connect. Ensure that the JDK has been installed on your computer.
Configuring the Signing Certificate Fingerprint
Step 1. Obtain the signature file that generated in Generating a Signing Certificate section.
Step 2. Go to Project Setting > General information. In the App information field, click the icon next to SHA-256 certificate fingerprint, and enter the obtained SHA256 certificate fingerprint.
Step 3. After completing the configuration, click check mark.
React-Native Integration
Step 1: Sign in to AppGallery Connect and select My projects.
Step 2: Find your app project, and click the desired app name.
Step 3: Go to Project Setting > General information. In the App information section, click agconnect-service.json to download the configuration file.
Step 4: Create a React Native project if you do not have one.
Step 5: Copy the agconnect-service.json file to the android/app directory of your React Native project.
Step 6: Copy the signature file that generated in Generating a Signing Certificate section, to the android/app directory of your React Native project.
Step 7: Check whether the agconnect-services.json file and signature file are successfully added to the android/app directory of the React Native project.
Step 8: Open the build.gradle file in the android directory of your React Native project.
- Go to buildscript then configure the Maven repository address and agconnect plugin for the HMS SDK.
buildscript {
repositories {
google()
jcenter()
maven { url 'https://developer.huawei.com/repo/' }
}
dependencies {
/*
* <Other dependencies>
*/
classpath 'com.huawei.agconnect:agcp:1.4.2.301'
}
}
- Go to allprojects then configure the Maven repository address for the HMS SDK.
allprojects {
repositories {
/*
* <Other repositories>
*/
maven { url 'https://developer.huawei.com/repo/' }
}
}
Step 9: Open the build.gradle file in the android/app directory of your React Native project.
- Package name must match with the package_name entry in agconnect-services.json file.
defaultConfig {
applicationId "<package_name>"
minSdkVersion 19
/*
* <Other configurations>
*/
}
android {
/*
* <Other configurations>
*/
signingConfigs {
config {
storeFile file('<keystore_file>.jks')
storePassword '<keystore_password>'
keyAlias '<key_alias>'
keyPassword '<key_password>'
}
}
buildTypes {
debug {
signingConfig signingConfigs.config
}
release {
signingConfig signingConfigs.config
minifyEnabled enableProguardInReleaseBuilds
...
}
}
}
Step 10: Open the build.gradle file in the android/app directory of your React Native project.
- Configure build dependencies.
buildscript {
...
dependencies {
/*
* <Other dependencies>
*/
implementation ('com.huawei.hms:rn-adapter:5.2.0.300'){
exclude group: 'com.facebook.react'
}
...
}
}
Step 11: Import the following class to the MainApplication.java file of your project.
import com.huawei.hms.jsb.adapter.rn.RnJSBReactPackage;
Then, add the RnJSBReactPackage() to your getPackages method. In the end, your file will be similar to the following:
@Override
protected List<ReactPackage> getPackages() {
List<ReactPackage> packages = new PackageList(this).getPackages();
packages.add(new RnJSBReactPackage()); // <-- Add this line
return packages;
}
...
Step 12: Download js-sdk using command below.
npm i @hmscore/hms-js-identity
Step 13: Import HMSIdentity in App.js as following line.
import HMSIdentity from "@hmscore/hms-js-identity";
Step 14: Don't forget to add init function before calling HMSIdentity functions.
HMSIdentity.init(NativeModules, DeviceEventEmitter);
Step 15: Run your project.
- Run the following command to the project directory.
react-native run-android
Cordova Integration
Step 1: Install Cordova CLI if haven't done before.
npm install -g cordova
Step 2: Create a new Cordova project or use the existing one.
- To create new Cordova project, you can use
cordova create path [id [name [config]]] [options]
command. For more details please follow CLI Reference - Apache Cordova.
Step 3: Update the widget id
property which is specified in the config.xml
file. It must be same with package_name value of the agconnect-services.json
file.
Step 4: Add the Android platform to the project if haven't done before.
cordova platform add android
Step 5: Download plugin using command below.
cordova plugin add @hmscore/hms-js-identity
Step 6: Copy agconnect-services.json
file to <project_root>/platforms/android/app
directory.
Step 7: Add keystore(.jks)
and build.json
files to your project's root directory.
You can refer to 3rd and 4th steps of Generating a Signing Certificate Codelab tutorial page for generating keystore file.
Fill
build.json
file according to your keystore information. For example:{ "android": { "debug": { "keystore": "<keystore_file>.jks", "storePassword": "<keystore_password>", "alias": "<key_alias>", "password": "<key_password>" }, "release": { "keystore": "<keystore_file>.jks", "storePassword": "<keystore_password>", "alias": "<key_alias>", "password": "<key_password>" } } }
Step 8: Import the following class to the MainActivity.java file of your project. You can find this file in platforms/android/app/src/main/java/<your_package_name>
directory.
import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit;
Step 9: In the same file, add CordovaJSBInit.initJSBFramework(this) line after the super.onCreate(savedInstanceState) method call.
In the end, your file will be similar to the following:
... import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit; public class MainActivity extends CordovaActivity { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); CordovaJSBInit.initJSBFramework(this); ... } ... }
Step 10: Run the app
cordova run android
Ionic Integration
Install Ionic CLI and other required tools if haven't done before.
npm install -g @ionic/cli cordova-res native-run
Ionic with Cordova Runtime
Step 1: Enable the Cordova integration if haven't done before.
ionic integrations enable cordova
Step 2: Update the widget id
property which is specified in the config.xml
file. It must be same with package_name value of the agconnect-services.json
file.
Step 3: Add the Android platform to the project if haven't done before.
ionic cordova platform add android
Step 4: Install HMS Identity Plugin
to the project.
ionic cordova plugin add @hmscore/hms-js-identity
Step 5: Copy agconnect-services.json
file to <project_root>/platforms/android/app
directory.
Step 6: Add keystore(.jks)
and build.json
files to your project's root directory.
You can refer to 3rd and 4th steps of Generating a Signing Certificate Codelab tutorial page for generating keystore file.
Fill
build.json
file according to your keystore information. For example:{ "android": { "debug": { "keystore": "<keystore_file>.jks", "storePassword": "<keystore_password>", "alias": "<key_alias>", "password": "<key_password>" }, "release": { "keystore": "<keystore_file>.jks", "storePassword": "<keystore_password>", "alias": "<key_alias>", "password": "<key_password>" } } }
Step 7: Import the following class to the MainActivity.java file of your project. You can find this file in platforms/android/app/src/main/java/<your_package_name>
directory.
import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit;
Step 8: In the same file, add CordovaJSBInit.initJSBFramework(this) line after the super.onCreate(savedInstanceState) method call.
In the end, your file will be similar to the following:
... import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit; public class MainActivity extends CordovaActivity { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); CordovaJSBInit.initJSBFramework(this); ... } ... }
Step 9: Run the application.
ionic cordova run android --device
Ionic with Capacitor Runtime
Step 1: Enable the Capacitor integration if haven't done before.
ionic integrations enable capacitor
Step 2: Initialize Capacitor if haven't done before. It must be same with package_name value of the agconnect-services.json
file.
npx cap init [appName] [appId]
- For more details please follow Initialize Capacitor with your app information.
Step 3: Install HMS Identity plugin
to the project.
npm install @hmscore/hms-js-identity
Step 4: Build Ionic app to generate resource files.
ionic build
Step 5: Add the Android platform to the project.
npx cap add android
Step 6: Copy keystore(.jks)
and agconnect-services.json
files to <project_root>/android/app
directory.
- You can refer to 3rd and 4th steps of Generating a Signing Certificate Codelab tutorial page for generating keystore file.
Step 7: Open the build.gradle
file in the <project_root>/android/app
directory.
Add
signingConfigs
entry to the android section and modify it according to your keystore.Enable
signingConfig
configuration for debug and release flavors.
...
android {
...
// Modify signingConfigs according to your keystore
signingConfigs {
config {
storeFile file('<keystore_file>.jks')
storePassword '<keystore_password>'
keyAlias '<key_alias>'
keyPassword '<key_password>'
}
}
buildTypes {
debug {
signingConfig signingConfigs.config // Enable signingConfig for debug flavor
}
release {
signingConfig signingConfigs.config // Enable signingConfig for release flavor
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
}
...
apply plugin: 'com.huawei.agconnect' // Apply com.huawei.agconnect plugin. This line must be added to the end of the file.
Step 8: Open the build.gradle
file in the <project_root>/android
directory. Add Huawei's maven repositories and agconnect classpath to the file.
buildscript {
repositories {
/*
<Other repositories>
*/
maven { url 'https://developer.huawei.com/repo/' }
}
dependencies {
/*
<Other dependencies>
*/
classpath 'com.huawei.agconnect:agcp:1.4.2.301'
}
}
/*
<Other build.gradle entries>
*/
allprojects {
repositories {
/*
<Other repositories>
*/
maven { url 'https://developer.huawei.com/repo/' }
}
}
Step 9: Import the following class to the MainActivity.java file of your project. You can find this file in android/app/src/main/java/<your_package_name>
directory.
import com.huawei.hms.js.identity.HMSIdentity;
Step 10: In the same file, add add(HMSIdentity.class); line to the ArrayList.
In the end, your file will be similar to the following:
... import com.huawei.hms.js.identity.HMSIdentity; public class MainActivity extends BridgeActivity { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // Initializes the Bridge this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{ // Additional plugins you've installed go here add(HMSIdentity.class); }}); ... } ... }
Step 11: Updates dependencies, and copy any web assets to your project.
npx cap sync
Step 12: Open the project in Android Studio and run it.
npx cap open android
3. API Reference
HMSIdentity
Public Method Summary
Method | Return Type | Description |
---|---|---|
queryUserAddress | Promise<Result> | This API is used to display the address selection page when your app needs to use the user's address-related information, such as name, contact, and detailed address. After the user selects an address on the page, the API returns the address to the app. |
3.1.2 Public Methods
Public Methods
queryUserAddress
This method can return the PendingIntent object of the address selection page.
Parameters
Parameter | Type | Description |
---|---|---|
userAddressRequest | UserAddressRequest[] | Object that contains request information. |
Return Type
Type | Description |
---|---|
Promise<Result> | Task containing the API request result. You can use OnSuccessListener to obtain the data returned in the success scenario. In this scenario, a GetUserAddressResult object is returned. You can use OnFailureListener to obtain related information in the failure scenario. In this scenario, an AddressApiException object is returned. |
Sample Code
async function queryUserAddress() {
const userAddressReq = {
countries: [""]
};
HMSIdentity.queryUserAddress({
userAddressReq
})
.then((res) => alert(JSON.stringify(res)))
.catch((err) => alert(JSON.stringify(err)));
}
Data Types
UserAddressRequest
Class of request information used to call the queryUserAddress method.
Name | Type | Description |
---|---|---|
countries | string[] | Obtains the ID of the leaderboard to which a score is to be submitted. |
Result
Name | Type | Description |
---|---|---|
status | string | Result status. |
resultCode | number | Result code. |
data | object | Result object according to the API. |
Result Codes
Result Code | Description |
---|---|
0 | Success. |
-1 | Common error code upon a failure. |
50001 | Identity Kit is not started.Please try again. |
50002 | A child identity is signed in, which does not support Identity Kit.Switch to another HUAWEI ID. |
50003 | Failed to authenticate the HUAWEI ID.Sign in with the HUAWEI ID again. |
30008 | Failed to obtain the HUAWEI ID information.Sign in with the HUAWEI ID again. |
60053 | The product has been consumed and cannot be consumed again. |
60054 | The Identity service is not supported in the current locale |
60055 | Children identity do not support Identity service |
60056 | The user triggers risk control, and the transaction is rejected. |
4. Configuration and Description
Configuring Obfuscation Scripts
React Native
In order to prevent error while release build, you may need to add following lines in proguard-rules.pro
file.
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keep class com.hianalytics.android.**{*;}
-keep class com.huawei.updatesdk.**{*;}
-keep class com.huawei.hms.**{*;}
-repackageclasses
Cordova
Before building the APK, configure the obfuscation configuration file to prevent the HMS Core SDK from being obfuscated.
NOTE: This step is required only if you want to minify and obfuscate your app. By default obfuscation is disabled in Cordova and Ionic apps.
The obfuscation is done by ProGuard
. By default, in Cordova and Ionic apps ProGuard is disabled. Even though ProGuard is not available, ProGuard support can be added through 3rd party ProGuard plugins. If ProGuard is enabled in your project, the Huawei Cordova Identity plugin's ProGuard rules need to be added to your project. These rules are as follows:
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keep class com.huawei.hianalytics.**{*;}
-keep class com.huawei.updatesdk.**{*;}
-keep class com.huawei.hms.**{*;}
-repackageclasses
5. Questions or Issues
If you have questions about how to use HMS samples, try the following options:
- Stack Overflow is the best place for any programming questions. Be sure to tag your question with huawei-mobile-services.
- Huawei Developer Forum HMS Core Module is great for general questions, or seeking recommendations and opinions.
- Huawei Developer Docs is place to official documentation for all HMS Core Kits, you can find detailed documentations in there.
6. Licensing and Terms
Huawei JS SDK is licensed under Apache 2.0 license.
3 years ago