Первые шаги

Библиотека VK Bridge позволяет приложениям (мини-приложениям и играм) использовать API ВКонтакте и API операционной системы, установленной на устройствах пользователей. Библиотека служит для отправки и получения событий.

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

Если ранее вы не работали с API ВКонтакте, рекомендуем прочитать раздел Использование API.

Если ранее вы не работали с React, советуем ознакомиться с документацией к библиотеке.

NPM: vk-bridge

GitHub: vk-bridge

Как использовать библиотеку VK Bridge

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

1.
Создайте проект мини-приложения.
2.
Подключите VK Bridge.
3.
Вызовите событие VK Bridge.
4.
Обработайте вернувшийся результат:
- •
  Метод bridge.send.
- •
  Метод bridge.subscribe.

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

Подключение VK Bridge

Если вы используете библиотеку для создания шаблона, отдельно подключать библиотеку VK Bridge не нужно.

Мы рекомендуем отправлять сообщение как можно раньше при запуске мини-приложения. В идеале — после выполнения минимума начальных действий и до массовой загрузки ресурсов. Допустимый интервал — 30 секунд после старта.

Обратите внимание! В коде приложения обязательно нужно вызывать событие инициализации VKWebAppInit, иначе приложение не запустится.

Через пакет NPM

1.

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

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

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

Shellnpm install @vkontakte/vk-bridge || yarn add @vkontakte/vk-bridge
3.

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

JavaScriptimport bridge from '@vkontakte/vk-bridge'; // Отправляет событие инициализации нативному клиенту bridge.send("VKWebAppInit");

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

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

1.

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

В репозитории VK Bridge этот файл находится в папке dist. Мы рекомендуем ссылаться на копию файла, расположенную на сервисе unpkg.com. В этом случае вы автоматически будете получать последнюю версию библиотеки и вам не нужно будет самостоятельно следить за выходом её обновлений.

HTML<script src="https://unpkg.com/@vkontakte/vk-bridge/dist/browser.min.js"></script>
2.

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

HTML<script> // Отправляет событие инициализации нативному клиенту vkBridge.send('VKWebAppInit'); </script>

Обратите внимание, что когда вы включаете .js-файл библиотеки в HTML-код своих страниц, то в JavaScript-коде надо использовать имя объекта vkBridge, а не bridge.

Вызов события VK Bridge

Используйте события объекта bridge:

JavaScript

// Подписывается на события, отправленные нативным клиентом
bridge.subscribe((e) => console.log(e)); 
    
// Отправляет событие нативному клиенту
bridge.send("VKWebAppInit", {});      
    
// Проверяет, поддерживается ли событие на текущей платформе
if (bridge.supports("VKWebAppResizeWindow")) {
  bridge.send("VKWebAppResizeWindow", {"width": 800, "height": 1000});
}

Список всех событий VK Bridge.

Обработка результата

Метод `bridge.send`

При использовании метода bridge.send вернётся промис. Работа с промисами не требует подключения дополнительных библиотек.

JavaScript

// Отправка события
bridge.send('VKWebAppGetEmail')
  .then((data) => {
    if (data.result) {
      // Обработка события в случае успеха
      console.log(data.email);
    } else {
      // Ошибка
    }
  })
  .catch((error) => {
    // Обработка события в случае ошибки
    console.log(error);
  });

Подробнее о промисах:

•

developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise

•

learn.javascript.ru/promise

Метод `bridge.subscribe`

При использовании метода bridge.subscribe в общем случае вернётся событие:

•
c постфиксом Result, если метод выполнился успешно;
•
с постфиксом Failed, если метод выполнился с ошибкой.

Обратите внимание! Также бывают события с другими постфиксами. Они подробно описаны в разделе конкретного события.

JavaScript

// Подписывается на события, отправленные нативным клиентом
bridge.subscribe(event => {
  if (!event.detail) {
    return;
  }

  switch(event.detail.type) {
    case 'VKWebAppOpenCodeReaderResult':
      if (event.detail.data.result) {
        // Обработка события в случае успеха
        console.log(event.detail.data.result);
      } else {
        // Ошибка
      }
      break;
    case 'VKWebAppOpenCodeReaderFailed':
      // Обработка события в случае ошибки
      console.log(event.detail.data.error_type, event.detail.data.error_data);      
      break;
  }
});

Обработка ошибок VK Bridge

При работе с VK Bridge в ответе могут возвращаться ошибки в объекте data.

JSON

{
  "type": "EventNameFailed", 
  "data": { 
    "error_type": "...",
    "error_data": {}
  } 
}

`"data"`

Параметр	Тип	Описание
`error_type`	`string`	Тип ошибки. Возможные значения: • `client_error` — ошибки, возникающие на клиенте; • `api_error` — ошибки API; • `auth_error` — ошибки авторизации.
`error_data`	`object`	Дополнительные данные ошибки, которые зависят от `error_type`. См. описание ниже.
`request_id`	`integer`	Информация, которая используется для внутренних целей: успешного выполнения или отклонения промиса.

`"error_type": "client_error"`

К этому типу относятся ошибки, связанные с некорректным синтаксисом событий VK Bridge. Параметры объекта error_data:

Параметр	Тип	Описание
`error_code`	`integer`	Код ошибки. См. список возможных значений в таблице ниже.
`error_reason`	`string`	Описание ошибки.
`error_description`	`string`	Необязательное поле. Детальное описание ошибки.

Код ошибки (`error_code`)	Описание (`error_reason`)
1	Unknown error
2	Missing required params
3	Connection lost
4	User denied
5	Invalid params
6	Unsupported platform
7	No device permission
8	Need user permission
9	This action cannot be performed in the background
10	Requests limit reached
11	Access denied
12	Uninitialized App
13	Custom error for every handler

`"error_type": "api_error"`

К этому типу относятся ошибки, перечисленные на странице Возвращаемые ошибки или в описании метода. Параметры объекта error_data:

Параметр	Тип	Описание
`error_code`	`integer`	Код ошибки.
`error_msg`	`string`	Описание ошибки.
`request_params`	`array`	Массив, содержащий параметры запроса к API.

`"error_type": "auth_error"`

К этому типу относятся ошибки, которые возвращаются в ходе авторизации. Параметры объекта error_data:

Параметр	Тип	Описание
`error`	`integer`	Код ошибки.
`error_reason`	`string`	Описание ошибки.
`error_description`	`array`	Необязательное поле. Детальное описание ошибки.

Первые шаги

Как использовать библиотеку VK Bridge

Подключение VK Bridge

Через пакет NPM

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

Вызов события VK Bridge

Обработка результата

Метод bridge.send

Метод bridge.subscribe

Обработка ошибок VK Bridge

"data"

"error_type": "client_error"

"error_type": "api_error"

"error_type": "auth_error"

Метод `bridge.send`

Метод `bridge.subscribe`

`"data"`

`"error_type": "client_error"`

`"error_type": "api_error"`

`"error_type": "auth_error"`