@appboxo/js-sdk

AppBoxo JS SDK

Appboxo JS SDK is a connection bridge between miniapp and native app, that has a rich API features that make your miniapp feel like a native. Using Appboxo JS SDK, host app can pass the user email to miniapp, to register the user automatically in the miniapp.

Usage

import appboxoSdk from '@appboxo/js-sdk';

// Sends event to client
appboxoSdk.send('AppBoxoWebAppInit');

// Subscribes to event, sended by client
appboxoSdk.subscribe(e => console.log(e));

For use in a browser, include the file dist/index.umd.js and use as follows

<script src="dist/index.umd.js"></script>

<script>
  // Sends event to client
  appboxoSdk.send('AppBoxoWebAppInit');
</script>

Native clients

Native clients (both Android and iOS) should call this to pass data to mini apps:

window.dispatchEvent(new window.CustomEvent('AppBoxoWebAppEvent', {
  bubbles: false,
  cancelable: false,
  detail: {
    type: 'AppBoxoWebAppGetInitData',
    data: {
      app_id: 234234,
      client_id: 344343,
      payload: 'asdlj2323ljaoiw',
      token: 'qerljljqwerqwe',
      request_id: 1
    }
  }
}))

Important

If an event triggered from mini app has request_id inside data (like on the example above), than it means that sendPromise has been called and same event with request_id and event type should be returned to resolve this promise.

Authentication

appboxoSdk.login(optionalProps)

Sends a message to native client to open confirm modal with default confirmation message. Upon confirmation it sends request to platform and returns resolved authentication token promise to miniapp.

Parameters

• optionalProps optional Props to extend default login behavior

Example

try {
  const token = await appboxoSdk.login({
    confirmModalText: 'This is my custom confirmation message',
    postConfirmCallback: (isConfirmed) => { console.log('Confirmation status: ', isConfirmed) }
  });
} catch (error) {
  // Handling an error
}

appboxoSdk.logout()

Sends a message to native client to clear authentication tokens.

API Reference

appboxoSdk.sendPromise(method[, params])

Sends a message to native client and returns the Promise object with response data

Parameters

• method required The AppBoxo js sdk method
• params optional Message data object

Example

// Sending event to client
appboxoSdk
  .sendPromise('AppBoxoWebAppGetInitData')
  .then(data => {
    // Handling received data
    console.log(data.email);
  })
  .catch(error => {
    // Handling an error
  });

You can also use imperative way

try {
  const data = await appboxoSdk.sendPromise('AppBoxoWebAppGetInitData');

  // Handling received data
  console.log(data.email);
} catch (error) {
  // Handling an error
}

appboxoSdk.send(method[, params])

Sends a message to native client

Parameters

• method required The AppBoxo js sdk method
• params optional Message data object

Example

// App initialization
appboxoSdk.send('AppBoxoWebAppInit');

// Opening images
appboxoSdk.send('AppBoxoWebAppShowImages', {
  images: [
    "https://pp.userapi.com/c639229/v639229113/31b31/KLVUrSZwAM4.jpg",
    "https://pp.userapi.com/c639229/v639229113/31b94/mWQwkgDjav0.jpg",
    "https://pp.userapi.com/c639229/v639229113/31b3a/Lw2it6bdISc.jpg"
  ]
}

appboxoSdk.subscribe(fn)

Subscribes a function to events listening

Parameters

• fn required Function to be subscribed to events

Example

// Subscribing to receiving events
appboxoSdk.subscribe(event => {
  if (!event.detail) {
    return;
  }

  const { type, data } = event.detail;

  if (type === 'AppBoxoWebAppOpenCodeReaderResult') {
    // Reading result of the Code Reader
    console.log(data.code_data);
  }

  if (type === 'AppBoxoWebAppOpenCodeReaderFailed') {
    // Catching the error
    console.log(data.error_type, data.error_data);
  }
});

// Sending method
appboxoSdk.send('AppBoxoWebAppOpenCodeReader', {});

appboxoSdk.unsubscribe(fn)

Unsubscribes a function from events listening

Parameters

• fn required Event subscribed function

Example

const fn = event => {
  // ...
};

// Subscribing
appboxoSdk.subscribe(fn);

// Unsubscribing
appboxoSdk.unsubscribe(fn);

appboxoSdk.supports(method)

Checks if an event is available on the current device

Parameters

• method required The AppBoxo js sdk method

appboxoSdk.isWebView()

Returns true if AppBoxo js sdk is running in mobile app, or false if not