Mini App JS SDK

The Mini App SDK for JavaScript can be used to access Android/iOS device and App specific features from a Mini App. It is intended to be used in conjunction with the Android Mini App SDK and iOS Mini App SDK.

Getting Started

1. Setup the SDK

This SDK can be used either as an NPM module or via the bundled script file.

Usage as NPM module

The SDK package can be installed in your project from the NPM registry:

npm install js-miniapp-sdk

And then it can be used as an import in your project:

import miniApp from "js-miniapp-sdk";

miniApp.getUniqueId()
    .then(id => {
    // ...

Usage via bundled script

You can alternatively use the bundled script file to use the SDK. When using the bundled script file, a global MiniApp object will be available for using the SDK.

First, download the bundled script file from the releases page. You can then include it as a normal <script> tag in your HTML:

<script src="miniapp.bundle.js"></script>

Then you can acces the SDK methods via window.MiniApp.default.

window.MiniApp.default.getUniqueId()
    .then(id => {
    // ...

2. Retrieve a unique ID

You can retrieve a unique ID which was generated by the Android or iOS App to represent the user of the mini app:

miniApp.getUniqueId()
	.then(id => {
		console.log(id);
	}).catch(error => {
		console.error(error);
	});

3. Request Permissions

There must be permission requests from miniapp to access some mobile components and data. Users can revoke a permission at any time, so you must always request the permission every time before you use the associated API. Note that accepted permissions are cached, so if a User has already accepted a permission then they will not be shown the permission dialog again unless they manually revoke the permission.

Note that there are two types of permissions:

• Device permissions: These permissions are for accessing device features, and they will display a platform-specific dialog which is controlled by the Android or iOS operating system. Device permissions can only be requested one at a time.
• Custom permissions: These permissions are related to accessing the User’s data which the Host App controls, and the Host App will display a custom permission dialog. Multiple permissions can be requested at once.

Usage example

Simply call available permission request methods from miniApp.

// Location Permission
import miniApp, { CustomPermissionResult, CustomPermissionName} from 'js-miniapp-sdk';
miniApp.requestLocationPermission()
	.then(success => {
		console.log(success); // Allowed.
	}).catch(error => {
		console.error(error); // Permission is not granted due to many circumstances.
    });

// User Data Permissions
import miniApp, { CustomPermissionResult, CustomPermissionName} from 'js-miniapp-sdk';
miniApp.requestCustomPermissions([
    {name: CustomPermissionName.USER_NAME, description: 'This text will be shown to the user.'},
    {name: CustomPermissionName.PROFILE_PHOTO, description: 'This text will be shown to the user.'},
    {name: CustomPermissionName.CONTACT_LIST, description: 'This text will be shown to the user.'}
]).then((result) => {
    const allowed = result
        .filter(permission => permission.status === CustomPermissionResult.ALLOWED)
        .map(permission => permisssion.name);

    if (allowed.indexOf(CustomPermissionName.USER_NAME) > -1) {
        // Access and use the User Name data
    }
}).catch(error => {
    console.error(error); // An error occured
});

4. Share Info

It is possible for the mini app user to share data with another App by showing the native content sharing chooser.

The data format must match the ShareInfoType.

const info = { content: inputValue };

miniApp.shareInfo(info)
    .then(success => console.log(success))
    .catch(error => console.error(error));

Advanced Usage

Usage when testing in the browser

Currently, the SDK does not support testing in the browser. You must test using the Android Mini App Demo App or iOS Mini App Demo App on an actual Android or iOS device.

If you wish to be able to test in a browser, you can detect whether your web app is running on an Android/iOS device or in the browser. If not running on a device, you can return a mock value instead of calling the SDK method. Device detection can be done using something like Bowser.

import miniApp from "js-miniapp-sdk";
import Bowser from "bowser";

const browser = Bowser.parse(window.navigator.userAgent);

function getId() {
    if (browser.is("android") || browser.is("ios")) {
        return miniApp.getUniqueId()
            .then(id => {
                console.log(id);
            }).catch(error => {
                console.error(error);
            });
    } else {
        return Promise.resolve("mock_unique_id_value");
    }
}

Changelog

See the full CHANGELOG.