Skip to content

Commit

Permalink
UPDATE cordova-plugin-hms-site 5.1.0-300
Browse files Browse the repository at this point in the history
  • Loading branch information
@fuatbakkal
fuatbakkal committed Feb 3, 2021
1 parent 946e2b5 commit 4edffd7
Show file tree
Hide file tree
Showing 107 changed files with 7,752 additions and 6,858 deletions.
385 changes: 27 additions & 358 deletions cordova-plugin-hms-site/README.md
View file

Large diffs are not rendered by default.

Binary file removed cordova-plugin-hms-site/example/cordova/.docs/images/api_key.png
View file
Binary file not shown.
Binary file removed cordova-plugin-hms-site/example/cordova/.docs/images/config_xml.png
View file
Binary file not shown.
197 changes: 103 additions & 94 deletions cordova-plugin-hms-site/example/cordova/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,133 +1,142 @@
# cordova-hms-site-demo
# HMS Site Cordova Demo

## Contents
1. Introduction
2. Installation Guide
3. Function Definitions
4. Configuration & Description
5. Licencing & Terms

## 1. Intruduction
This demo application demonstrates the usage of Cordova HMS Site plugin.
- [1. Introduction](#1-introduction)
- [2. Installation Guide](#2-installation-guide)
- [2.1. Creating a Project in AppGallery Connect](#21-creating-a-project-in-appgallery-connect)
- [2.2. Configuring the Signing Certificate Fingerprint and Obtaining agconnect-services.json](#22-configuring-the-signing-certificate-fingerprint-and-obtaining-agconnect-servicesjson)
- [2.3. Cordova](#23-cordova)
- [3. Configuration and Description](#3-configuration-and-description)
- [4. Questions or Issues](#4-questions-or-issues)
- [5. Licensing and Terms](#5-licensing-and-terms)

---

## 1. Introduction

This demo application demonstrates the usage of the HMS Site Kit Cordova plugin.

---

## 2. Installation Guide
- Download agconnect-services.json and put it under the root directory of the project.
- Add keystore file and build.json file to your project's root and configure build.json file according to keystore information.
```json
{
"android": {
"debug": {
"keystore": "<keystore>",
"storePassword": "<password>",
"alias": "<alias>",
"password" : "<password>"
},
"release": {
"keystore": "<keystore>",
"storePassword": "<password>",
"alias": "<alias>",
"password" : "<password>"
}
}
}
```
- Update the widget id property which is specified in config.xml file. It should be same as the package name which is defined in agconnect-services.json file.

![configxml](./.docs/images/config_xml.png)
Before you get started, you must register as a HUAWEI Developer and complete identity verification on the [HUAWEI Developer](https://developer.huawei.com/consumer/en/) website. For details, please refer to [Register a HUAWEI ID](https://developer.huawei.com/consumer/en/doc/10104).

- Update the API key which is specified in 'www/js/index.js' file. It should be same as the API key which is defined in agconnect-services.json file.
### 2.1. Creating a Project in AppGallery Connect

![apikey](./.docs/images/api_key.png)
Creating an app in AppGallery Connect is required in order to communicate with the Huawei services. To create an app, perform the following steps:

- Download cordova-plugin-hms-site plugin.
- Run following commands in the root directory of project respectively.
```
cordova platform add android
cordova plugin add @hmscore/cordova-plugin-hms-site
```
1. Sign in to [AppGallery Connect](https://developer.huawei.com/consumer/en/service/josp/agc/index.html) and select **My projects**.
2. Select your project from the project list or create a new one by clicking the **Add Project** button.
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**.
4. On the **Add app** page, enter the app information, and click **OK**.

- Execute following command to run application
```
cordova run android
```
## 3. Function Definitions
### 2.2. Configuring the Signing Certificate Fingerprint and Obtaining agconnect-services.json

A signing certificate fingerprint is used to verify the authenticity of an app when it attempts to access an HMS Core (APK) through the HMS SDK. Before using the HMS Core (APK), you must locally generate a signing certificate fingerprint and configure it in the **AppGallery Connect**. 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 for the certificate generation. Perform the following steps after you have generated the certificate.

| Return Type | Function | Description |
|:----------------|:----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Promise\<any> | initializeService(config) | Call the initializeService method to initialize the HMSSite service. A configuration object which contains apiKey must be passed as a parameter. |
| Promise\<Sites> | textSearch(textSearchRequest) | With this function, users can specify keywords, coordinate bounds, and other information to search for places such as tourist attractions, enterprises, and schools. |
| Promise\<Sites> | detailSearch(detailSearchRequest) | With this function, users can search for details about a place based on the unique ID of the place. |
| Promise\<Sites> | querySuggestion(querySuggestionRequest) | With this function, your app can return search suggestions during the user input. |
| Promise\<Sites> | nearbySearch(nearbySearchRequest) | With this function, your app can return a list of nearby places based on the current location of a user. When the user selects a place, the app obtains the place ID and searches for details about the place. |
| Promise\<Sites> | widgetSearch(widgetSearchRequest) | The widget is a search component of the built-in place search suggestion feature. When a user enters a keyword in the search box, the widget displays a list of suggested places to the user. |
| Promise< void > | enableLogger() | This method is called to enables the HMSLogger for sends some statistics for the development of functions in the cordova-plugin-hms-site plugin. |
| Promise< void > | disableLogger() | This method is called to diables the HMSLogger for stops sending some statistics for the development of functions in the cordova-plugin-hms-site plugin. |
1. Sign in to [AppGallery Connect](https://developer.huawei.com/consumer/en/service/josp/agc/index.html) and select your project from **My Projects**. Then go to **Project Setting** > **General information**. In the **App information** field, click the icon next to SHA-256 certificate fingerprint, and enter the obtained **SHA-256 certificate fingerprint**.
2. After completing the configuration, click **OK** to save the changes. (Check mark icon)
3. In the same page, click **agconnect-services.json** button to download the configuration file.

### 2.3. Cordova

#### Public Methods
1. Install Cordova CLI if haven't done before.

##### Future\<any> HMSSite.initializeService(config)
```bash
npm install -g cordova
```

Call the initializeService method to initialize the HMSSite service. A configuration object which contains apiKey must be passed as a parameter.
2. Open the demo project's root folder.
###### Parameters
| Name | Description |
|--------|-------------------------------------------------------------------------------------------------------------------------------------------|
| config | Configuration that contains the value of apiKey obtained from HUAWEI AppGallery Connect, which is required for the start of the services. |
3. Update the widget **`id`** property which is specified in the **`config.xml`** file. It must be same with **client > package_name** value of the **`agconnect-services.json`** file.
4. Add the **Android platform** to the project.
##### Future\<Sites> HMSSite.textSearch(textSearchRequest)
```bash
cordova platform add android
```
With this function, users can specify keywords, coordinate bounds, and other information to search for places such as tourist attractions, enterprises, and schools.
5. Install `HMS Site plugin` to the project.
###### Parameters
| Name | Description |
|-------------------|---------------------------------------|
| textSearchRequest | Request object used for place search. |
```bash
cordova plugin add @hmscore/cordova-plugin-hms-site
```
6. Copy **`agconnect-services.json`** file to **`<project_root>/platforms/android/app`** directory.
##### Future\<Sites> HMSSite.detailSearch(detailSearchRequest)
7. Add **`keystore(.jks)`** and **`build.json`** files to your project's root directory.

With this function, users can search for details about a place based on the unique ID of the place.
- 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.

###### Parameters
| Name | Description |
|---------------------|-----------------------------------------------|
| detailSearchRequest | Request object used for place details search. |
- Fill **`build.json`** file according to your keystore. 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>"
}
}
}
```

##### Future\<Sites> HMSSite.querySuggestion(querySuggestionRequest)
8. Run the app.

With this function, your app can return search suggestions during the user input.
```bash
cordova run android --device
```

###### Parameters
| Name | Description |
|------------------------|---------------------------------------------------------------|
| querySuggestionRequest | Request object used for search suggestions during user input. |
---

## 3. Configuration and Description

##### Future\<Sites> HMSSite.nearbySearch(nearbySearchRequest)
### Configuring Obfuscation Scripts

With this function, your app can return a list of nearby places based on the current location of a user. When the user selects a place, the app obtains the place ID and searches for details about the place.
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 Site 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
```
###### Parameters
| Name | Description |
|---------------------|--------------------------------------------------|
| nearbySearchRequest | Request object used to search for nearby places. |
---
## 4. Questions or Issues
##### Future\<Site> HMSSite.widgetSearch(widgetSearchRequest)
If you have questions about how to use HMS samples, try the following options:
The widget is a search component of the built-in place search suggestion feature. When a user enters a keyword in the search box, the widget displays a list of suggested places to the user.
- [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`**.
- [GitHub](https://github.com/HMS-Core/hms-cordova-plugin) is the official repository for these plugins, You can open an issue or submit your ideas.
- [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.
###### Parameters
| Name | Description |
|---------------------|-----------------------------------------------------|
| widgetSearchRequest | Request object used to search for place suggestion. |
If you run into a bug in our samples, please submit an issue to the [GitHub repository](https://github.com/HMS-Core/hms-cordova-plugin).
## 3. Confuguration & Description
No.
---
## 4. Licencing & Terms
Apache 2.0 license.
## 5. Licensing and Terms
Huawei Site Kit Cordova Plugin is licensed under the [Apache 2.0 license](LICENCE).
41 changes: 17 additions & 24 deletions cordova-plugin-hms-site/example/cordova/config.xml
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,18 @@
<?xml version="1.0" encoding="utf-8"?>
<widget id="<package_name>" version="5.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
<name>
cordova-hms-site-demo
</name>
<description>
A demo application which shows the usage of HMS Site Plugin
</description>
<content src="index.html" />
<plugin name="cordova-plugin-whitelist" spec="1" />
<access origin="*" />
<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />
<allow-intent href="mailto:*" />
<allow-intent href="geo:*" />
<platform name="android">
<allow-intent href="market:*" />
</platform>
<platform name="ios">
<allow-intent href="itms:*" />
<allow-intent href="itms-apps:*" />
</platform>
<?xml version='1.0' encoding='utf-8'?>
<widget id="<package_name>" version="5.1.0-300" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
<name>Site Demo</name>
<description>
A demo application which shows the usage of HMS Site Plugin.
</description>
<content src="index.html" />
<access origin="*" />
<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />
<allow-intent href="mailto:*" />
<allow-intent href="geo:*" />
<platform name="android">
<allow-intent href="market:*" />
</platform>
</widget>
67 changes: 32 additions & 35 deletions cordova-plugin-hms-site/example/cordova/package.json
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,35 @@
{
"name": "com.huawei.hms.cordova.site.demoapp",
"displayName": "HMSSiteDemo",
"version": "5.0.1-300",
"description": "A sample Apache Cordova application that demonstrates the usage of cordova-plugin-hms-site",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [
"cordova",
"huaweisite",
"site",
"ecosystem:cordova"
],
"license": "Apache-2.0",
"dependencies": {},
"devDependencies": {
"cordova-android": "^8.1.0",
"cordova-plugin-whitelist": "^1.3.4"
},
"cordova": {
"plugins": {
"cordova-plugin-whitelist": {}
"name": "cordova-hms-site-demo",
"displayName": "HMSSiteDemo",
"version": "5.1.0-300",
"description": "A demo application which shows the usage of HMS Site Plugin.",
"license": "Apache-2.0",
"licenseFilename": "LICENCE",
"readmeFilename": "README.md",
"main": "./www/js/index.js",
"keywords": [
"cordova",
"ecosystem:cordova",
"site",
"huawei-site",
"hms-site"
],
"devDependencies": {
"cordova-plugin-whitelist": "1.3.4"
},
"platforms": [
"android"
"cordova": {
"plugins": {
"cordova-plugin-whitelist": {}
},
"platforms": [
"android"
]
},
"files": [
"www",
"config.xml",
"LICENCE",
"package.json",
"README.md"
]
},
"files": [
"./.docs",
"./www",
"config.xml",
"LICENCE",
"package.json",
"README.md"
]
}
}
19 changes: 19 additions & 0 deletions cordova-plugin-hms-site/example/cordova/www/css/index.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
/*
Copyright 2020-2021. Huawei Technologies Co., Ltd. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License")
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
button {
width: 100%;
height: 60px;
}
Loading

0 comments on commit 4edffd7

Please sign in to comment.