Skip to content

Latest commit

 

History

History

js-miniapp-sdk

README.md

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.

JS SDK Developer documentation

Table of Contents

{:.no_toc}

  • Table of contents {:toc}

Getting Started

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.getMessagingUniqueId()
    .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.getMessagingUniqueId()
    .then(id => {
    // ...

Mini App Manifest

There is a manifest for each mini app. The manifest provides the info for Android/iOS SDK to handle the mini app so the mini app developer should understand the structure and data type of manifest.

The manifest contains:

  • Required permissions
  • Optional permissions
  • Access token permissions
  • Custom metadata

Here is the example of manifest. You can also see it in our sample app.

{
  // The mini app should use "reqPermissions" for setting which permissions it requires.
  // These permissions will be requested by the host app before launching and downloading the mini app.
  // The user MUST accept these permissions before the mini app can be launched.
  "reqPermissions": [
    {
      "name": "rakuten.miniapp.user.USER_NAME",
      "reason": "Describe your reason here (optional)."
    },
    {
      "name": "rakuten.miniapp.user.PROFILE_PHOTO",
      "reason": "Describe your reason here (optional)."
    }
  ],
  // The mini app should use "optPermissions" for setting which permissions it will optionally use.
  // These permissions will be requested by the host app before launching and downloading the mini app.
  // The user can choose to either accept or deny these permissions before the mini app is launched.
  "optPermissions": [
    {
      "name": "rakuten.miniapp.user.CONTACT_LIST",
      "reason": "Describe your reason here (optional)."
    },
    {
      "name": "rakuten.miniapp.device.LOCATION",
      "reason": "Describe your reason here (optional)."
    }
  ],
  // For access tokens, can define which "audience" and "scopes" you would like permission to use
  "accessTokenPermissions": [
    {
      "audience": "rae",
      "scopes": ["idinfo_read_openid", "memberinfo_read_point"]
    },
    {
      "audience": "api-c",
      "scopes": ["your_service_scope_here"]
    }
  ],
  // The Host App can require additional keys that the mini app developer must set
  "customMetaData": {
    "exampleKey": "test"
  }
}

Mini App Features

Retrieve a unique ID

API: MiniAppFeatures.getUniqueId

Deprecated: This method will be deprecated from v2.0

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);
  });

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.

There are two types of permissions:

  • Custom permissions: Access User data or device features which the Host App controls. Displays Host App's custom permission dialog.
  • Device permissions: Access device features. Displays Android/iOS platform permission dialog.

Mini app developer can define which permissions are required and optional in mini app manifest. You do not need to request permission when declaring them as required type.

Custom Permissions

API: MiniAppFeatures.requestCustomPermissions, CustomPermissionName, CustomPermissionStatus

These permissions are related to accessing the User data or device features which the Host App controls, and the Host App will display a custom permission dialog. Multiple permissions can be requested at once. These permissions should be requested before you attempt to access the User's data or certain device features.

These permissions are requested using the MiniAppFeatures.requestCustomPermissions method.

Permission Name Description
CustomPermissionName.USER_NAME Grant access to the User's name.
CustomPermissionName.PROFILE_PHOTO Grant access to the user's Profile Photo.
CustomPermissionName.CONTACT_LIST Grant access to the user's contact list.
CustomPermissionName.ACCESS_TOKEN Grant access to the a user's access token.
CustomPermissionName.LOCATION Grant access to the device's location (custom permission only).
CustomPermissionName.SEND_MESSAGE Allow miniapp to send message to specific contact via hostapp.
CustomPermissionName.POINTS Allow miniapp to retrieve points.
CustomPermissionName.FILE_DOWNLOAD Allow miniapp to download files.
Usage example
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.',
    },
    {
      name: CustomPermissionName.ACCESS_TOKEN,
      description: 'This text will be shown to the user.',
    },
    {
      name: CustomPermissionName.LOCATION,
      description: 'This text will be shown to the user.',
    },
    {
      name: CustomPermissionName.SEND_MESSAGE,
      description: 'This text will be shown to the user.',
    },
    {
      name: CustomPermissionName.POINTS,
      description: 'This text will be shown to the user.',
    },
    {
      name: CustomPermissionName.FILE_DOWNLOAD,
      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
  });

Device Permissions

API: MiniAppFeatures.requestLocationPermission

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.

Each device permission is requested using a specific method for that permission. Device permissions also have an associated Custom permissions, so you should first request the custom permission before requesting the device permission. However, if you did not request the custom permission first, then the method will automatically request the custom permission from the user.

Permission Method Description
requestLocationPermission Grant access to the device location (both device permission & custom permission).
Usage example
// Location Permission
import miniApp from 'js-miniapp-sdk';
miniApp
  .requestLocationPermission('This description will be shown to the user.')
  .then(success => {
    console.log(success); // Allowed.
  })
  .catch(error => {
    console.error(error); // Permission is not granted due to many circumstances.
  });

Show Ads

API: Ad.loadInterstitialAd, Ad.loadRewardedAd, Ad.showInterstitialAd, Ad.showRewardedAd, Reward

Mini App SDK allows you to display ads upon requesting from a Mini App with an ad unit id. This requires you to first load an Ad by passing an ID. You can then display an Ad in the Ad Unit by passing the same ID which was used for loading.

Note that typically you should load your Ads at some point earlier than you intend to use them, such as at App launch time. You can also pre-load multiple Ads by calling MiniApp.loadInterstialAd or MiniApp.loadRewardedAd multiple times.

Currently two ad types are supported,

  1. Interstitial
  2. Rewarded
const adUnitID = 'xxx-xxx-xxxxxxxxxxxxx';

miniApp
  .loadInterstitialAd(adUnitID)
  .then(response => {
    miniApp
      .showInterstitialAd(adUnitID)
      .then(response => console.log(response))
      .catch(error => console.error(response));
  })
  .catch(error => console.error(response));
const adUnitID = 'xxx-xxx-xxxxxxxxxxxxx';

miniApp
  .loadRewardedAd(adUnitID)
  .then(response => {
    miniApp
      .showRewardedAd(adUnitID)
      .then(response => console.log(response))
      .catch(error => console.error(response));
  })
  .catch(error => console.error(response));

Events

Mini app can listen to the following events that will be sent/triggered by the Hostapp/Native SDKs to Mini app.

Mini App Events

API: MiniAppEvents

These MiniAppEvents events are more live Mini app life cycle events that will be broadcast when a event occurs

  • EXTERNAL_WEBVIEW_CLOSE

  • PAUSE

  • RESUME

    Click here to see the Code snippet 
    window.addEventListener(MiniAppEvents.EXTERNAL_WEBVIEW_CLOSE, function (e) {
  // To-do
});

Keyboard events

API: MiniAppKeyboardEvents

These MiniAppKeyboardEvents events will be triggered when a keyboard is shown or dismissed

  • KEYBOARDSHOWN

  • KEYBOARDHIDDEN

    Click here to see the Code snippet 
    window.addEventListener(MiniAppKeyboardEvents.KEYBOARDSHOWN, function (e) {
  // To-do
});

Host app events Available from v1.16.0

API: HostAppEvents

These HostAppEvents will be triggered when the host app wants to notify something to the Mini app

  • RECEIVE_JSON_INFO

    Click here to see the Code snippet 
    window.addEventListener(MiniAppKeyboardEvents.RECEIVE_JSON_INFO, function (e) {
  // To-do
});

Share Info

API: MiniAppFeatures.shareInfo,

ShareInfoType

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));

Requesting User details

API: UserInfoProvider

Please make sure that User have allowed respective custom permission before requesting the user detail.

User name

API: UserInfoProvider.getUserName, CustomPermissionName.USER_NAME

Returns the Username text from the Host app.

miniApp.user
  .getUserName()
  .then(userName => {
    console.log(userName);
  })
  .catch(error => {
    console.error(error);
  });

Profile Photo

API: UserInfoProvider.getProfilePhoto, CustomPermissionName.PROFILE_PHOTO

Returns the Profile Photo URI from the Host app.

miniApp.user
  .getProfilePhoto()
  .then(profilePhoto => {
    console.log(profilePhoto);
  })
  .catch(error => {
    console.error(error);
  });

Contact List

API: UserInfoProvider.getContacts, Contact, CustomPermissionName.CONTACT_LIST

Returns the Contact list from the Host app.

miniApp.user
  .getContacts()
  .then(contacts => {
    console.log(contacts);
  })
  .catch(error => {
    console.error(error);
  });

Access Token

API: UserInfoProvider.getAccessToken, AccessTokenData, AccessTokenScopes, CustomPermissionName.ACCESS_TOKEN

You can get an access token provided by the Host App.

There are 2 reasons your access token request can be rejected:

  • The Host App will be able to deny your request if your mini app ID is not approved to access the token.
  • Your request will also be denied by the MiniApp SDK if your audience and scopes do not match the ones defined in the Mini App Manifest

Returns the AccessTokenData list from the Host app.

AccessTokenData contains token,validUntil and scopes details.

miniApp.user
  .getAccessToken('TOKEN_AUDIENCE', ['TOKEN_SCOPE1', 'TOKEN_SCOPE2'])
  .then(data => {
    const isValid = data.validUntil.getTime() >= Date.now();
    if (isValid) {
      const token = data.token;
      // Use token
    }
  })
  .catch(error => console.error(error));

Set screen orientation

API: MiniAppFeatures.setScreenOrientation, ScreenOrientation

It is possible to change and lock device screen orientation. However, there is no guarantee that all hostapps and device OS allow the force screen change so MiniApp should not rely on this.

The support screen change cases are defined as ScreenOrientation. After finish locking, the miniapp can release the lock and grant back the normal orientation controller to device. Please use ScreenOrientation.LOCK_RELEASE

miniApp
  .setScreenOrientation(ScreenOrientation.LOCK_LANDSCAPE) // or LOCK_PORTRAIT, LOCK_RELEASE.
  .then(success => {
    console.log(success);
  })
  .catch(error => {
    console.error(error);
  });

Send message

API: ChatServiceProvider MessageToContact

Send message to the single contact

miniApp.chatService
  .sendMessageToContact(messageToContact)
  .then(contactId => {
    // contact id string.
    console.log(contactId);
  })
  .catch(error => {
    console.error(error);
  });

Send message by contact id

Please make sure that User have allowed message sending custom permission before sending message to specific contact.

miniApp.chatService
  .sendMessageToContactId(id, messageToContact)
  .then(contactId => {
    console.log(contactId);
  })
  .catch(error => {
    console.error(error);
  });

Send message to multiple contacts

miniApp.chatService
  .sendMessageToMultipleContacts(messageToContact)
  .then(contactIds => {
    // contact id string array.
    console.log(contactIds);
  })
  .catch(error => {
    console.error(error);
  });

Open device camera

Please make sure that capture attribute is available, it will open device camera from miniapp.

<html>
  ...
  <div data-role="fieldcontain">
    <label for="name">Open file chooser to select file using camera</label>
    <input id="fileselect" type="file" accept="image/*" capture="environment" />
  </div>
  ...
</html>

Set Close alert Available from v1.15.0

When a Mini app is closed, you can set the close confirmation popup which the host app can show before closing the miniapp. Host app can decide whether to show/hide the confirmation popup before closing the miniapp. 
const alertInfo: CloseAlertInfo = {
  shouldDisplay: true,
  title: "Info",
  description: "Would you like to close the miniapp?",
};
MiniApp.miniappUtils
  .setCloseAlert(alertInfo)
  .then(() => {
  })
  .catch((error) => {
  });
});

Universal Bridge Available from v1.16.0

MiniApp users can send any JSON/String from MiniApp to HostApp as well as receive any JSON/String from HostApp to MiniApp.

Send a JSON/String from MiniApp to HostApp

Please use the following example in the MiniApp:

import miniApp from 'js-miniapp-sdk';
const inputValue = '{"data":"This is a sample json information"}';
const info = { content: inputValue };
miniApp.universalBridge
  .sendJsonToHostapp(info)
  .then(success => {
    console.log(success);
  })
  .catch(error => {
    console.error(error);
  });

Send a UniversalBridgeInfo from MiniApp to HostApp

Please use the following example in the MiniApp:

import miniApp from 'js-miniapp-sdk';
const info: UniversalBridgeInfo = {
  key: "launch",
  value: "deeplinkurl",
  description: "Description of the info that is passed",
};
const info = { content: inputValue };
miniApp.universalBridge
  .sendInfoToHostapp(info)
  .then(success => {
    console.log(success);
  })
  .catch(error => {
    console.error(error);
  });

Receive a JSON/String from HostApp to MiniApp

Please use the following example in the MiniApp:

import HostAppEvents from 'js-miniapp-sdk';
window.addEventListener(HostAppEvents.RECEIVE_JSON_INFO, function(e) {
  let message = e.detail.message;
  console.log(message);
});

Close miniapp Available from v1.16.0

When the miniapp want's to close, they can use this interface to close by itself. Calling this interface, it would let know the host app know that the miniapp wants to close. Host app can decide if it can proceed with the flow. 
MiniApp.miniappUtils.closeMiniApp(true).catch((error) => {
});

In-App Purchases

You can perform the in-app purchases for the products available for In-App Purchases associated with Google Play™.

Get all products list

This will retrieve the list of products details available for In-App Purchase associated with Google Play™. This will return only the list of products associated with Mini app in the platform

import miniApp from 'js-miniapp-sdk';
miniApp.purchases
      .getAllProducts()
      .then((success) => {
        console.log(success);
      })
      .catch((error) => {
        console.error(error);
      });

Purchase a product with product id

This will request for the In-app Purchase of a product with product id associated with Google Play™. Returns the PurchasedProduct object with transaction details.

import miniApp from 'js-miniapp-sdk';
miniApp.purchases
      .purchaseProductWith(productId)
      .then((success) => {
        console.log(success);
      })
      .catch((error) => {
        console.error(error);
      });

Consume a purchase

This will request to Consume the product that is purchased using the purchaseProductWith API Returns the PurchasedProduct object with transaction details.

import miniApp from 'js-miniapp-sdk';
miniApp.purchases
      .consumePurchaseWith(productId, transactionId)
      .then((success) => {
        console.log(success);
      })
      .catch((error) => {
        console.error(error);
      });

Advanced Usage

Errors management

Access Token error

When an access token is requested, different Error subtypes can be thrown to the MiniApp:

Here is a complete example of you can manage Access Token errors:

miniApp.user.getAccessToken("TOKEN_AUDIENCE", ["TOKEN_SCOPE1","TOKEN_SCOPE2"])
  .then(data => {
      ...
  })
  .catch(error => {                            //Example of values :
      console.error(error.name);              // AudienceNotSupportedError
      console.error(error.message);          //  The value passed for 'audience' is not supported.

      if (error instanceof AuthorizationFailureError) {
          // handle error
      } else if (error instanceof AudienceNotSupportedError) {
          // handle error
      } else if (error instanceof ScopesNotSupportedError) {
          // handle error
      } else if (error instanceof MiniAppError) {
          // handle error
      } else {
          // unexepected error caused by SDK
      }
  })

Check Android/iOS device

API: Platform.getPlatform

You can detect whether your mini app is running on an Android/iOS by using

const platform = miniApp.getPlatform();
//platform value here can be `Android`, `iOS` or `Unknown`.

When it is not running by Android/iOS, the return value is Unknown.

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 return a mock value instead of calling the SDK method.

Click to expand code example 
import miniApp from 'js-miniapp-sdk';

const platform = miniApp.getPlatform();

function getId() {
  if (platform != 'Unknown') {
    return miniApp
      .getUniqueId()
      .then(id => {
        console.log(id);
      })
      .catch(error => {
        console.error(error);
      });
  } else {
    return Promise.resolve('mock_unique_id_value');
  }
}

Troubleshooting & FAQs

Error: "Uncaught TypeError: Cannot read property 'getUniqueId' of undefined"

This is an error that you could see on Android devices when using any of the SDK functions.

Please ensure that you have defined a <title> tag within your HTML document's <head> before the Mini App SDK <script> tag. For example:

<head>
  <title>My Mini App title</title>
  <script src="miniapp.bundle.js"></script>
  <head></head>
</head>

In the Android SDK, we will inject some necessary JavaScript from the native side, and we do this after receiving a callback that the mini app's <title> has been set. So if you do not set a <title>, then the JavaScript will be injected at an unpredictable time and you could see errors when trying to use SDK functions.

Changelog

See the full CHANGELOG.