README

JSB Account

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 Account Kit and React Native, Cordova and Ionic platforms. This plugin exposes all capabilities provided by HUAWEI Account 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-account

Step 13: Import HMSAccount in App.js as following line.

import HMSAccount from "@hmscore/hms-js-account";

Step 14: Don't forget to add init function before calling HMSAccount functions.

HMSAccount.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-account

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 Account Plugin to the project.

ionic cordova plugin add @hmscore/hms-js-account

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 Account plugin to the project.

npm install @hmscore/hms-js-account

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.account.HMSAccount;

Step 10: In the same file, add add(HMSAccount.class); line to the ArrayList.

In the end, your file will be similar to the following:

...

import com.huawei.hms.js.account.HMSAccount;

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(HMSAccount.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

HMSAccount

Public Method Summary

Method	Return Type	Description
signIn	Promise<Result>	This API is called for users to sign in to an app with HUAWEI IDs securely.
silentSignIn	Promise<Result>	This API is called for silent authorization. The API will not display the related sign-in page.
cancelAuthorizationcancelAuthorization	Promise<Result>	This API is called to cancel sign-in authorization.
signOut	Promise<Result>	This API is called for users to sign out of an app from a HUAWEI ID.
getChannel	Promise<Result>	This API is called to obtains icon information.
containScopes	Promise<Result>	This API is called to checks whether an ID has been assigned all permissions specified by scopeList.
addAuthScope	Promise<Result>	Obtains information about the current sign-in ID.
getAuthResult	Promise<Result>	This API is called to obtain the latest authorization information.
getAuthResultWithScopes	Promise<Result>	This API is called to obtain the AuthHuaweiId instance.

3.1.2 Public Methods

Public Methods

signIn

This API is called for HUAWEI sign-in.

Parameters

Parameter	Type	Description
permissions	Permission[]	Requested permission options.
scopes	Scope[]	Authorized scopes.

Return Type

Type	Description
Promise<Result>	If the operation is successful, promise resolves to an AuthHuaweiId object. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
const permissions = [
  HMSAccount.Permission.ACCESSTOKEN,
  HMSAccount.Permission.IDTOKEN
]
const scopes = [
  HMSAccount.Scope.MOBILE_NUMBER,
  HMSAccount.Scope.ACCOUNT_BIRTHDAY,
  HMSAccount.Scope.OPENID,
  HMSAccount.Scope.PROFILE
]

HMSAccount.signIn(permissions, scopes)
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

silentSignIn

This API is called to return the information (or error information) about the HUAWEI ID used by a user who has signed in to an app. During this process, no user page will be displayed to the HUAWEI ID user.

Parameters

Name	Type	Description
permissions	Permission[]	Requested permission options.
scopes	Scope[]	Authorized scopes.

Return Type

Type	Description
Promise<Result>	If the operation is successful, promise resolves to an AuthHuaweiId object. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
const permissions = [
  HMSAccount.Permission.ACCESSTOKEN,
  HMSAccount.Permission.IDTOKEN
]
const scopes = [
  HMSAccount.Scope.MOBILE_NUMBER,
  HMSAccount.Scope.ACCOUNT_BIRTHDAY,
  HMSAccount.Scope.OPENID,
  HMSAccount.Scope.PROFILE
]
HMSAccount.silentSignIn(permissions, scopes)   
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

signOut

This API is called to sign out of an app from a HUAWEI ID. After a user signs out, the HMS Core SDK deletes the cached HUAWEI ID information.

Return Type

Type	Description
Promise<Result>	If the operation is successful, promise resolves successfully. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
HMSAccount.signOut()  
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

getChannel

Obtains icon information.

Return Type

Type	Description
Promise<Result>	If the operation is successful, promise resolves AccountIcon successfully. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
HMSAccount.getChannel()  
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

cancelAuthorization

This API is called to cancel sign-in authorization.

Return Type

Type	Description
Promise<Result>	If the operation is successful, promise resolves successfully. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
HMSAccount.cancelAuthorization()
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

containScopes

This API is called to check whether the designated HUAWEI ID has been assigned all permissions specified by scopeList.

Parameters

Parameter	Type	Description
scopes	Scope[]	Authorized scopes.
huaweiId	Promise<Result>	Signed-in HUAWEI ID information, including the ID, nickname, profile picture URI, permission, and access token.

Return Type

Type	Description
Promise<Result>	true: The ID has all permissions specified by scopeList.
false: The ID does not have all permissions specified by scopeList.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
const scopes = [HMSAccount.Scope.OPENID, HMSAccount.Scope.EMAIL];
HMSAccount.containScopes(huaweiId, scopes)
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

addAuthScope

This API is called to request the permission specified by scopeList from a HUAWEI ID.

Parameters

Parameter	Type	Description
scopes	Scope[]	Authorized scopes.

Return Type

Type	Description
Promise<Result>	If the operation is successful, promise resolves successfully. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
const scopes = [HMSAccount.Scope.EMAIL, HMSAccount.Scope.OPENID];
HMSAccount.addAuthScope(scopes)
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

getAuthResult

This API is called to obtain information about the HUAWEI ID used for previous sign-in and authorization.

Return Type

Type	Description
`Promise<Result>	If the operation is successful, promise resolves to an AuthHuaweiId object. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
HMSAccount.getAuthResult()
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

getAuthResultWithScopes

This API is called to obtain the AuthHuaweiId.

Parameters

Parameter	Type	Description
scopes	Scope[]	Authorized scopes.

Return Type

Type	Description
Promise<Result>	If the operation is successful, promise resolves to an AuthHuaweiId object. Otherwise, it throws an error.

Sample Code

import HMSAccount from "@hmscore/hms-js-account";
const scopes = [HMSAccount.Scope.PROFILE]
HMSAccount.getAuthResultWithScopes(scopes)
    .then((res) => { console.log(JSON.stringify(res)) })
    .catch((err) => { console.log(JSON.stringify(err)) });

Data Types

Result

Name	Type	Description
status	string	Result status.
resultCode	number	Result code.
data	object	Result object according to the API.

AuthHuaweiId

Name	Type	Description
homeZone	number	Home Zone.
accessToken	string	Access token.
idToken	string	ID token from a HUAWEI ID if the authorization parameter specified by ID_TOKEN is carried during authorization.
photoUriString	string	Profile picture URI.
grantedScopes	ScopeUri[]	Authorized scopes.
expirationTimeSecs	number	Expiration time in seconds.
displayName	string	Nickname.
familyName	string	Family name.
gender	number	Gender.
givenName	string	Given name from a HUAWEI ID if the authorization parameter specified during authorization. Otherwise, value null is returned.
openId	string	The value differs for the same user in different apps.
unionId	string	UnionId from a HUAWEI ID if the authorization parameter specified during authorization.
status	number	Status
extensionScope	Scope[]	Extended scopes.

ScopeUri

Name	Type	Description
mScopeUri	string	Scope Uri.

Status

Name	Type	Description
statusCode	number	Status Code.

AccountIcon

Name	Type	Description
icon	string	icon resources.
description	string	icon description.

Constants

Scope

Name	Value	Description
HMSAccount.Scope.OPENID	"openid"	Specifies the openid scope.
HMSAccount.Scope.BASEPROFILE	"https://www.huawei.com/auth/account/base.profile"	Specifies the base profile scope.
HMSAccount.Scope.MOBILE_NUMBER	"https://www.huawei.com/auth/account/mobile.number"	Specifies the mobile number scope.
HMSAccount.Scope.ACCOUNT_COUNTRY	"https://www.huawei.com/auth/account/country"	Specifies the account country scope.
HMSAccount.Scope.ACCOUNT_BIRTHDAY	"https://www.huawei.com/auth/account/birthday"	Specifies the account birthday scope.
HMSAccount.Scope.AGE_RANGE	"https://www.huawei.com/auth/account/age.range"	Specifies the age range scope.

Permission

Name	Value	Description
HMSAccount.Permission.IDTOKEN	"idtoken"	Requests a HUAWEI ID user to authorize an app to obtain the ID token.
HMSAccount.Permission.ACCESSTOKEN	"https://www.huawei.com/auth/account/base.profile/accesstoken"	Requests a HUAWEI ID user to authorize an app to obtain the access token.

Result Codes

Result Code	Descriptive Name	Description
0	SUCCESS	Success.
-1	FAILED	Common error code upon a failure.
-8	NOT_SILENT_SIGN_IN_OR_WRONG_PARAMETER	Not silentSignIn api or wrong parameter.
2002	SIGN_IN_AUTH	The app has not been authorized.
2003	SIGN_IN_PARAMS_ERROR	Invalid parameter for calling a method.
2005	SIGN_IN_NETWORK_ERROR	A network error occurs during authorization.
2009	SIGN_IN_AUTH_SERVER_FAILED	The HUAWEI Account Kit server is faulty.
2012	SIGN_IN_CANCELLED	The user taps the back button to cancel the sign-in.
2013	SIGN_IN_EXECUTING	The user is signing in.
700111	UPGRADE_FAILED	Kit upgrade failed.

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 Account 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.

Usage no npm install needed!

README

JSB Account

Contents

1. Introduction

2. Installation Guide

Creating a Project in AppGallery Connect

Configuring the Signing Certificate Fingerprint

React-Native Integration

Cordova Integration

Ionic Integration

Ionic with Cordova Runtime

Ionic with Capacitor Runtime

3. API Reference

HMSAccount

Public Method Summary

3.1.2 Public Methods

Public Methods

signIn

Parameters

Return Type

Sample Code

silentSignIn

Parameters

Return Type

Sample Code

signOut

Return Type

Sample Code

getChannel

Return Type

Sample Code

cancelAuthorization

Return Type

Sample Code

containScopes

Parameters

Return Type

Sample Code

addAuthScope

Parameters

Return Type

Sample Code

getAuthResult

Return Type

Sample Code

getAuthResultWithScopes

Parameters

Return Type

Sample Code

Data Types

Result

AuthHuaweiId

ScopeUri

Status

AccountIcon

Constants

Scope

Permission

Result Codes

4. Configuration and Description

Configuring Obfuscation Scripts

React Native

Cordova

5. Questions or Issues

6. Licensing and Terms