REACT NATIVE | How to install & use HMS Site Kit
Tags: reactnative, hms
Published: 2020-09-29 06:50:30

Introduction
Hello everyone. In this article we are going to take a look at Huawei Mobile Services(HMS) Site Kit Plugin for react native. We will cover how to install and use HMS Site Kit.

HMS Site Kit has following features

Keyword Search: Returns a place list based on keywords entered by the user.

Nearby Place Search: Searches for nearby places based on the current location of the user's device.

Place Details: Searches for details about a place.

Place Search Suggestion: Returns a list of place suggestions.

Before we begin, you need to have Huawei developer account to use Huawei Mobile Services and thus the HMS Site Kit. You can sign in/register to Huawei developer website from  here.

Configure your project on AppGallery Connect
First of all, you need to integrate Huawei Mobile Services with your application. I will not get into details about how to integrate your application but you can use this article as step by step guide.

Installation
First things first, let's install the library.

```npm i @hmscore/react-native-hms-site```

After the installation completed, we can import the library.

```import RNHMSSite from '@hmscore/react-native-hms-site'```

Before we can use the features of HMS site kit. We need to initialize it. In order to initialize the service, you will need an API key. When you integrated your application with HMS, AppGallery Connect will automatically provide an API key for you. You can find your API key on AppGallery Connect > YourApp > Project Settings > General information > App information.

Since we have our api key let's call initialize service function.

    const config = {
    apiKey: '<Your_API_KEY>' // You can find it in AppGallery Connect > YourApp > Project Settings > General information > App information};
 
    RNHMSSite.initializeService(config)
    .then(() => {
        console.log('Service is initialized successfully');
    })
    .catch((err) => {
        console.log('Error : ' + err);
     });

If your API key is correct you will see "Service is initialized successfully" on your console.

Usage
Now we can start using HMS React Native Site Kit. Let's start with keyword search.

Keyword (Text) Search
HMS Site kit keyword search feature let's you implement a functionality that returns place list based on your user's keyword input. Also you can specify a location which search result will be baised. You can specify search radius, country, language and page size. For the keyword search you can set the POI (Point of Interest) where results can be filtered based on POI. User can search Bakery, School, ATM etc.

Let's create a TextSearchRequest object, which is used as the request body for keyword search. Related parameters are as follows, among which query is mandatory and others are optional:

query: search keyword.

location: longitude and latitude to which search results need to be biased.

radius: search radius, in meters. The value ranges from 1 to 50000. The default value is 50000.

poiType: POI type. The value range is the same as that of LocationType.

countryCode: code of the country where places are searched, which complies with the ISO 3166-1 alpha-2 standard.

language: language in which search results are displayed. For details about the value range, please refer to language codes in Language Mapping. If this parameter is not passed, the language of the query field is used in priority. If the field language is unavailable, the local language will be used.

pageSize: number of records on each page. The value ranges from 1 to 20. The default value is 20.

pageIndex: current page number. The value ranges from 1 to 60. The default value is 1.

After that we can call textSearch function and send our TextSearchRequest object as a parameter like this.

Let's find international school at Paris

    const onTextSearch = () => {
    let textSearchReq = {
        query: 'International',
        location: {
            lat: 48.893478,
            lng: 2.334595,
        },
        radius: 1000,
        countryCode: 'FR',
        language: 'en',
        pageIndex: 1,
        pageSize: 1,
        poiType: RNHMSSite.LocationType.SCHOOL
    };
    RNHMSSite.textSearch(textSearchReq)
        .then((response) => {
            console.log(JSON.stringify(response));
        })
        .catch((err) => {
            console.log(JSON.stringify(err));
        });
    };

The response json should be like this and as you can see there is alot of information to play around with.

    {
    "totalCount": 1,
    "sites": [
        {
            "siteId": "FB3941B313927D74413FFF0E883144FE",
            "poi": {
                "rating": 0,
                "poiTypes": [
                    "SCHOOL"
                ],
                "phone": "+(33)-(1)-42000679",
                "openingHours": {},
                "internationalPhone": "+(33)-(1)-42000679"
            },
            "viewport": {
                "southwest": {
                    "lng": 2.3455935548062814,
                    "lat": 48.87367776679441
                },
                "northeast": {
                    "lng": 2.3494610451937183,
                    "lat": 48.87622143320559
                }
            },
            "name": "Acting International",
            "formatAddress": "15, Rue Ambroise Thomas, 75009, 9e Arrondissement, Paris, Ile-de-France, France",
            "address": {
                "subLocality": "9e Arrondissement",
                "subAdminArea": "Paris",
                "postalCode": "75009",
                "thoroughfare": "Rue Ambroise Thomas",
                "countryCode": "FR",
                "locality": "Paris",
                "country": "France",
                "adminArea": "Ile-de-France"
            },
            "distance": 2269.4454697030014,
            "location": {
                "lng": 2.3475273,
                "lat": 48.8749496
            }
        }
    ]
    }

Nearby Place Search
HMS Site kit nearby search feature let's you implement a functionality that returns nearby places using the current location of the user. Also you can specify search keyword, search radius, language and page size. For the nearby search you can set the POI (Point of Interest) where results can be filtered based on POI. User can search Bakery, School, ATM etc.

Let's create a NearbySearchRequest object, which is used as the request body for nearby place search. Related parameters are as follows, among which location is mandatory and others are optional:

location: longitude and latitude to which search results need to be biased.

radius: search radius, in meters. The value ranges from 1 to 50000. The default value is 50000.

query: search keyword.

poiType: POI type. The value range is the same as that of LocationType.

language: language in which search results are displayed. For details about the value range, please refer to language codes in Language Mapping. If this parameter is not passed, the language of the query field is used in priority. If the field language is unavailable, the local language will be used.

pageSize: number of records on each page. The value ranges from 1 to 20. The default value is 20.

pageIndex: current page number. The value ranges from 1 to 60. The default value is 1.

After that we can call nearbySearch function and send our NearbySearchRequest object as a parameter like this.

Let's find an ATM nearby.

    const onNearbySearch = () => {
    let nearbySearchReq = {
        location: {
            lat: 51.500775,
            lng: -0.115756,
        },
        query: 'BANK',
        radius: 1000,
        poiType: RNHMSSite.LocationType.ATM,
        language: 'en',
        pageIndex: 1,
        pageSize: 1
    };
    RNHMSSite.nearbySearch(nearbySearchReq)
        .then((response) => {
            console.log(JSON.stringify(response));
        })
        .catch((err) => {
            console.log(JSON.stringify(err));
        });
    };

The response json should be like this and as you can see there is alot of information to play around with.

    {
    "totalCount": 1,
    "sites": [
        {
            "siteId": "7B4F4024A4FD4D700E61B659247BB854",
            "poi": {
                "rating": 0,
                "poiTypes": [
                    "ATM"
                ],
                "openingHours": {},
                "internationalPhone": ""
            },
            "viewport": {
                "southwest": {
                    "lng": -0.11576103182719415,
                    "lat": 51.498155166794405
                },
                "northeast": {
                    "lng": -0.11167496817280585,
                    "lat": 51.50069883320559
                }
            },
            "name": "Bank of Ireland - Post Office",
            "formatAddress": "125-131, Westminster Bridge Road, Lambeth, London, England, the United Kingdom",
            "address": {
                "subAdminArea": "London",
                "thoroughfare": "Westminster Bridge Road",
                "countryCode": "GB",
                "locality": "Lambeth",
                "country": "the United Kingdom",
                "adminArea": "England"
            },
            "distance": 206.06612089844526,
            "location": {
                "lng": -0.113718,
                "lat": 51.499427
            }
        }
    ]
    }

Place Details Search
Place details search returns search details about a place based on the unique ID (Site Id) of the place. SiteId can get from keyword or nearby or Place Suggestion search.

Let's create a DetailSearchRequest object, which is used as the request body for place details search. Related parameters are as follows, among which siteId is mandatory and others are optional:

siteId: ID of a place.

language: language in which search results are displayed. If this parameter is not passed, the local language will be used.

After that we can call detailSearch function and send our DetailSearchRequest object as a parameter like this.

Let's look at the details of the atm we found on nearby search.

    const onDetailSearch = () => {
    let detailSearchReq = {
        siteId: '7B4F4024A4FD4D700E61B659247BB854',
        language: 'en'
    };
    RNHMSSite.detailSearch(detailSearchReq)
        .then((response) => {
            console.log(JSON.stringify(response));
        })
        .catch((err) => {
            console.log(JSON.stringify(err));
        });
    };

The response json should be like this and as you can see there is alot of information to play around with.