hms-js-base

Contents

1. Introduction
2. Installation Guide
3. Function Definitions & Sample
4. Licencing & Terms

1. Introduction

The SDK provides the ability to use HMS Core with JavaScript under multiple platforms (RN, OHOS, QuickApp, Cordova).

2. Installation Guide

• Go to your project

cd example/

• Install

npm i @hmscore/hms-js-base 

project-name
    |_ node_modules
        |_ ...
        |_  @hmscore/hms-js-base
        |_ ...

• import hms-js-base package to your application

import { hmsjsb, hmsbase } from '@hmscore/hms-js-base'

3. Function Definitions & Sample

• Function Definitions
  • hmsjsb
    • hmsjsb.invoke({apiName, args, success, fail, complete})
    • hmsjsb.on(eventName, callback, eventCallbackMap)
    • hmsjsb.off(eventName, offKey, eventCallbackMap)
    • hmsjsb.init(params)
    • hmsjsb.destroy()
  • hmsbase
    • SharedPreferences
      • hmsbase.setSPvalue({key, value, spname})
      • hmsbase.getSPvalue({key, spname})
      • hmsbase.removeSPvalue({key, spname})
    • base
      • hmsbase.getMetaData({key, packagename})
      • hmsbase.getPackageName()
      • hmsbase.getAppId()
      • hmsbase.getAaId()
      • hmsbase.getUid()
      • hmsbase.getAppVersion()
      • hmsbase.getAgcConfig({key})
      • hmsbase.config({subId})
    • report
      • hmsbase.reportEntry({uri, kitSdkVersion})
      • hmsbase.reportExit({uri, transactId, statusCode, errorCode, kitSdkVersionName})
    • update
      • hmsbase.isJsbKitAvailable({min_api_level})
      • hmsbase.upgrade()
      • hmsbase.reload()
• Sample
  • OHOS example

hmsjsb.invoke({apiName, args, success, fail, complete})

Call the HMS Core method.

The returns of callback & promise are supported. When the paramters contain success/fail/complete, it will return from callbacks, otherwise it will return a promise.

| Parameters | Type | Required |Description | | --- | --- | --- | --- | | apiName | string | yes | JAVA API name | | args | Object | no | params | | success | successCallback | no |success callback | | fail | failCallback | no |fail callback | | complete | completeCallback | no |complete callback |

return value： result

example

// callback
hmsjsb.invoke({
  apiName: 'update.availability',
  args: {
    min_api_level: 2,
  },
  success: (result) => {
    console.info(JSON.stringify(result));
  },
  fail: (error) => {
    console.info(JSON.stringify(error));
  }
});

// promise 
hmsjsb.invoke({
  apiName: 'update.availability',
  args: {
    min_api_level: 2,
  }
}).then(res => console.info(JSON.stringify(res)))
.catch(err => console.info(JSON.stringify(err)));

hmsjsb.on(eventName, callback, eventCallbackMap)

listen for HMS Core events. After the interface is called, the listener will start automatically. You can use hmsjsb.off to stop listening.

| Parameters | Type | Required |Description | | --- | --- | --- | --- | | eventName | string | yes |event name | | callback | function | yes |event callback | | eventCallbackMap | Object | no |event callback map, only used in OHOS, other platforms can ignore it |

return value： result

hmsjsb.off(eventName, offKey, eventCallbackMap)

Stop listening for HMS Core events, call it when the page is destroyed.

| Parameters | Type | Required |Description | | --- | --- | --- |--- | | eventName | string | yes| event name | | offKey | * | yes | type is function or string, Event callback or hmsjsb.on result | | eventCallbackMap | Object | no | event callback map,only used in OHOS, other platforms can ignore it |

return value ：result

hmsjsb.init(params)

Before calling the hmsjsb methods,call the method to initialize

Note: Currently only the React Native and OHOS platforms need to call this method, other platforms can ignore it.

| Parameters | Type | Required |Description | | --- | --- | --- |--- | | params | Object | no | RN and OHOS are must input, RN example:{ NativeModules, DeviceEventEmitter }, OHOS example:{}|

return value： result

hmsjsb.destroy()

Before the page is destroyed, call the method to destroy.

Note: Currently only the React Native platform needs to call this method, other platforms can ignore it.

return value： result

hmsbase.setSPvalue({key, value, spname})

SharedPreferences

| Param | Type | Description | | --- | --- | --- | | key | string | the key of SharedPreferences | | value | string | the value of SharedPreferences | | spname |string | the spname ofSharedPreferences |

hmsbase.getSPvalue({key, spname})

Read SharedPreferences value

| Param | Type | Description | | --- | --- | --- | | key | string | the key of SharedPreferences | | spname |string | the spname ofSharedPreferences |

hmsbase.removeSPvalue({key, spname})

Delete shareapeferences value

| Param | Type | Description | | --- | --- | --- | | key | string | the key of SharedPreferences | | spname |string | the spname ofSharedPreferences |

hmsbase.getMetaData({key, packagename})

Read metadata

| Param | Type | Description | | --- | --- | --- | | key | string |the key of metadata| | packagename |string |packagename|

hmsbase.getPackageName()

Get the package name of the third party application

hmsbase.getAppId()

Get the appid of the third party application

hmsbase.getAaId()

Get AAID

hmsbase.getUid()

Get UID, Depends on hms-js-base 5.2.0-300 and bridge-sdk 5.2.0.300

hmsbase.getAppVersion()

Get the application version number, Depends on hms-js-base 5.2.0-300 and bridge-sdk 5.2.0.300

hmsbase.getAgcConfig({key})

Get AGC configuration, Depends on hms-js-base 5.2.0-300 and bridge-sdk 5.2.0.300

| Param | Type | Description | | --- | --- | --- | | key | string | the key of AGC configuration |

hmsbase.config({subId})

Authentication

| Param | Type | Description | | --- | --- | --- | | subId | string | the appId of h5 app|

hmsbase.reportEntry({uri, kitSdkVersion})

Event tracking start

| Param | Type | Description | | --- | --- | --- | | uri | string | uri | | kitSdkVersion |int | kitsdk version|

hmsbase.reportExit({uri, transactId, statusCode, errorCode, kitSdkVersionName})

Event tracking end

| Param | Type | Description | | --- | --- | --- | | uri | string | uri | | transactId |string | transact ID| | statusCode | int | status code | | errorCode |int | error code| | kitSdkVersionName |int |kitsdk version|

hmsbase.isJsbKitAvailable({min_api_level})

Check jsb kit api_level >= min_api_level

| Param | Type | Description | | --- | --- | --- | | min_api_level | int | Expected api_level of JSB kit |

hmsbase.upgrade()

Upgrade jsb kit

hmsbase.reload()

After the upgrade is successful, reload the new jsb kit to initialize the jsb kit

successCallback : function

success callback.

Kind: global typedef

| Parameters | Type | Description | | --- | --- | --- | | result | object | result |

failCallback : function

fail callback.

Kind: global typedef

| Parameters | Type | Description | | --- | --- | --- | | result | object | result |

completeCallback : function

complete callback.

Kind: global typedef

| Parameters | Type | Description| | --- | --- | --- | | result | object | result |

result : object

the returned value of mothed or callback

Kind: return value

|Returns |Type |Description| | --- | --- | --- | | errCode | number | error code | | errMsg | string | error message | | data | * | Type is function or string | | extras | object | extras |

OHOSexample

Define the global variable eventCallbackMap in app.js, and then init hms-js-base at the onCreate method.

import { hmsjsb } from '@hmscore/hms-js-base'
//Define the global
hmsData: {
  eventCallbackMap: {},
}

//init
onCreate() {
  hmsjsb.init(this.hmsData.eventCallbackMap);
}

Subscribe and unsubscribe events, need to match use.

Notes: When the event linstener is no longer needed or the page is destroyed, please stop listening

import router from '@system.router'
import { hmsjsb } from '@hmscore/hms-js-base'

export default {
  data: {
    title: "",
    eventCallbackId: ""
  },
  onInit() {
    //Subscribe
    this.eventCallbackId = hmsjsb.on("onBackground", (result) => {
      console.info("event callback result: " + JSON.stringify(result));
    }, this.$app.$def.hmsData.eventCallbackMap);
  },
  onDestroy() {
    //unsubscribe
    hmsjsb.off("onBackground", this.eventCallbackId,
      this.$app.$def.hmsData.eventCallbackMap);
  }
}

4. Licensing and Terms

hms-js-base SDK uses the Apache 2.0 license.