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.
Table of Contents
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.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 => {
// ...
Mini App Features
Retrieve a unique ID
API: MiniAppFeatures.getUniqueId
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
API: MiniAppFeatures.requestCustomPermissions, CustomPermissionName, CustomPermissionStatus, MiniAppFeatures.requestLocationPermission
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.
Permission | Type | Method | Description |
---|---|---|---|
Location | Custom & Device | requestLocationPermission() |
Custom and device permission respectively for location. Currently supported types are CustomPermissionName.LOCATION & DevicePermission.LOCATION .Location data can be accessible via geolocation request ( navigator.geolocation ). |
User Data | Custom | requestCustomPermissions() |
Custom permissions for User Data. Currently supported types are CustomPermissionName.USER_NAME , CustomPermissionName.PROFILE_PHOTO , and CustomPermissionName.CONTACT_LIST . These permissions should be requested before you attempt to access the User’s data. |
Usage example
Simply call available permission request methods from miniApp
.
// 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.
});
// 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
});
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,
- Interstitial
- 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) );
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
You can get an access token provided by the Host App. The Host App will be able to deny your request if your mini app ID is not approved to access the token.
This will return an object containing token
and validUntil
keys.
miniApp.user.getAccessToken()
.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);
});
Advanced Usage
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>
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.