npm package: @hmscore/hms-js-nearby
Description: HMS JS Nearby
Latest version: 5.2.0-300

# JSB Nearby

## 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)
  - [HMSNearby](#hmsnearby)
    - [Public Method Summary](#public-method-summary)
  - [Data Types](#data-types)
    - [UidInstance](#uidinstance)
    - [IBeaconInfo](#ibeaconinfo)
    - [NamespaceType](#namespacetype)
    - [MessagePicker](#messagepicker)
    - [MessagePolicy](#messagepolicy)
    - [GetRequest](#getrequest)
    - [UnGetRequest](#ungetrequest)
    - [Message](#message)
    - [PutRequest](#putrequest)
    - [PutResponse](#putresponse)
    - [UnPutRequest](#unputrequest)
    - [GetMessageEvent](#getmessageevent)
    - [CloudAppMsgResponseInfo](#cloudappmsgresponseinfo)
    - [CloudBeaconMsgResponseInfo](#cloudbeaconmsgresponseinfo)
  - [Constant Values](#constant-values)
    - [DistanceType](#hmsnearbydistancetype)
    - [FindingMode](#hmsnearbyfindingmode)
    - [TtlSeconds](#hmsnearbyttlseconds)
    - [Permission](#hmsnearbypermission)
- [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

JSSDK Nearby Service Plugin enables communication between HUAWEI Nearby Kit and React Native, Cordova and Ionic platforms. This plugin exposes functionalities provided by HMS Core Nearby Service SDK. Detailed information about data types, constants and methods are 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](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.2.301'
  }
}
```

- 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.2.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-nearby
```

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

```js
import HMSNearby from "@hmscore/hms-js-nearby";
```

**Step 15:** Call HMSNearby's init method to initialize. 

```js
import { NativeModules, DeviceEventEmitter } from "react-native";
...

HMSNearby.init(NativeModules, DeviceEventEmitter);
```

**Step 16:** 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-nearby
```

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

**Step 12:** Allow all permissions to the app from phone settings.

### 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 Nearby Plugin` to the project.

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

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

**Step 11:**  Allow all permissions to the app from phone settings.

#### 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. The **`appId`** property must be same with **package_name** value of the **`agconnect-services.json`** file.

```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:** Install `HMS Nearby plugin` to the project.

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

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

```bash
ionic build
```

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

```bash
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](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html#2) 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.

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

...

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.

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

```java
import com.huawei.hms.js.nearby.HMSNearby;
```

**Step 10:** In the same file, add **add(HMSNearby.class)** line inside the **this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>()** method.

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

    ```java
    ...

    import com.huawei.hms.js.nearby.HMSNearby;

    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
                // Ex: add(TotallyAwesomePlugin.class);
                add(HMSNearby.class);
            }});
        }
    }
    ```

**Step 11:** 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 12:** Updates dependencies, and copy any web assets to your project.

```bash
npx cap sync
```

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

```bash
npx cap open android
```

**Step 14:**  Allow all permissions to the app from phone settings.

## 3. API Reference

### **HMSNearby**

#### Public Method Summary

| Method | Return Type | Description |
| ------ | ----------- | ----------- |
| [putMessage(putRequest)](#hmsnearbyputmessageputrequest) | [Promise<Result\<PutResponse>>](#putresponse) | Publishes a message to the cloud and broadcasts a sharing code for nearby devices to scan. |
| [unPutMessage(unPutRequest)](#hmsnearbyunputmessageunputrequest) | Promise<Result\<void>> | Cancels a published message. The message will be deleted from the cloud. |
| [getMessage(getRequest, callback)](#hmsnearbygetmessagegetrequest-callback) | Promise<Result\<void>> | Obtains the message published by a nearby device. |
| [unGetMessage(unGetRequest)](#hmsnearbyungetmessageungetrequest) | Promise<Result\<void>> | Cancels a registered message subscription task. |
| [onStopMessageEngine](#hmsnearbyonstopmessageengine)| Promise<Result\<void>> | Stops message engine. |
| [hmsCoreHeartBeat](#hmsnearbyhmscoreheartbeat)| Promise<Result\<void>> | Sends HeartBeat to HMS Core. |

### 3.1.2 Public Methods

#### HMSNearby.putMessage(putRequest)

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| putRequest | [PutRequest](#putrequest) | Published message parameters. |

| Return Type | Description |
| ----------- | ----------- |
| [Promise<Result\<PutResponse>>](#putresponse) | If the operation is successful, promise will resolve published message id and message sequence. |

Call Example

```js
const request = {
    mMsg: {
        mContent: [66,65,83,75,69,84,66,65,76,76,95,48],
        mNamespace: "_reserved_namespace",
        mType: "NBA"
    },
    mPermission: HMSNearby.Permission.PERMISSION_DEFAULT,
    mPolicy: {
        distanceType: HMSNearby.DistanceType.POLICY_DISTANCE_TYPE_DEFAULT,
        findingMode: HMSNearby.FindingMode.POLICY_FINDING_MODE_DEFAULT,
        ttlSeconds: 300
    }
};
HMSNearby.putMessage(request)
    .then((response) => {
        console.log(response.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Response

```js
{"mMsgId":2,"mMsgSeq":0}
```

#### HMSNearby.unPutMessage(unPutRequest)

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| unPutRequest | [UnPutRequest](#unputrequest) | Parameters to cancel published message. |

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

Call Example

```js
const request = {
    mMsg: {
        mContent: [66,65,83,75,69,84,66,65,76,76,95,48],
        mNamespace: "_reserved_namespace",
        mType: "NBA"
    },
    mMsgId: 2,
    mMsgSeq: 0
};
HMSNearby.unPutMessage(request)
    .then((response) => {
        console.log(response.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

#### HMSNearby.getMessage(getRequest, callback)

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| getRequest | [GetRequest](#getrequest) | Message subscription parameters. |
| callback | (response: [GetMessageEvent](#getmessageevent)) => void | Message events will trigger. |

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

Call Example

```js
const request = {
    mMessagePicker: {
        isIncludeAll: true
    },
    mPermission: HMSNearby.Permission.PERMISSION_DEFAULT,
    mPolicy: {
        ttlSeconds: HMSNearby.TtlSeconds.POLICY_TTL_SECONDS_INFINITE,
        distanceType: HMSNearby.DistanceType.POLICY_DISTANCE_TYPE_DEFAULT,
        findingMode: HMSNearby.FindingMode.POLICY_FINDING_MODE_DEFAULT
    },
    mSessionId: "1ea95c89-c94b-4319-8fcd-424e700a9d4b"
};

const callback = (event) => {
    console.log(JSON.stringify(event));
};

HMSNearby.getMessage(request, callback)
    .then((response) => {
        console.log(response.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

Example Callback Response

```js
{
    "mBeaconMessageList":[],
    "mIsDistanceChanged":false,
    "mIsFound":true,
    "mIsNew":false,
    "mIsSignalChanged":false,
    "mMsgType":1,
    "mOrgBleScanDataStr":"DVjCRpfKDNXgHUq7",
    "mRssi":0,
    "mSharingCodeMessageList":[{
        "mIsFound":true,
        "msgData":"BASKETBALL_0",
        "msgId":1,
        "msgSeq":0,
        "msgTag":"NBA"
    }],
    "mSharingCodeMsgBitmap":"01,01",
    "mTxPower":0
}
```

#### HMSNearby.unGetMessage(unGetRequest)

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| unGetRequest | [UnGetRequest](#ungetrequest) | Parameters to cancel subscription. |

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

Call Example

```js
const request = {
    mSessionId: "1ea95c89-c94b-4319-8fcd-424e700a9d4b"
};
HMSNearby.unGetMessage(request)
    .then((response) => {
        console.log(response.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

#### HMSNearby.onStopMessageEngine()

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

Call Example

```js
HMSNearby.onStopMessageEngine()
    .then((response) => {
        console.log(response.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

#### HMSNearby.hmsCoreHeartBeat()

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

Call Example

```js
HMSNearby.hmsCoreHeartBeat()
    .then((response) => {
        console.log(response.data)
    })
    .catch((err) => {
        console.log(err)
    });
```

### Data Types

#### UidInstance

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| uid | string | 10-byte namespace of an Eddystone UID (in hexadecimal format), for example, c526dfec5403adc62585. |
| isIncludeInstance | boolean | Sets whether include instance. |
| instance | string | Optional parameter. 6-byte instance of an Eddystone UID (in hexadecimal format), for example, 32ddbcad1576. |

#### IBeaconInfo

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| uuid | string | UUID. |
| isIncludeMajor | boolean | Sets whether include major. |
| isIncludeMinor | boolean | Sets whether include minor. |
| major | string | Optional parameter. Major value. |
| minor | string | Optional parameter. Minor value. |

#### NamespaceType

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| namespace | string | Namespace of a message. It indicates custom message types. A namespace can contain multiple types of messages. The value cannot be empty and cannot contain asterisks (*). |
| type | string | Type of a message. It indicates custom messages. The value cannot be empty and cannot contain asterisks (*). |

#### MessagePicker

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| isIncludeAll | boolean | Optional parameter. Filters all published messages in the project on Huawei Developers which the current app belongs.  |
| eddystoneUid | [UidInstance[]](#uidinstance) | Optional parameter. Filters the original information of the target Eddystone ID. |
| iBeaconInfo | [IBeaconInfo[]](#ibeaconinfo) | Optional parameter. Filters the original information of the target iBeacon ID. |
| messageType | [NamespaceType[]](#namespacetype) | Optional parameter. Picks among all messages in the specified namespace and with the specified type. A namespace can be specified only for beacon messages. |

#### MessagePolicy

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| distanceType | [DistanceType](#hmsnearbydistancetype) | For message publishing, the published message will only be delivered to subscribing devices that are at the most specified distance. For message subscription, messages will only be delivered if the publishing device is at the most specified distance. |
| findingMode | [FindingMode](#hmsnearbyfindingmode) | Sets the finding mode of the current policy. |
| ttlSeconds | [TtlSeconds](#hmsnearbyttlseconds) | Sets TTL for message publishing and subscription. For message publishing, you need to set TTL of the message. For message subscription, you need to set TTL of the current task. |

#### GetRequest

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mSessionId | string | UUID. |
| mMessagePicker | [MessagePicker](#messagepicker) | Sets the rule for filtering messages to be received. |
| mPermission | [Permission](#hmsnearbypermission) | Sets message permissions. |
| mPolicy | [MessagePolicy](#messagepolicy) | Sets a message subscription policy. |

#### UnGetRequest

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mSessionId | string | UUID. |

#### Message

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mContent | number[] | Message content. The length cannot exceed 65536. |
| mNamespace | string | Optional parameter. Message type. The length cannot exceed 16. |
| mType | string | Optional parameter. Domain namespace. The default value is _reserved_namespace. |

#### PutRequest

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mMsg | [Message](#message) | Message published to the cloud. This message can be subscribed by nearby devices. |
| mPermission | [Permission](#hmsnearbypermission) | Sets message permissions. |
| mPolicy | [MessagePolicy](#messagepolicy) | Sets the policy for publishing messages. |

#### PutResponse

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mMsgId | number | Published message id. |
| mMsgSeq | number | Published message sequence. |

#### UnPutRequest

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mMsg | [Message](#message) | Published message. |
| mMsgId | number | Message id. |
| mMsgSeq | number | Message sequence. |

#### GetMessageEvent

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| mIsFound | boolean | Checks whether message is found. |
| mMsgType | number | Message Type. |
| mSharingCodeMsgBitmap | string | Sharing code bitmap. |
| mSharingCodeMessageList | [CloudAppMsgResponseInfo[]](#cloudappmsgresponseinfo) | Message list shared by app. |
| mBeaconMessageList | [CloudBeaconMsgResponseInfo[]](#cloudbeaconmsgresponseinfo) | Message list shared by beacon. |
| mTxPower | number | Transmit power from 1 meter away, in dBm. |
| mRssi | number | Received signal strength, in dBm. The value range is [–127,127]. This value is a weighted value. The shorter the distance is, the higher the weight is, and the stronger the signal is. |
| mOrgBleScanDataStr | string | Sharing code. |
| mIsSignalChanged | boolean | Checks whether signal is changed. |
| mIsDistanceChanged | boolean | Checks whether distance is changed. |
| mIsNew | boolean | Checks whether message is new. |

#### CloudAppMsgResponseInfo

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| msgData | string | Message content. |
| msgTag | string | Message Tag. |
| msgId | number | Message id. |
| msgSeq | number | Message sequence. |
| mIsFound | boolean | Checks whether message is found. |

#### CloudBeaconMsgResponseInfo

| Name             | Type                          | Description       |
| ---------------- | ----------------------------- | ----------------- |
| attachmentId | string | Beacon attachment id. |
| namespace | string | Beacon namespace. |
| type | string | Beacon message type. |
| value | string | Beacon content. |
| mIsFound | boolean | Checks whether message is found. |
| mIsSignalChanged | boolean | Checks whether signal is changed. |
| mIsDistanceChanged | boolean | Checks whether distance is changed. |
| mIsNew | boolean | Checks whether message is new. |

### Constant Values

#### HMSNearby.DistanceType

| Field            | Value                         | Description       |
| ---------------- | ----------------------------- | ----------------- |
| POLICY_DISTANCE_TYPE_DEFAULT | 0 | This mode allows messages to be transmitted over any distance. The maximum distance is the connectable distance of Bluetooth signals. |
| POLICY_DISTANCE_TYPE_EARSHOT | 1 | This mode allows messages to be transmitted only within the earshot. Here refers to the ultrasonic transmission range. Currently, the Message API does not support ultrasonic data transmission. Therefore, this distance type is not supported. |

#### HMSNearby.FindingMode

| Field            | Value                         | Description       |
| ---------------- | ----------------------------- | ----------------- |
| POLICY_FINDING_MODE_DEFAULT | 0 | This mode supports both broadcast and scanning functions. |
| POLICY_FINDING_MODE_BROADCAST | 1 | This mode only supports broadcast. The scanning function is restricted. |
| POLICY_FINDING_MODE_SCAN | 2 | This mode only supports to scan nearby devices. The broadcast function is restricted. |

#### HMSNearby.TtlSeconds

| Field            | Value                         | Description       |
| ---------------- | ----------------------------- | ----------------- |
| POLICY_TTL_SECONDS_DEFAULT | 240 | Default TTL, in seconds. |
| POLICY_TTL_SECONDS_MAX | 86400 | Maximum TTL, in seconds. |
| POLICY_TTL_SECONDS_INFINITE | 2147483647 | TTL is unlimited. |

#### HMSNearby.Permission

| Field            | Value                         | Description       |
| ---------------- | ----------------------------- | ----------------- |
| PERMISSION_DEFAULT | 0 | Default permission. It grants all required permissions. |
| PERMISSION_BLE | 1 | BLE permission. |
| PERMISSION_BLUETOOTH | 2 | Bluetooth permission. |
| PERMISSION_MICROPHONE | 3 | Microphone permission. This permission defines the ultrasonic data broadcast function. Currently, Nearby Message is not supported. |
| PERMISSION_NONE | -1 | No permission. |

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