npm package: @hmscore/hms-js-contactshield
Description: HMS JS ContactShield
Latest version: 5.1.0-300

# JSB ContactShield

## Contents

- [1. Introduction](#1-introduction)
- [2. Installation Guide](#2-installation-guide)
  - [Creating a Project in App Gallery Connect](#creating-a-project-in-appgallery-connect)
  - [Configuring the Signing Certificate Fingerprint](#configuring-the-signing-certificate-fingerprint)
  - [React-Native Integration](#react-native-integration)
  - [Cordova Integration](#cordova-integration)
  - [Ionic Integration](#ionic-integration)
    - [Ionic with Cordova Runtime](#ionic-with-cordova-runtime)
    - [Ionic with Capacitor Runtime](#ionic-with-capacitor-runtime)
- [3. API Reference](#3-api-reference)
  - [HMSContactShield](#hmscontactshield)
    - [Public Method Summary](#public-method-summary)
  - [Data Types](#data-types)
    - [DiagnosisConfiguration](#diagnosisconfiguration)
    - [GetPeriodicKeyResponse](#getperiodickeyresponse)
    - [PeriodicKey](#periodickey)
    - [GetContactSketchResponse](#getcontactsketchresponse)
    - [ContactSketch](#contactsketch)
    - [GetContactDetailResponse](#getcontactdetailresponse)
    - [ContactDetail](#contactdetail)
    - [GetContactWindowResponse](#getcontactwindowresponse)
    - [ContactWindow](#contactwindow)
    - [ScanInfo](#scaninfo)
    - [GetVersionResponse](#getversionresponse)
    - [GetDeviceCalibrationConfidenceResponse](#getdevicecalibrationconfidenceresponse)
    - [IsRunningResponse](#isrunningresponse)
    - [GetContactShieldStatusResponse](#getcontactshieldstatusresponse)
    - [GetDailySketchResponse](#getdailysketchresponse)
    - [DailySketch](#dailysketch)
    - [SketchData](#sketchdata)
    - [GetSharedKeysDataMappingResponse](#getsharedkeysdatamappingresponse)
    - [SharedKeysDataMapping](#sharedkeysdatamapping)
- [4. Configuration and Description](#4-configuration-and-description)
- [5. Questions or Issues](#5-questions-or-issues)
- [6. Licensing and Terms](#6-licensing-and-terms)

## 1. Introduction

## 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](https://developer.huawei.com/consumer/en/service/josp/agc/index.html)  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.** 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 2.** After completing the configuration, click check mark.

### React-Native Integration

**Step 1:** Sign in to [AppGallery Connect](https://developer.huawei.com/consumer/en/service/josp/agc/index.html) 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](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html#3) 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 **AndroidManifest.xml** file, add the following lines, and replace the value **<app_id>** with the value you found in the **agconnect-services.json** file.

```xml
<application>
...
     <meta-data
            android:name="com.huawei.hms.client.appid"
            android:value="appid=<app_id>" />
</application>
```

**Step 9:** 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.

```groovy
buildscript {    
  repositories {        
    google()        
    jcenter()        
    maven { url 'https://developer.huawei.com/repo/' }   
  }    

  dependencies {        
    /*          
      * <Other dependencies>        
      */   
    classpath 'com.huawei.agconnect:agcp:1.4.1.300'    
  }
}
```

- Go to **allprojects** then configure the Maven repository address for the HMS SDK.

```groovy
allprojects {
  repositories {
    /*          
      * <Other repositories>        
      */  
    maven { url 'https://developer.huawei.com/repo/' }
  }
}
```

**Step 10:** 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.

```groovy
defaultConfig {
  applicationId "<package_name>"
  minSdkVersion 21
  /*
   * <Other configurations>
   */
}
```

```groovy
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 11:** Open the **build.gradle** file in the **android/app** directory of your React Native project.

- Configure build dependencies.

```groovy
buildscript {
  ...
  dependencies {
    /*
    * <Other dependencies>
    */
    implementation ('com.huawei.hms:rn-adapter:5.1.0.300'){
        exclude group: 'com.facebook.react'
    } 
    ...    
  }
}
```

**Step 12:**  Import the following class to the **MainApplication.java** file of your project.

```java
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:

```java
@Override
protected List<ReactPackage> getPackages() {
    List<ReactPackage> packages = new PackageList(this).getPackages();
    packages.add(new RnJSBReactPackage()); // <-- Add this line 
    return packages;
}
...
```

**Step 13:**  Download js-sdk using command below.

```bash
npm i @hmscore/hms-js-contactshield
```

**Step 14:**  Import **HMSContactShield** in App.js as following line.

```js
import HMSContactShield from "@hmscore/hms-js-contactshield";
```

**Step 15:**  Run your project.

- Run the following command to the project directory.

```bash
react-native run-android  
```

### Cordova Integration

**Step 1:** Install Cordova CLI if haven't done before.

```bash
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](https://cordova.apache.org/docs/en/latest/reference/cordova-cli/index.html#cordova-create-command).

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

```bash
cordova platform add android
```

**Step 5:**  Download plugin using command below.

```bash
cordova plugin add @hmscore/hms-js-contactshield
```

**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](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html#2) Codelab tutorial page for generating keystore file.

- Fill **`build.json`** file according to your keystore information. For example:

    ```json
    {
        "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.

```java
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:

    ```java
    ...

    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:** Open the **AndroidManifest.xml** file, add the following lines, and replace the value **<app_id>** with the **app_id** value that can be found in the **agconnect-services.json** file.

```xml
<application>
...
     <meta-data
            android:name="com.huawei.hms.client.appid"
            android:value="appid=<app_id>" />
</application>
```

**Step 11:**  Run the app

  ```bash
  cordova run android
  ```

### Ionic Integration

Install Ionic CLI and other required tools if haven't done before.

```bash
npm install -g @ionic/cli cordova-res native-run
```

#### Ionic with Cordova Runtime

**Step 1:** Enable the **Cordova integration** if haven't done before.

```bash
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.

```bash
ionic cordova platform add android
```

**Step 4:** Install `HMS Contact Shield Plugin` to the project.

```bash
ionic cordova plugin add @hmscore/hms-js-contactshield
```

**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](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html#2) Codelab tutorial page for generating keystore file.

- Fill **`build.json`** file according to your keystore information. For example:

    ```json
    {
        "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.

```java
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:

    ```java
    ...

    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:** Open the **AndroidManifest.xml** file, add the following lines, and replace the value **<app_id>** with the **app_id** value that can be found in the **agconnect-services.json** file.

```xml
<application>
...
     <meta-data
            android:name="com.huawei.hms.client.appid"
            android:value="appid=<app_id>" />
</application>
```

**Step 10:** Run the application.

```bash
ionic cordova run android --device
```

#### Ionic with Capacitor Runtime

**Step 1:** Enable the **Capacitor integration** if haven't done before.

```bash
ionic integrations enable capacitor
```

**Step 2:** Initialize **Capacitor** if haven't done before.

```bash
npx cap init [appName] [appId]
```

- For more details please follow [Initialize Capacitor with your app information](https://capacitorjs.com/docs/getting-started/with-ionic#initialize-capacitor-with-your-app-information).

**Step 3:** Update the **`appId`** property which is specified in the **`capacitor.config.json`** file according to your project. It must be same with **package_name** value of the **`agconnect-services.json`** file.

**Step 4:** Install `HMS Contact Shield plugin` to the project.

```bash
npm install @hmscore/hms-js-contactshield
```

**Step 5:** Build Ionic app to generate resource files.

```bash
ionic build
```

**Step 6:** Add the **Android platform** to the project.

```bash
npx cap add android
```

**Step 7:** 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](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html#2) Codelab tutorial page for generating keystore file.

**Step 8:** 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.

```groovy
...

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'
        }
    }
}

...
```

**Step 9:** Open the **`build.gradle`** file in the **`<project_root>/android`** directory. Add **Huawei's maven repositories** and **agconnect classpath** to the file.

```groovy
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 10:**  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.

```java
import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit;
```

**Step 11:** 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:

    ```java
    ...

    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 12:** Open the **AndroidManifest.xml** file, add the following lines, and replace the value **<app_id>** with the **app_id** value that can be found in the **agconnect-services.json** file.

```xml
<application>
...
     <meta-data
            android:name="com.huawei.hms.client.appid"
            android:value="appid=<app_id>" />
</application>
```

**Step 13:** Updates dependencies, and copy any web assets to your project.

```bash
npx cap sync
```

**Step 14:** Open the project in Android Studio and run it.

```bash
npx cap open android
```

## 3. API Reference

### **HMSContactShield**

#### Public Method Summary

| Method                                                                        | Return Type                                                                                         | Description                                                                                                                                            |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [isContactShieldRunning](#hmscontactshieldiscontactshieldrunning)             | [Promise<Result\<IsRunningResponse>>](#isrunningresponse)                                           | This API is called to check whether Contact Shield is running.                                                                                         |
| [contactApiPermission](#hmscontactshieldcontactapipermission)                 | Promise<Result\<void>>                                                                              | This API is called to ask permission.                                                                                                                  |
| [startContactShield](#hmscontactshieldstartcontactshield)                     | Promise<Result\<void>>                                                                              | Enables Contact Shield.                                                                                                                                |
| [stopContactShield](#hmscontactshieldstopcontactshield)                       | Promise<Result\<void>>                                                                              | Disables Contact Shield                                                                                                                                |
| [getContactSketch(token)](#hmscontactshieldgetcontactsketchtoken)             | [Promise<Result\<GetContactSketchResponse>>](#getcontactsketchresponse)                             | This API is called to obtain the latest diagnosis result summary from Contact Shield.                                                                  |
| [getContactDetail(token)](#hmscontactshieldgetcontactdetailtoken)             | [Promise<Result\<GetContactDetailResponse>>](#getcontactdetailresponse)                             | This API is called to obtain the latest diagnosis result details from Contact Shield.                                                                  |
| [getContactWindow(tokenWindow)](#hmscontactshieldgetcontactwindowtokenwindow) | [Promise<Result\<GetContactWindowResponse>>](#getcontactwindowresponse)                             | This API is called to obtain the latest diagnosis result details from Contact Shield in Window mode.                                                   |
| [clearData](#hmscontactshieldcleardata)                                       | Promise<Result\<void>>                                                                              | This API is called to delete all data stored on the device.                                                                                            |
| [getVersion](#hmscontactshieldgetversion)                                     | [Promise<Result\<GetVersionResponse>>](#getversionresponse)                                         | This API is called to obtain the version.                                                                                                              |
| [getPeriodicKey](#hmscontactshieldgetperiodickey)                             | [Promise<Result\<GetPeriodicKeyResponse>>](#getperiodickeyresponse)                                 | This API is called to obtain the periodic key list from the Contact Shield SDK.                                                                        |
| [getCalibrationConfidence](#hmscontactshieldgetcalibrationconfidence)         | [Promise<Result\<GetDeviceCalibrationConfidenceResponse>>](#getdevicecalibrationconfidenceresponse) | This API is called to obtain the calibrationConfidence.                                                                                                |
| [getContactStatus](#hmscontactshieldgetcontactstatus)                         | [Promise<Result\<GetContactShieldStatusResponse>>](#getcontactshieldstatusresponse)                 | This API is called to obtain the the status value form Contact Shiled.                                                                                 |
| [getDailySketch](#hmscontactshieldgetdailysketch)                             | [Promise<Result\<GetDailySketchResponse>>](#getdailysketchresponse)                                 | This API is called to obtain the daily contact summary.                                                                                                |
| [setSharedKeyDataMapping](#hmscontactshieldsetsharedkeydatamapping)           | Promise<Result\<void>>                                                                              | Sets a SharedKeysDataMapping object as the default configuration for the Window mode risk calculation. This API can be set only once every seven days. |
| [getSharedKeyDataMapping](#hmscontactshieldgetsharedkeydatamapping)           | [Promise<Result\<GetSharedKeysDataMappingResponse>>](#getsharedkeysdatamappingresponse)             |Provides the mapping definition of SharedKey.|
| [putSharedKeyFiles](#hmscontactshieldputsharedkeyfiles)                       | Promise<Result\<void>>                                                                              | Provides the shared key list file obtained from the diagnosis server to the Contact Shield SDK.                                                        |
| [putSharedKey](#hmscontactshieldputsharedkey)                                 | Promise<Result\<void>>                                                                              | This API is called to putSharedKey.                                                                                                                    |

### 3.1.2 Public Methods

##### HMSContactShield.isContactShieldRunning()

| Return Type                                               | Description                      |
| --------------------------------------------------------- | -------------------------------- |
| [Promise<Result\<IsRunningResponse>>](#isrunningresponse) | Running status will be returned. |

Call Example

```js

HMSContactShield.isContactShieldRunning()
    .then((response) => {
        console.log(response.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "mIsRunning": true }
```

##### HMSContactShield.contactApiPermission()

| Parameter   | Type     | Description                                                      |
| ----------- | -------- | ---------------------------------------------------------------- |
| apiName     | string   | Optional parameter. By default it is set as "contactshield.api". |
| permissions | string[] | Optional parameter. By default it is set as [].                  |

| Return Type            | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Promise<Result\<void>> | If the operation is successful, promise will resolve successfully. Otherwise it throws an error. |

Call Example

```js
HMSContactShield.contactApiPermission()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

##### HMSContactShield.startContactShield()

| Parameter        | Type    | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| incubationPeriod | number  | Configured incubation period for COVID-19. The default value is 14, in days. Optional parameter. |
| persistent       | boolean | Optional parameter. By default it is set as false.                                               |

| Return Type            | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Promise<Result\<void>> | If the operation is successful, promise will resolve successfully. Otherwise it throws an error. |

Call Example

```js
HMSContactShield.startContactShield()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

##### HMSContactShield.stopContactShield()

| Return Type            | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Promise<Result\<void>> | If the operation is successful, promise will resolve successfully. Otherwise it throws an error. |

Call Example

```js
HMSContactShield.stopContactShield()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

##### HMSContactShield.getContactSketch(token)

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| token     | string | Token       |

| Return Type                                                             | Description                                        |
| ----------------------------------------------------------------------- | -------------------------------------------------- |
| [Promise<Result\<GetContactSketchResponse>>](#getcontactsketchresponse) | Contact diagnosis result summary will be returned. |

Call Example

```js
HMSContactShield.getContactSketch("TOKEN_TEST")
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "mContactSketch": { "attenuationDurations": [0, 0, 0], "daysSinceLastHit": 0, "maxRiskValue": 0, "numberOfHits": 0, "summationRiskValue": 0 } }
```

##### HMSContactShield.getContactDetail(token)

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| token     | string | Token       |

| Return Type                                                             | Description                                            |
| ----------------------------------------------------------------------- | ------------------------------------------------------ |
| [Promise<Result\<GetContactDetailResponse>>](#getcontactdetailresponse) | The contact diagnosis result details will be returned. |

Call Example

```js
HMSContactShield.getContactDetail("TOKEN_TEST")
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "contactDetailList": [] }
```

##### HMSContactShield.getContactWindow(tokenWindow)

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| token     | string | Token       |

| Return Type                                                             | Description                                   |
| ----------------------------------------------------------------------- | --------------------------------------------- |
| [Promise<Result\<GetContactWindowResponse>>](#getcontactwindowresponse) | The contact window response will be returned. |

Call Example

```js
HMSContactShield.getContactWindow("TOKEN_WINDOW_MODE")
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "contactWindowList": [] }
```

##### HMSContactShield.clearData()

| Return Type            | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Promise<Result\<void>> | If the operation is successful, promise will resolve successfully. Otherwise it throws an error. |

Call Example

```js
HMSContactShield.clearData()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

##### HMSContactShield.getVersion()

| Return Type                                                 | Description                               |
| ----------------------------------------------------------- | ----------------------------------------- |
| [Promise<Result\<GetVersionResponse>>](#getversionresponse) | The version information will be returned. |

Call Example

```js
HMSContactShield.getVersion()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "version": 170 }
```

##### HMSContactShield.getPeriodicKey()

| Return Type                                                         | Description                             |
| ------------------------------------------------------------------- | --------------------------------------- |
| [Promise<Result\<GetPeriodicKeyResponse>>](#getperiodickeyresponse) | The periodic key list will be returned. |

Call Example

```js
HMSContactShield.getPeriodicKey()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "mPeriodicKeyList": [{ "content": [-61, 123, -90, -82, -22, 9, -5, -69, 76, 57, 9, 124, 19, -92, 101, -104], "daysSinceStartOfSymptoms": 0, "initialRiskLevel": 0, "periodicKeyLifeTime": 144, "periodicKeyValidTime": 2685312, "reportType": 0 }] }
```

##### HMSContactShield.getCalibrationConfidence()

| Return Type                                                                                         | Description                                           |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [Promise<Result\<GetDeviceCalibrationConfidenceResponse>>](#getdevicecalibrationconfidenceresponse) | Calibration Confidence result value will be returned. |

Call Example

```js
HMSContactShield.getCalibrationConfidence()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "calibrationConfidence": 1 }
```

##### HMSContactShield.getContactStatus()

| Return Type                                                                         | Description                                            |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [Promise<Result\<GetContactShieldStatusResponse>>](#getcontactshieldstatusresponse) | The running status of Contact Shield will be returned. |

Call Example

```js
HMSContactShield.getContactStatus()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "statusValue": 1 }
```

##### HMSContactShield.getDailySketch()

| Parameter                  | Type     | Description                                                                                                                      |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| weightsOfReportType        | number[] | The weight map of reportType. Optional parameter. By default it is set as [0].                                                   |
| weightsOfContagiousness    | number[] | The weight map of Contagiousness. Optional parameter. By default it is set as [0].                                               |
| thresholdOfAttenuationInDb | number[] | The threshold list of Attenuation. Optional parameter. By default it is set as [0].                                              |
| weightsOfAttenuationBucket | number[] | The weight list of Attenuation. Optional parameter. By default it is set as [0].                                                 |
| thresholdOfDaysSinceHit    | number   | The threshold of the number of days between the current day and the contact time. Optional parameter. By default it is set as 0. |
| minWindowScore             | number   | The minimum WindowScore limit.Optional parameter. By default it is set as 0.                                                     |

| Return Type                                                         | Description                                       |
| ------------------------------------------------------------------- | ------------------------------------------------- |
| [Promise<Result\<GetDailySketchResponse>>](#getdailysketchresponse) | The daily contact summary value will be returned. |

Call Example

```js
HMSContactShield.getDailySketch()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "dailySketchList": [] }
```

##### HMSContactShield.setSharedKeyDataMapping()

| Parameter                         | Type     | Description                                                                               |
| --------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| daysSinceCreationToContagiousness | number[] | The contagiousness map of a periodic key.Optional parameter. By default it is set as [0]. |
| defaultContagiousness             | number   | The default contagiousness.Optional parameter. By default it is set as 0.                 |
| defaultReportType                 | number   | The default report type.Optional parameter. By default it is set as 0.                    |

| Return Type            | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Promise<Result\<void>> | If the operation is successful, promise will resolve successfully. Otherwise it throws an error. |

Call Example

```js
HMSContactShield.setSharedKeyDataMapping()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

##### HMSContactShield.getSharedKeyDataMapping()

| Return Type                                                                             | Description                                           |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [Promise<Result\<GetSharedKeysDataMappingResponse>>](#getsharedkeysdatamappingresponse) | The mapping definition of SharedKey will be returned. |

Call Example

```js
HMSContactShield.getSharedKeyDataMapping()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{ "sharedKeysDataMapping": { "daysSinceCreationToContagiousness": [0], "defaultContagiousness": 0, "defaultReportType": 0 } }
```

##### HMSContactShield.putSharedKeyFiles()

| Parameter | Type                                              | Description               |
| --------- | ------------------------------------------------- | ------------------------- |
| fileNames | string                                            | Paths of the shared keys. |
| token     | string                                            | Token                     |
| config    | [DiagnosisConfiguration](#diagnosisconfiguration) | Optional parameter.       |

| Return Type            | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Promise<Result\<void>> | If the operation is successful, promise will resolve successfully. Otherwise it throws an error. |

Call Example

```js
HMSContactShield.putSharedKeyFiles(["some-test-file.zip"], token)
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

##### HMSContactShield.putSharedKey()

| Parameter   | Type                        | Description                                                                                     |
| ----------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
| periodicKey | [PeriodicKey](#periodickey) | An optional param with a default value pKey is obtained from HMSContactShield.getPeriodicKey(). |

| Return Type            | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Promise<Result\<void>> | If the operation is successful, promise will resolve successfully. Otherwise it throws an error. |

Call Example

```js
HMSContactShield.putSharedKey()
    .then((res) => {
        console.log(res.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

### Data Types

#### DiagnosisConfiguration

| Name                          | Type     | Description                                                                                             |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| minimumRiskValueThreshold     | number   | The lowest risk value that would be recorded.                                                           |
| attenuationRiskValues         | number[] | The signal attenuation risk values.                                                                     |
| attenuationWight              | number   | The attenuation weight.                                                                                 |
| daysAfterContactedRiskValues  | number[] | Risk value associated with the last contact based on the number of days elapsed since the last contact. |
| daysAfterContactedWeight      | number   | The days after contacted weight.                                                                        |
| durationRiskValues            | number[] | Risk value associated with the last contact based on the duration of the last contact.                  |
| durationWeight                | number   | The duration weight.                                                                                    |
| initialRiskLevelRiskValues    | number[] | The initial contact risk value.                                                                         |
| mInitialRiskLevelWeight       | number   | The initial risk level weight.                                                                          |
| attenuationDurationThresholds | number[] | Attenuation threshold details. The return value contains two thresholds, each ranging from 0 to 255.    |

#### GetPeriodicKeyResponse

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mPeriodicKeyList | [PeriodicKey[]](#periodickey) | PeriodicKey List. |

#### PeriodicKey

| Name                     | Type      | Description                                                                                             |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------- |
| content                  | Int8Array | The content of the periodic key.                                                                        |
| daysSinceStartOfSymptoms | number    | The number of days between the occurrence of the first symptom and the generation of this periodic key. |
| initialRiskLevel         | number    | The initial risk level corresponding to the periodic key. The value is an integer ranging from 0 to 8.  |
| periodicKeyLifeTime      | umber     | The number of time segments elapsed since the periodic key takes effect.                                |
| periodicKeyValidTime     | number    | The time segment to which the periodic key effective time belongs.                                      |
| reportType               | number    | The diagnosis type that is set when a shared key is uploaded.                                           |

#### GetContactSketchResponse

| Name           | Type                            | Description                           |
| -------------- | ------------------------------- | ------------------------------------- |
| mContactSketch | [ContactSketch](#contactsketch) | The contact diagnosis result summary. |

#### ContactSketch

| Name                 | Type     | Description                                                                                                                                        |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| attenuationDurations | number[] | The time-related details for the contacts of all matched shared keys in an array. The unit is minute. Each value in the array ranges from 0 to 30. |
| daysSinceLastHit     | number   | The number of days elapsed since the last successful matching of a shared key.                                                                     |
| maxRiskValue         | number   | The highest risk level among all shared keys that are successfully matched. The value ranges from 0 to 4096.                                       |
| numberOfHits         | number   | The number of shared keys that are successfully matched.                                                                                           |
| summationRiskValue   | number   | The sum of contact risk values of all matched shared keys.                                                                                         |

#### GetContactDetailResponse

| Name              | Type                              | Description                           |
| ----------------- | --------------------------------- | ------------------------------------- |
| contactDetailList | [ContactDetail[]](#contactdetail) | The contact diagnosis result details. |

#### ContactDetail

| Name                 | Type     | Description                                                                        |
| -------------------- | -------- | ---------------------------------------------------------------------------------- |
| dayNumber            | number   | The number of days elapsed since the contact.                                      |
| durationMinutes      | number   | The duration of the contact, in minutes.                                           |
| attenuationRiskValue | number   | The attenuation level during the contact.                                          |
| initialRiskLevel     | number   | The initial risk level corresponding to a shared key that is successfully matched. |
| totalRiskValue       | number   | The current risk value corresponding to a shared key that is successfully matched. |
| attenuationDurations | number[] | The time-related details for the contact in an array. The unit is minute.          |

#### GetContactWindowResponse

| Name              | Type                              | Description        |
| ----------------- | --------------------------------- | ------------------ |
| contactWindowList | [ContactWindow[]](#contactwindow) | ContactWindow List |

#### ContactWindow

| Name                   | Type                    | Description                                                                                              |
| ---------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- |
| mDateMillis            | number                  | The date when the contact occurs.                                                                        |
| mScanInfos             | [ScanInfo[]](#scaninfo) | The ScanInfo list recorded during the contact.                                                           |
| mReportType            | number                  | The diagnosis type that is set when a shared key is uploaded.                                            |
| mContagiousness        | number                  | The contagiousness of the periodic key that generates the contact.                                       |
| mCalibrationConfidence | number                  | The confidence level of the Bluetooth BLE broadcast power of the broadcaster that generates the contact. |

#### ScanInfo

| Name                  | Type   | Description                                                   |
| --------------------- | ------ | ------------------------------------------------------------- |
| mAverageAttenuation   | number | The average of all attenuations detected during the scanning. |
| mMinimumAttenuation   | number | The minimum attenuation.                                      |
| mSecondsSinceLastScan | number | The number of seconds elapsed since last scanning.            |

#### GetVersionResponse

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| version | number | Version     |

#### GetDeviceCalibrationConfidenceResponse

| Name                  | Type   | Description                                                                                              |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| calibrationConfidence | number | The confidence level of the Bluetooth BLE broadcast power of the broadcaster that generates the contact. |

#### IsRunningResponse

| Name       | Type    | Description                                   |
| ---------- | ------- | --------------------------------------------- |
| mlsRunning | boolean | The status whether Contact Shield is running. |

#### GetContactShieldStatusResponse

| Name        | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| statusValue | number | The running status of Contact Shield. |

#### GetDailySketchResponse

| Name            | Type                          | Description                    |
| --------------- | ----------------------------- | ------------------------------ |
| dailySketchList | [DailySketch[]](#dailysketch) | Defines daily contact summary. |

#### DailySketch

| Name           | Type                        | Description                                               |
| -------------- | --------------------------- | --------------------------------------------------------- |
| daysSinceEpoch | number                      | The number of UTC days corresponding to the contact time. |
| reportSketches | [SketchData[]](#sketchdata) | The contact summary data list for specified reportType.   |
| sketchData     | [SketchData](#sketchdata)   | The contact summary data for all reportType.              |

#### SketchData

| Name                | Type   | Description                                     |
| ------------------- | ------ | ----------------------------------------------- |
| maxScore            | number | The maximum risk score.                         |
| scoreSum            | number | The sum of all risk scores.                     |
| weightedDurationSum | number | The sum of duration-based weighted risk scores. |

#### GetSharedKeysDataMappingResponse

| Name                  | Type                                            | Description                          |
| --------------------- | ----------------------------------------------- | ------------------------------------ |
| sharedKeysDataMapping | [SharedKeysDataMapping](#sharedkeysdatamapping) | The mapping definition of SharedKey. |

#### SharedKeysDataMapping

| Name                              | Type     | Description                               |
| --------------------------------- | -------- | ----------------------------------------- |
| daysSinceCreationToContagiousness | number[] | The contagiousness map of a periodic key. |
| defaultContagiousness             | number   | The default contagiousness.               |
| defaultReportType                 | number   | The default report type.                  |

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

```text
-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 Contact Shield plugin's ProGuard rules need to be added to your project. These rules are as follows:

```text
-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](https://stackoverflow.com/questions/tagged/huawei-mobile-services) is the best place for any programming questions. Be sure to tag your question with **huawei-mobile-services**.
- [Huawei Developer Forum](https://forums.developer.huawei.com/forumPortal/en/home?fid=0101187876626530001) HMS Core Module is great for general questions, or seeking recommendations and opinions.
- [Huawei Developer Docs](https://developer.huawei.com/consumer/en/doc/overview/HMS-Core-Plugin) 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](LICENCE).