Инвосбокс MiniApp SDK

Библиотека minapp-sdk позволяет мини-приложениям использовать API Инвойсбокс и API операционной системы, установленной на устройстве пользователя.

Библиотека является мостом между мини-приложениями, работающими на стороне пользователя, и клиентской частью Инвойсбокс (десктопной версией платёжного сервиса, мобильной версией платёжного сервиса или мобильным приложением). Именно они обмениваются данными с серверами Инвойсбокс, а библиотека работает как посредник на стороне пользователя.

• NPM: minapp-sdk
• GitHub: minapp-sdk

Как использовать библиотеку MiniApp SDK

Чтобы использовать библиотеку:

1. Создайте проект мини-приложения
2. Подключите MiniApp SDK
3. Используйте методы:
   • Метод invoiceboxMinapp.connect. Установить соединение с родительским окном.
   • Метод invoiceboxMinapp.disconnect. Разорвать соединение с родительским окном.
   • Метод invoiceboxMinapp.isConnected. Узнать, установлено ли соединение с родительским окном.
   • Метод invoiceboxMinapp.getInitialData. Получить данные покупателя от родительского окна.
   • Метод invoiceboxMinapp.matchMetaDataValues. Узнать, есть ли в метаданных нужная информация.
   • Метод invoiceboxMinapp.getMetaDataValues. Получить, из метаданных нужную информацию.
4. Обработайте события:
   • Событие invoiceboxMinapp.onHeightChange. Сообщить родительскому окну параметры высоты мини-приложения.
   • Событие invoiceboxMinapp.onDone. Сообщить родительскому окну о готовности заказа к оплате.
   • Событие invoiceboxMinapp.onError. Сообщить родительскому окну об ошибке в мини-приложении.
   • Событие invoiceboxMinapp.onLink. Сообщить родительскому окну о необходимости открыть страницу.
   • Событие invoiceboxMinapp.onUnavailable. Сообщить родительскому окну, что мини-приложение недоступно.

Инструкция ниже актуальна для любой операционной системы. Для первых шагов потребуется знание языка JavaScript и умение работать с командной строкой.

Подключение MiniApp SDK

Родительским окном мини-приложения может быть iframe или WebView.

Через пакет NPM

Перейдите в созданный проект мини-приложения:

cd <ПУТЬ_К_МИНИ_ПРИЛОЖЕНИЮ>

Установите библиотеку:

npm install @invoicebox/minapp-sdk || yarn add @invoicebox/minapp-sdk

Инициализируйте MiniApp SDK в файле index.js:

import { invoiceboxMinapp } from '@invoicebox/minapp-sdk';

invoiceboxMinapp.connect();

Включение скрипта в HTML-код страницы

Этот способ подходит, если вы не используете менеджеры пакетов, такие как npm или yarn, для создания своего HTML-приложения.

В код каждой HTML-страницы, где вы будете вызывать библиотеку, добавьте ссылку на файл index.min.js

В репозитории MiniApp SDK этот файл находится в папке cjs (commonjs modules). Мы рекомендуем ссылаться на копию файла, расположенную на сервисе unpkg.com. В этом случае вы автоматически будете получать последнюю версию библиотеки и вам не нужно будет самостоятельно следить за выходом её обновлений.

<!-- Если требуется зафиксировать версию, например, 3.0.1 -->
<script src="https://unpkg.com/@invoicebox/minapp-sdk@3.0.1/cjs/index.min.js"></script>

<!-- Крайняя версия (следует использовать аккуратно, так как крайние изменения могут быть не совместимы) -->
<script src="https://unpkg.com/@invoicebox/minapp-sdk/cjs/index.min.js"></script>

В коде каждой HTML-страницы, где вы будете вызывать библиотеку, инициализируйте MiniApp SDK

<script>
  invoiceboxMinapp.connect();
</script>

События и методы

Метод connect

Для того, чтобы установить соединение с родительским окном, воспользуйтесь методом connect.

connect(): void;

Метод disconnect

Чтобы разорвать соединение с родительским окном, воспользуйтесь методом disconnect.

disconnect(): void;

Метод isConnected

Чтобы узнать установлено ли соединение с родительским окном, воспользуйтесь методом isConnected.

isConnected(): boolean;

Метод getInitialData

Для того, чтобы получить данные покупателя для оформления заказа, воспользуйтесь методом getInitialData.

getInitialData(): Promise<{
    shopId?: number;
    userEmail: string;
    userName: string;
    userPhone: string;
    fullHeight: boolean;
    locale: string;
} & (
    | {
          orderContainerId?: never;
          minappType: 'order';
      }
    | {
          orderContainerId: string;
          minappType: 'suborder';
      }
)>

• minappType - значение order указывает, что мини-приложение работает в режиме основного заказа, значение suborder - в режиме дополнительной услуги
• orderContainerId - обязательно, если minappType: 'suborder', отсутствует, если minappType: 'order', идентификатор родительского заказа в случае, если заказ является дополнительной услугой
• shopId - опционально, идентификатор точки продаж, если мини-приложение работает с множеством точек продаж
• userEmail - адрес электронной почты покупателя
• userName - имя покупателя
• userPhone - номер мобильного телефона покупателя
• fullHeight - флаг сообщающий, что мини-приложение должно занять всю высоту контейнера, в котором располагается
• locale - локаль

Пример использования

invoiceboxMinapp.getInitialData().then(console.log);

/*
{
    minappType: 'suborder',
    orderContainerId: '3c15a3d1-3da8-4ba8-87e5-2dba828299fa',
    shopId: 123,
    userEmail: 'email@example.com',
    userName: 'Иван Иванов',
    userPhone: '+71231234567',
    fullHeight: false,
    locale: 'ru';
}
*/

Метод matchMetaDataValues

Общая информация по наличию метаданных в заказах описана в документации. Для того, чтобы узнать есть ли нужная информация в метаданных, воспользуйтесь методом matchMetaDataValues.

matchMetaDataValues(targetKey: string, targetValues: unknown[]): Promise<boolean>

• targetKey - ключ (название свойства) по которому будет осуществлен поиск
• targetValues - массив возможных значений, если хотя бы одно значение из этого массива совпадет со значемием в метаданных, функция вернет true, в противном случае false

Пример использования

/*
  если метаданные содержат поле iataCode: "SU" или iataCode: "LED", метод вернет true
*/
invoiceboxMinapp
  .matchMetaDataValues("iataCode", ["SU", "LED"])
  .then((isMatch) => {
    if (isMatch) {
      // do something
    }
  });

Метод getMetaDataValues

Для того, чтобы получить нужную информацию из метаданных, воспользуйтесь методом getMetaDataValues.

getMetaDataValues(targetKey: string | string[]): Promise<unknown[]>

• targetKey - ключ (название свойства) или массив ключей по котороым будет осуществлен поиск

Пример использования

invoiceboxMinapp
  .getMetaDataValues(["flightNumber", "departureTime"])
  .then(console.log);

/*
  ['NDJ37S', '2022-03-04T20:15:00+03:00']
*/

Событие onHeightChange

Для управления высотой мини-приложения на платёжной странице используется метод onHeightChange. Мини-приложение может задать высоту, которая требуется для корректного отображения мини-приложения на платёжной странице.

onHeightChange(height: number): void;

Пример использования

const Conatiner = ({ children }: { children: ReactNode }) => {
  const [elRef, setElRef] = useState<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!elRef) return;
    const observer = new ResizeObserver(() => {
      invoiceboxMinapp.onHeightChange(elRef.offsetHeight);
    });
    observer.observe(elRef);
    return () => observer.disconnect();
  }, [elRef, child]);

  return <div ref={elRef}>{children}</div>;
};

Событие onDone

После того, как мини-приложение успешно добавило новый заказ в существующий orderContainer или создало новый, необходимо вызвать метод onDone. paymentUrl приходит от сервера в момент создания заказа.

Если закз успешно создан, но будет оплачен не через систему инвойсбокс, допускается вызов метода без передачи платежной ссылки: onDone(null). Пользователь увидит, что мини-приложение успешно завершло работу, но переадресации для оплаты не произойдет.

onDone(paymentUrl: string | null): void

Пример использования

createOrderRequest(someData).then((response) => {
  invoiceboxMinapp.onDone(response.data.url);
});

Событие onError

В случае возникновения ошибки в мини-приложении (например, при оформлении заказа, при взаимодействии с API Инвойсбокс и т.д.), необходимо вызвать метод onError. Родительская страница уведомит пользователя об ошибке. Функция принимает один опциональный строковый аргумент - пользовательское сообщение. Если сообщение есть, то оно отобразится. Если нет, то отобразится сообщение по умолчанию Что-то пошло не так.

onError(message?: string): void

Пример использования

// Пользователь увидит "Ошибка создания заказа"
invoiceboxMinapp.onError("Ошибка создания заказа");

// Пользователь увидит "Что-то пошло не так"
invoiceboxMinapp.onError();

Событие onLink

Метод onLink позволяет произвести переадресацию пользователя по ссылке в родительском окне, как будто переадресация была вызвана не в контексте iframe/webview, а в контексте родительской страницы.

onLink(href: string): void

Пример использования

// На платёжной странице будет открыта новая вкладка с Google страницей
// это никак не повлияет на работу мини-приложения
invoiceboxMinapp.onLink("https://www.google.ru");

Событие onUnavailable

Метод onUnavailable позволяет сообщить родительскому окну, что мини-приложение недоступно. Мини-приложение будет закрыто. Пользователь увидит соответствующее сообщение.

onUnavailable(): void

Пример использования

invoiceboxMinapp.onUnavailable();

Читать далее »