# Правила размещения рекламы в игровых приложениях и сервисах VK Mini Apps
Реклама, размещаемая в приложении (тексты и изображения), должна соответствовать [Правилам пользования Сайтом ВКонтакте](https://vk.com/terms), **п. 3** [Правил размещения рекламы](https://vk.com/ads?act=office_help&terms) и законодательству РФ, в частности Федеральному закону «О рекламе» от 13.03.2006 No. 38-ФЗ. 

## Рекламные форматы
Допускается использовать следующие виды рекламных форматов:
1. **Рекламный баннер** — таргетированный рекламный блок с объявлением, который может содержать небольшой текст, одно изображение и кнопку перехода.
2. **Медиареклама (интерстициальная, мид-ролл)** — рекламный блок длиною до 30 секунд, который показывается на весь экран в промежуточные моменты использования приложения.

## В приложениях и сервисах запрещается:
**1.1.** Использовать сторонние рекламные системы монетизации (баннерные и тизерные сети, CPA-системы и другие) и сторонние системы показов медиарекламы, за исключением случаев обмена трафиком между приложениями.
**1.2.** Размещать рекламу в любых всплывающих окнах, а также в окне, открывающемся при просмотре приложения со стены пользователя.
**1.3.** Перекрывать рекламным баннером функциональную область приложения (область, которая необходима пользователю для полноценного взаимодействия с функциями приложения).
**1.4.** Перекрывать рекламный баннер другими функциональными элементами приложения.
**1.5.** Видоизменять рекламный баннер таким образом, чтобы он мог ввести пользователя в заблуждение относительно результатов перехода по нему, а также ограничивать возможность его закрытия. 
> Рекламный баннер и все его составляющие всегда должны отображаться полностью и не сливаться по цвету с фоном в любой отдельный момент времени.
**1.6.** Размещать активную область баннера (нажатие на которую приводит к переходу) ближе, чем на 20 пикселей к другим функциональным элементам приложения. В приложениях, требующих активных и частых нажатий пользователя, не допускается размещать рекламные баннеры вокруг функциональной области приложения.
**1.7.** Неожиданно показывать баннеры в тех областях приложения, на которые пользователь до того нажимал, взаимодействуя с основной функциональностью.
**1.8.** Неожиданно прерывать работу приложения показом медиарекламы.
> Показывать рекламный блок в формате медиарекламы допустимо только в двух случаях:
> а) во время явного процесса загрузки (например, для игровых приложений — следующего уровня или локации); 
> б) по нажатию на кнопку за обозначенный явным образом бонус в рамках функциональности приложения.
**1.9.** Показывать медиарекламу при запуске приложения, а также размещать рекламные баннеры на стартовой странице приложения (во время онбординга).
**1.10.** Показывать более одной медиарекламы подряд.
**1.11.** Предоставлять пользователям денежную или иную материальную компенсацию за просмотр рекламы, в том числе в виде игровой валюты или иных ценностей, если имеется возможность их вывода или конвертации в денежные средства.

Правила | Правила размещения рекламы в игровых приложениях и сервисах VK Mini Apps

API ВКонтакте

# Authorization Code Flow для получения ключа доступа сообщества

Используйте Authorization Code Flow для вызова методов API ВКонтакте с серверной части  вашего приложения (например, из PHP). Ключ доступа, полученный таким способом, не привязан к IP-адресу.

## Получение списка администрируемых сообществ

Получить ключ доступа сообщества через OAuth может только его администратор. Чтобы получить ключи доступа сразу для всех или нескольких сообществ пользователя, мы рекомендуем добавить этот дополнительный шаг в процесс авторизации.

Получите ключ доступа пользователя ([для работы с клиента](api/access-token/implicit-flow-user) или [для работы с сервера](api/access-token/authcode-flow-user)) с правами `scope`= `groups` и сделайте запрос к методу [groups.get](groups.get) с параметром `filter`= `admin`, чтобы получить список идентификаторов администрируемых сообществ.

Затем используйте все полученные значения или их часть в качестве параметра `group_ids`.

## Открытие диалога авторизации

Необходимо перенаправить браузер пользователя по адресу
[`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор  вашего приложения.  
* `redirect_uri` (**обязательный**) — адрес, на который будет передан `code` (домен указанного адреса должен соответствовать основному домену в настройках приложения и перечисленным значениям в списке доверенных `redirect uri` — адреса сравниваются вплоть до `path`-части).  
* `group_ids` (**обязательный**) — идентификаторы сообществ, для которых необходимо получить ключ доступа. Параметр должен представлять собой строку, содержащую значения без знака «минус», разделенные запятой.  
* `display` — Указывает тип отображения страницы авторизации. Поддерживаются следующие варианты: 
    *  `page` — форма авторизации в отдельном окне;  
    *  `popup` — всплывающее окно;  
    *  `mobile` — авторизация для мобильных устройств (без использования Javascript) 
* `scope` — битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации и запросить отсутствующие.  
* `response_type` — тип ответа, который вы хотите получить. Укажите `code`.  
* `v` (**обязательный**) — [версия API](reference/versions), которую вы используете. Актуальная версия: **:version**.  
* `state` — произвольная строка, которая будет возвращена вместе с результатом авторизации.  

Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&display=page&redirect_uri=http://example.com/callback&group_ids=123456,654321&scope=messages&response_type=code&v=:version
```

Если пользователь не вошел на сайт, то в диалоговом окне ему будет предложено ввести свой логин и пароль. 

## Разрешение прав доступа

После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра `scope`. Полный список настроек доступен в разделе [прав доступа приложений](reference/access-rights).  

Сейчас для ключей доступа сообщества приложение любого типа может запрашивать права `manage`,`messages`,`photos`,`docs`. Методы, доступные с ключом доступа сообщества, помечены в общем [списке](reference) специальным значком.

## Получение code

После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу `redirect_uri`, указанному при открытии диалога авторизации. При этом код для получения ключа доступа `code` будет передан в `GET`-параметре на указанный адрес: 

```
REDIRECT_URI?code=7a6fa4dff77a228eeda56603b8f53806c883f011c40b72630bb50df056f6479e52a
```

Параметр `code` может быть использован в течение 1 часа для получения ключа доступа к API `access_token` с  вашего сервера.

В случае возникновения ошибки браузер пользователя будет перенаправлен с кодом и описанием ошибки: 

```
REDIRECT_URI?error=invalid_request&error_description=Invalid+display+parameter
```

## Получение access_token

Для получения `access_token` необходимо выполнить запрос с  вашего сервера на [https://oauth.vk.com/access_token](https://oauth.vk.com/access_token), передав следующие параметры:

* `client_id` (**обязательный**) — Идентификатор  вашего приложения  
* `client_secret` (**обязательный**) — Защищенный ключ  вашего приложения (указан в настройках приложения)  
* `redirect_uri` (**обязательный**) — URL, который использовался при получении `code` на первом этапе авторизации. Должен быть аналогичен переданному при авторизации.  
* `code` (**обязательный**) — Временный код, полученный после прохождения авторизации. 

Пример запроса:

```
https://oauth.vk.com/access_token?client_id=1&client_secret=H2Pk8htyFD8024mZaPHm&redirect_uri=http://mysite.ru&code=7a6fa4dff77a228eeda56603b8f53806c883f011c40b72630bb50df056f6479e52a
```

В результате выполнения данного запроса ваш сервер получит следующий JSON:

```JSON
{
   "access_token_123456": "533bacf01e11f55b536a565b57531ac114461ae8736d6506a3",

   "access_token_654321": "a740d2bfe91caaa6eab794e1168da38cdaedc93c92f233638f",

   "groups": [
    {
      "group_id": 123456,
      "access_token": "533bacf01e11f55b536a565b57531ac114461ae8736d6506a3"
    },
    { 
      "group_id": 654321,
      "access_token": "a740d2bfe91caaa6eab794e1168da38cdaedc93c92f233638f"
    }
]

   "expires_in": 0

}
```

В поле `groups` возвращается массив объектов с полями `group_id` (`integer`)  — идентификатор сообщества   и `access_token` (`string`) — ключ доступа сообщества.

Старые поля `access_token` использовать не рекомендуется, они будут упразднены в будущих версиях API.

В случае ошибки будут переданы параметры `error` и `error_description`. 

```JSON
{
  "error": "invalid_grant",
  "error_description": "Code is expired."
}

```

Использование API | Ключ доступа | Authorization Code Flow для получения ключа доступа сообщества

# Authorization Code Flow для получения ключа доступа пользователя

Используйте Authorization Code Flow для вызова методов API ВКонтакте с серверной части вашего приложения (например, из PHP). Ключ доступа, полученный таким способом, не привязан к IP-адресу, но набор прав, которые может получить приложение, ограничен из соображений безопасности.

## Открытие диалога авторизации

Необходимо перенаправить браузер пользователя по адресу
[`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения.  
* `redirect_uri` (**обязательный**) — адрес, на который будет передан `code` (домен указанного адреса должен соответствовать основному домену в настройках приложения и перечисленным значениям в списке доверенных `redirect uri`, адреса сравниваются вплоть до `path`-части).  
* `display` — указывает тип отображения страницы авторизации. Поддерживаются следующие варианты: 
    *  `page` — форма авторизации в отдельном окне;  
    *  `popup` — всплывающее окно;  
    *  `mobile` — авторизация для мобильных устройств (без использования Javascript)  Если пользователь авторизуется с мобильного устройства, будет использован тип `mobile`. 
* `scope` –  битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации пользователя и запросить отсутствующие.  
* `response_type` — тип ответа, который вы хотите получить (укажите `code`).  
* `state` — произвольная строка, которая будет возвращена вместе с результатом авторизации.  

Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&display=page&redirect_uri=http://example.com/callback&scope=friends&response_type=code&v=:version
```

Если пользователь не вошел на сайт, то в диалоговом окне ему будет предложено ввести свой логин и пароль. 

## Разрешение прав доступа

После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра `scope`. Полный список настроек доступен в разделе [прав доступа приложений](reference/access-rights).  

Обратите внимание, что некоторые [права доступа](reference/access-rights)  пользователя из списка (например, `messages`) могут быть запрошены только Standalone-приложением — что означает необходимость использования [Implicit Flow](api/access-token/implicit-flow-user) для запроса таких прав. 

## Получение code

После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу `redirect_uri`, указанному при открытии диалога авторизации. При этом код для получения ключа доступа `code` будет передан как `GET`-параметр: 

```
REDIRECT_URI?code=7a6fa4dff77a228eeda56603b8f53806c883f011c40b72630bb50df056f6479e52a 
```

Параметр `code` может быть использован в течение 1 часа для получения ключа доступа к API `access_token` с вашего сервера. 

В случае возникновения ошибки браузер пользователя будет перенаправлен с кодом и описанием ошибки: 

```
REDIRECT_URI?error=invalid_request&error_description=Invalid+display+parameter 
```

## Получение access_token

Для получения `access_token` необходимо выполнить запрос с вашего сервера на [https://oauth.vk.com/access_token](https://oauth.vk.com/access_token), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения. 
* `client_secret` (**обязательный**) — защищенный ключ вашего приложения (указан в настройках приложения).  
* `redirect_uri` (**обязательный**) — URL, который использовался при получении `code` на первом этапе авторизации. Должен быть аналогичен переданному при авторизации.  
* `code` (**обязательный**) — временный код, полученный после прохождения авторизации. 

Пример запроса:

```
https://oauth.vk.com/access_token?client_id=1&client_secret=H2Pk8htyFD8024mZaPHm&redirect_uri=http://mysite.ru&code=7a6fa4dff77a228eeda56603b8f53806c883f011c40b72630bb50df056f6479e52a
```

В результате выполнения данного запроса ваш сервер получит вновь созданный `access_token`. Вместе с `access_token` серверу возвращается время жизни ключа `expires_in` в секундах. `expires_in` содержит `0`, если токен бессрочный (при использовании `scope` = `offline`). Процедуру авторизации приложения необходимо повторять в случае истечения срока действия `access_token`, смены пользователем своего логина или пароля или удаления приложения из настроек. 

```JSON
{
  "access_token": "533bacf01e11f55b536a565b57531ac114461ae8736d6506a3",
  "expires_in": 43200,
  "user_id": 66748
}
```

Если у пользователя указан email, а приложением были запрошены соответствующие [права](reference/access-rights), сервер также вернет `email` пользователя. 

В случае ошибки будут переданы параметры `error` и `error_description`.

```JSON
{
  "error": "invalid_grant",
  "error_description": "Code is expired."
}
```

Использование API | Ключ доступа | Authorization Code Flow для получения ключа доступа пользователя

# Общие сведения

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

В API ВКонтакте для получения ключа доступа используется открытый [протокол OAuth 2.0](https://oauth.net/2/). При этом пользователь не передает логин и пароль приложению, поэтому его аккаунт не может быть скомпрометирован. 

Мы поддерживаем три способа получения ключа доступа по OAuth 2.0:

1. Implicit flow — самый короткий и простой вариант. Ключ возвращается на устройство пользователя, где был открыт диалог авторизации (в виде дополнительного параметра URL). Такой ключ может быть использован только для запросов непосредственно с устройства пользователя (например, для выполнения вызовов из Javascript на веб-сайте или из мобильного приложения). 

2. Authorization code flow — двухэтапный вариант с дополнительной аутентификацией вашего сервера. Ключ доступа возвращается непосредственно на сервер и может быть использован, например, для автоматизированных запросов из PHP. 

3. Client credentials flow — авторизация по секретному ключу приложения. Этот подход необходимо использовать только для доступа к специальным [secure](method/secure)-методам. 

## Ключ доступа пользователя

Такой ключ требуется для работы со всеми [методами](method) нашего API, за исключением методов секции [`secure`](method/secure). 

**Ключ доступа** — своего рода «подпись» пользователя в вашем приложении. Он сообщает серверу, от имени какого пользователя осуществляются запросы, и какие [права доступа](reference/access-rights) он выдал вашему приложению. 

Получить ключ доступа пользователя можно одним из этих способов:

*  [Implicit flow](api/access-token/implicit-flow-user). Для работы с API от имени пользователя в Javascript-приложениях и Standalone-клиентах (десктопных или мобильных). 
*  [Authorization code flow](api/access-token/authcode-flow-user). Для работы с API от имени пользователя с серверной стороны вашего сайта. 

В iFrame и Flash-приложениях ключ доступа передается при запуске с [остальными параметрами](api/app-run-parameters), вам не нужно самостоятельно реализовывать работу с OAuth. 

## Ключ доступа сообщества

Такой ключ позволяет работать с API от имени группы, встречи или публичной страницы. Например, с его помощью вы можете отвечать подписчикам сообщества на сообщения, поступившие в его адрес. 

С ключом доступа сообщества можно вызывать те методы, которые имеют специальную пометку в общем [списке](reference). 

Получить ключ доступа сообщества можно одним из этих способов:

*  [Implicit flow](api/access-token/implicit-flow-community). Для работы с API от имени сообщества в Javascript-приложениях и Standalone-клиентах (десктопных или мобильных). 
*  [Authorization code flow](api/access-token/authcode-flow-community). Для работы с API от имени сообщества с серверной стороны вашего сайта. 
*  В интерфейсе настроек сообщества. Для этого достаточно открыть раздел **Управление сообществом** (**Управление страницей**, если у вас публичная страница), выбрать вкладку **Работа с API** и нажать **Создать ключ доступа**. 

## Сервисный ключ доступа

Сервисный ключ нужен для запросов, которые не требуют авторизации пользователя или сообщества. Это такие методы, как [`secure.sendNotification`](method/secure.sendNotification) для отправки уведомлений от приложения, или [`secure.addAppEvent`](method/secure.addAppEvent) для добавления информации о достижениях, а также открытые методы, например, [`users.get`](method/users.get). 

Получить сервисный ключ доступа можно в настройках вашего приложения. Ключ не привязан к IP-адресу при использовании с открытыми методами, срок его действия не ограничен. Если ключ был скомпрометирован, вы можете сгенерировать новый ключ, при этом старый будет аннулирован.

Сервисный ключ доступа идентифицирует ваше приложение. Все запросы к API, совершённые с использованием вашего ключа доступа, будут считаться совершёнными от имени вашего приложения. Сервисный ключ доступа можно использовать только для запросов с серверной стороны приложения, его нельзя передавать и хранить на клиенте. 

Для запросов к методам [`secure`](method/secure) сервисный ключ привязан к IP-адресу, с которого был сгенерирован.

Документация о старой схеме получения сервисного ключа доступа доступна на этой странице: [Client credentials flow](api/service-token/client-cred-flow).

## Дополнительно

*  Если вы разрабатываете приложение для iOS, Android или Windows Phone, мы рекомендуем использовать наши [мобильные SDK](sdk/overview) с возможностью авторизации через официальное приложение, установленное на устройстве клиента. 
*  Для встраиваемых iFrame приложений вам не нужно самостоятельно внедрять OAuth для работы с клиента, ключ доступа передается в приложение при запуске (подробнее см. на [этой странице](api/app-run-parameters)). 
*  Для внешних сайтов доступен [виджет авторизации](widgets/auth) — готовое решение для Implicit Flow на веб-сервисе.

Использование API | Ключ доступа | Общие сведения

# Implicit Flow для получения ключа доступа сообщества

Используйте Implicit Flow для вызова методов API ВКонтакте непосредственно с устройства пользователя (например, из Javascript).

## Получение списка администрируемых сообществ

Получить ключ доступа сообщества через OAuth может только его администратор. Чтобы получить ключи доступа сразу для всех или нескольких сообществ пользователя, мы рекомендуем добавить этот дополнительный шаг в процесс авторизации.

Получите ключ доступа пользователя ([для работы с клиента](api/access-token/implicit-flow-user) или [для работы с сервера](api/access-token/authcode-flow-user)) с правами `scope`=`groups` и сделайте запрос к методу [groups.get](groups.get) с параметром `filter`=`admin`, чтобы получить список идентификаторов администрируемых сообществ.

Затем используйте все полученные значения или их часть в качестве параметра `group_ids`.

## Открытие диалога авторизации

Перед открытием диалога авторизации мы рекомендуем убедиться, что пользователь является администратором сообщества, для которого необходимо получить ключ доступа

Необходимо перенаправить браузер пользователя по адресу
[`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения. 
* `redirect_uri` (**обязательный**) — адрес, на который будет переадресован пользователь после прохождения авторизации.
* `group_ids` (**обязательный**) —  идентификаторы сообществ, для которых необходимо получить ключ доступа. Параметр должен представлять собой строку, содержащую значения без знака «минус», разделенные запятой.
* `display` — указывает тип отображения страницы авторизации. Поддерживаются следующие варианты: 
    * `page` — форма авторизации в отдельном окне; 
    * `popup` — всплывающее окно; 
    * `mobile` — авторизация для мобильных устройств (без использования Javascript) 

Если пользователь авторизуется с мобильного устройства, будет использован тип `mobile`.
* `scope` — битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации и запросить отсутствующие. Сейчас доступны: `manage`,`messages`,`photos`,`docs`.
* `response_type` — тип ответа, который необходимо получить. Укажите `token`.
* `v` (обязательный) — [версия API](reference/versions), которую вы используете. Актуальная версия: `:version`.
* `state` — произвольная строка, которая будет возвращена вместе с результатом авторизации.  


Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&group_ids=1,123456&display=page&redirect_uri=http://example.com/callback&scope=messages&response_type=token&v=:version
```

## Разрешение прав доступа

После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра `scope`. Полный список настроек доступен в разделе [прав доступа приложений](reference/access-rights).  

Сейчас для ключей сообщества приложение любого типа может запрашивать права `manage`,`messages`,`photos`,`docs`. Методы, доступные с ключом доступа сообщества, помечены в общем [списке](method) специальным значком.

## Получение access_token

После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу `redirect_uri`, указанному при открытии диалога авторизации. При этом ключ доступа к API `access_token` и другие параметры будут переданы в URL-фрагменте ссылки:

```
http://REDIRECT_URI#access_token_XXXXXX= 533bacf01e11f55b536a565b57531ad114461ae8736d6506a3&expires_in=86400
```

Здесь `XXXXXX` — идентификатор сообщества, для которого был запрошен ключ доступа.

В случае возникновения ошибки авторизации в качестве `GET`-параметров в `redirect_uri` будет передана информация об этой ошибке. 

```
http://REDIRECT_URI#error=access_denied&error_description=The+user+or+authorization+server+denied+the+request.
```

Использование API | Ключ доступа | Implicit Flow для получения ключа доступа сообщества

# Implicit Flow для получения ключа доступа пользователя

> Для приложений на iOS, Android, Windows Phone мы рекомендуем использовать [упрощенную схему авторизации через SDK](sdk/overview). 

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

## Открытие диалога авторизации

Необходимо перенаправить браузер пользователя по адресу
[`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения.
* `redirect_uri` (**обязательный**) — адрес, на который будет переадресован пользователь после прохождения авторизации (см. [`redirect_uri`](#Redirect_uri)).
* `display` — указывает тип отображения страницы авторизации. Поддерживаются следующие варианты:

    * `page` — форма авторизации в отдельном окне;
    * `popup` — всплывающее окно;
    * `mobile` — авторизация для мобильных устройств (без использования Javascript)

    Если пользователь авторизуется с мобильного устройства, будет использован тип `mobile`.
* `scope` — битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации пользователя и запросить отсутствующие.
* `response_type` — тип ответа, который необходимо получить. Укажите `token`.
* `state` — произвольная строка, которая будет возвращена вместе с результатом авторизации.
* `revoke=1` — параметр, указывающий, что необходимо не пропускать этап подтверждения прав, даже если пользователь уже авторизован.

Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&display=page&redirect_uri=http://example.com/callback&scope=friends&response_type=token&v=:version&state=123456
```

### Redirect_uri

**Redirect_uri** — это URL, на который будет переадресован браузер пользователя после разрешения им прав доступа. 

Если вы разрабатываете веб-приложение и хотите работать с API из Javascript, в `redirect_uri` необходимо указать адрес страницы на Вашем сайте. В целях безопасности, этот адрес также должен быть указан в настройках вашего приложения (поля «Адрес сайта», «Базовый домен» и «Доверенный Redirect URI»). 

> **Обратите внимание**, вы не сможете работать с методами, которые помечены как доступные только для Standalone-приложений. Во всех остальных случаях (мобильное, десктопное приложение) необходимо использовать `redirect_uri` по умолчанию: [`https://oauth.vk.com/blank.html`](https://oauth.vk.com/blank.html)

Если пользователь не авторизован ВКонтакте в используемом браузере, то в диалоговом окне ему будет предложено ввести свой логин и пароль.

## Разрешение прав доступа

После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра `scope`. Полный список настроек доступен в разделе [прав доступа приложений](reference/access-rights).  

С ключом пользователя, полученным в Implicit Flow, можно работать с наибольшим количеством прав доступа и соответствующих методов по сравнению с остальными способами авторизации. 

>  **Обратите внимание,** что некоторые права могут быть запрошены только Standalone-приложением (например, право доступа `messages`). Это автоматически означает необходимость использования `redirect_uri` по умолчанию (см. [`redirect_uri`](#Redirect_uri)).


## Получение access_token

После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу `redirect_uri`, указанному при открытии диалога авторизации. При этом ключ доступа к API `access_token` и другие параметры будут переданы в URL-фрагменте ссылки:

```
http://REDIRECT_URI#access_token=533bacf01e11f55b536a565b57531ad114461ae8736d6506a3&expires_in=86400&user_id=8492&state=123456
```

Вместе с ключом `access_token` также будет указано время его жизни `expires_in`, заданное в секундах. `expires_in` содержит `0`, если токен бессрочный (при использовании `scope` = `offline`). Если срок использования ключа истек, то необходимо повторно провести все описанные выше шаги, но в этом случае пользователю уже не придется дважды разрешать доступ. Запрашивать `access_token` также необходимо при смене пользователем логина или пароля или удалением приложения в настройках доступа. 

Кроме того, среди возвращаемых параметров будет указан `user_id` — идентификатор авторизовавшегося пользователя. 

В случае возникновения ошибки авторизации в качестве GET-параметров в `redirect_uri` будет передана информация об этой ошибке. 

```
http://REDIRECT_URI#error=access_denied&error_description=The+user+or+authorization+server+denied+the+request.
```

Использование API | Ключ доступа | Implicit Flow для получения ключа доступа пользователя


# Требования к отображению рекламных записей

## Получение рекламных записей

Для приложений с функциональностью ленты новостей метод [`newsfeed.get`](method/newsfeed.get), кроме обычных записей возвращает рекламные записи — промопосты.

В вызове [`newsfeed.get`](method/newsfeed.get) необходимо дополнить параметр `filters` значением `ads_post`, а также передавать дополнительный параметр `device_info`, содержащий следующие поля:
* `app_version` — версия приложения;
* `app_build` — билд приложения;
* `manufacturer` — производитель, кроме iOS;
* `device_model` — модель устройства;
* `system_name` — название системы (iOS, Android);
* `system_version` — версия системы (6.2, 11.0.2);
* `ads_device_id` — ID устройства,
* `ads_android_id` — Android ID, только для Android;
* `ads_tracking_disabled` — `0`, если отслеживание разрешено пользователем, `1` — запрещено.

Для пагинации ленты новостей необходимо использовать параметры `start_from`/`next_from`.

В работе с рекламными записями в ленте используйте отдельные методы для жалоб и скрытия источника из ленты: `adsint.reportAd`, `adsint.hideAd`.

### Метод adsint.reportAd

`Параметры:`
* `ad_data` (`string`, **required**) — значение поля `ad_data` из рекламного объявления.
* `reason` (`string`) — причина жалобы. Возможные значения:
   * `spam` — спам;
   * `insult` — оскорбление;
   * `porn` — материал для взрослых;
   * `fraud` — мошенничество;
   * `other` — другое.

Ответ:
После успешного выполнения возвращает объект с полем `success`, которое содержит значение `1`.

### Метод adsint.hideAd

Параметры:
* `ad_data` (`string`, **required**) — значение поля `ad_data` из рекламного объявления.
* `object`_type` (`string`) — тип скрываемого объекта. Допустимые значения:
   * `ad` — рекламное объявление;
   * `source` — источник рекламного объявления. Только для промопостов.

Ответ
После успешного выполнения возвращает объект с полем `success`, которое содержит значение `1`.

## Формат данных в API

Объект, описывающий рекламную запись, содержит следующие поля:

### `type`
`string`
Тип записи. Всегда содержит значение `ads`.

### `ads_title`
`string`
Заголовок рекламного блока.

### `ads_id1`
`integer`
ID позиции в новостной ленте, часть 1.

### `ads_id2`
`integer`
ID позиции в новостной ленте, часть 2.

### `ads`
`array`
Массив рекламных объявлений, всегда содержит 1 элемент. Объект, описывающий объявление, содержит следующие поля:
* `type` (`string`) — тип объявления, всегда равен `post`;
* `age_restriction` (`string`) — возрастная метка;
* `ad_data` (`string`) — строка для регистрации событий методом `adsint.registerAdEvents` и для действий в методах `adsint.hideAd` и `adsint.reportAd`. Подробнее в разделе [Регистрация событий](#Регистрация%20событий).
* `ad_data_impression` — строка для регистрации событий методом `adsint.registerAdEvents`. Подробнее в разделе [Регистрация событий](#Регистрация%20событий).
* `post` (`object`) — [объект записи на стене](reference/objects/post). В поле `post_type` содержится значение `post_ads`. Дополнительно объект может содержать поле `track_code` (`string`), необходимое для [регистрации событий](#Регистрация%20событий).
* `statistics` (`array`) — массив ссылок на пиксели для [регистрации событий](#Регистрация%20событий).  Каждый объект в массиве содержит поля:
   * `type` (`string`) — тип события. Возможные значения:
      * `load` — данные об объявлении получены через API;
      * `impression` — объявление показано пользователю;
      * `click_post_owner` — переход по заголовку поста (в группу);
      * `click_post_link` — переход по ссылке в посте (включая хэштег, упоминание, внутренние ссылки ВК и внешние);
   * `url` (`string`) — ссылка на пиксель, возможно с промежуточными редиректами.

> Обратите внимание на особенности работы с рекламными записями в некоторых методах:
* В методах секции [likes](method/likes) рекламные записи задаются типом объекта `post_ads`.
* В методе [wall.getById](method/wall.getById) в поле `type` для рекламных записей возвращается значение `post_ads`. Кроме того, в этот метод всегда нужно передавать параметр `track_code` при его наличии.
* В методе [wall.repost](method/wall.repost) для рекламной записи необходимо указывать префикс `wall_ads`.
* В методах секции [messages](messages) в поле `attachment` рекламной записи соответствует тип `wall_ads`. 


## Оформление рекламной записи

Рекламная запись должна быть показана в ленте на той же позиции, на которой она находится в ответе от метода [newsfeed.get](method/newsfeed.get). Для рекламной записи необходимо использовать стандартное оформление блоков в ленте с добавлением заголовка (поле `ads_title`) и возрастного ограничения (`age_restriction`) в верхней части блока. Например:

![](14e49c892345ecb718bfafa56a6c7087b1625cbb6498db71d0e4cb1e "7041681492505805859")

### Регистрация событий

Необходимо отправлять данные о взаимодействии пользователя с рекламной записью — как из ленты новостей, так и при открытии рекламной записи на отдельном экране. Для этого используются три механизма (в каждом случае необходимо использовать все три).

### Пиксели статистики

В поле `statistics` объекта, описывающего объявление, возвращаются данные пикселей статистики. Каждый объект, описывающий пиксель, содержит название события в поле `type`  (`string`) (например, переход к владельцу рекламной записи или показ рекламной записи) и URL пикселя, который соответствует этому событию, в поле `url` (`string`).

Как только произошло событие с типом `type`, необходимо открыть URL из соответствующего поля `url`. Каждый тип события может встречаться несколько раз с разными ссылками. При наступлении события нужно загружать все пиксели этого типа, при этом каждая ссылка должна загружаться не более одного раза для событий `load` и `impression`. Для проверки на уникальность события необходимо хранить ключ вида `<type>:<ads_id1>:<ads_id2>` не менее суток (или хранить не менее 1000 последних ключей), и перед отправкой события проверять наличие соответствующего ключа в хранилище.

> Внимание!
URL пикселя может содержать цепочку редиректов. Необходимо корректно обрабатывать файлы cookies в соответствии с заголовками HTTP-ответов.

### adsint.registerAdEvents

В момент показа рекламной записи необходимо вызвать метод `adsint.registerAdEvents` с параметром `events` (`array`) в таком формате:

```JSON
[{
    "event_type": "impression",
    "ad_data_impression": "ZDI0MWVl"
  }, {...}]
```

Каждый элемент массива `events` — объект, который содержит два поля:
* `event_type` (`string`) — всегда должен содержать значение `impression`;
* `ad_data_impression` (`string`) — значение одноименного поля из объекта рекламной записи.

> Внимание!
Метод `adsint.registerAdEvents` нужно вызвать не позднее, чем в течение `5` секунд после того, как произошло событие.

### stats.trackEvents

В момент показа или действия рекламной записью необходимо вызвать метод `stats.trackEvents` с параметром `events` (`array`) в таком формате:

```JSON
[{
    "e":"view_post",
    "post_ids":["123_456", ...],
    "track_code":["sdfsdf", ..]
}, {...}]
```

Каждый элемент массива `events` — объект, описывающий событие. Набор полей в нём зависит от типа события.

## Просмотр рекламной записи

Объект, описывающий событие, содержит поля:

### `e`
`string`
Тип события. Всегда содержит значение _view_post_.

### `post_ids`
(`array`)
Данные о просмотренных записях. Каждый элемент массива представляет собой строку вида `<owner_id>_<post_id>`. Здесь `owner_id` — идентификатор владельца записи, `post_id` — идентификатор записи.

### `track_code`
(`array`)
Значение поля `track_code` из объекта записи. Элементы массива `track_code` должны поиндексно соответствовать элементам массива `post_ids`.

### `repost_ids`
(`array`)
Данные об оригиналах просмотренных записей, если они являются репостами (только предыдущий пост в цепочке, репостом которого является рекламная запись). Формат аналогичен полю `post_ids`, элементы массива `repost_ids` должны поиндексно соответствовать элементам массива `post_ids`.

## Действие с рекламной записью

Объект, описывающий событие, содержит поля:

### `e`
`string`
Тип события. Всегда содержит значение `ost_interaction`.

### `post_id`
`string`
Строковый идентификатор записи (`owner_id+_+post_id`).

### `action`
`string`
Действие. Возможные значения:
* `expand` — раскрытие записи по кнопке «Показать больше»;
* `open` — открытие записи на отдельном экране;
* `link_click` — переход по ссылке из текста записи;
* `attached_link_click` — переход по ссылке, прикреплённой к записи;
* `snippet_action` —  переход по ссылке в сниппете;
* `audio_start` — начал проигрывать музыку в записи;
* `video_start` — начал проигрывать видео в записи 
* `open_photo` — открытие фотографии из записи;
* `open_layer` — открытие статьи из записи;
* `open_wiki` — открытие вики-страницы; 
* `open_group` — переход в группу;
* `open_user` — переход к пользователю.

### `ad_data`
`string`
Значение `ad_data` из объекта рекламной записи.

### `track_code`
(`string`)
Значение поля `track_code` из объекта записи.

### `link`
`string`
URL ссылки. передаётся, если `action` — `link_click`, `attached_link_click` или `snippet_action`. Для хэштегов передается сам хэштег в виде `#hashtag`.
Для ссылок передается значение в оригинальном виде: `example.com`, `https://vk.com/samsung;, ...` Для mention-ссылок передаётся ссылка, преобразованная в `https://vk.com/...`.

> **Внимание!** Метод [stats.trackEvents](method/stats.trackEvents) нужно вызвать не позднее, чем в течение `1` минуты после того, как произошло событие.

Интеграция | Реклама | Требования к отображению рекламных записей

# Рекламный API

## Что это такое?

Автоматизируйте работу с таргетированной рекламой ВКонтакте с помощью методов API — создавайте креативы, запускайте объявления и целые рекламные кампании, редактируйте настройки и получайте статистику. 

Возможности рекламного API:

*  создание и редактирование кампаний и объявлений;
*  автоматизированная выгрузка статистики;
*  управление и обновление аудиторий ретаргетинга;
*  добавление клиентов, наблюдателей и администраторов в рекламный кабинет.


## Работа с API

Перед вызовом методов API необходимо получить ключ доступа пользователя с помощью [Implicit Flow](api/access-token/implicit-flow-user) или [Authorization Code Flow](api/access-token/authcode-flow-user). После этого вы сможете выполнять любые запросы к API по [стандартной схеме взаимодействия](api/api-requests).

> **Важно:** перед началом работы с рекламным API ознакомьтесь с ограничениями и рекомендациями.

Выбирайте нужные методы для работы в зависимости от задач — [здесь](method/ads) мы собрали методы, которые пригодятся для работы с рекламой.   

При работе иногда могут возникать ошибки, но не стоит их бояться. Понять, что пошло не так, поможет [список ошибок](reference/errors).

## Готовые инструменты

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

* [Active Traffic](https://www.activetraffic.ru/)  —  массовое создание и настройка объявлений, аналитика и статистика, автоматические тактики.
*  [Aori](https://aori.ru/) — единая платформа для управления рекламой с простым интерфейсом.
* [Atuko](https://atuko.ru) — массовое создание и редактирование рекламных кампаний с помощью Excel-генератора, подключение сторонней аналитики, массовое копирование и перенос кампаний из одного аккаунта в другой, гибкая настройка и выгрузка отчетов.
*  [eLama](https://elama.ru/tools/)  —  калькулятор выгодной ставки за клик, быстрый конструктор креативов, импорт лидов.
*  [ERESH](https://eresh.zemedia.ru/)  —  устраняет рутину при подготовке и управлении кампаниями: помогает с медиапланом, с расчётом бюджета. Сегментирует объявления, управляет ставками, показывает расширенную статистику.
*  [Kairos](https://kairos.zemedia.ru/)  —  управляет кампаниями. Позволяет сделать максимальный выкуп горячей аудитории, достичь заданного охвата или заданного расхода бюджета к дедлайну. Рентабелен для месячных бюджетов от 300 тыс. рублей.
*  [Marylin](https://mymarilyn.ru/)  —  оптимизация рекламных кампаний, управление ставками под заданные KPI, автоматизация рутинных процессов.
*  [Plarin](https://www.plarin.net/)  —  массовое редактирование объявлений. Библиотека шаблонов креативов, их массовое создание. Оптимизация ставок, автоматическая сегментация, графические отчёты.

API ВКонтакте | Реклама | Рекламный API

# Формат запросов

## Синтаксис запроса

Чтобы обратиться к методу API ВКонтакте, нужно выполнить `POST` или `GET` запрос вида:

```
https://api.vk.com/method/METHOD?PARAMS&access_token=TOKEN&v=V
```

Он состоит из нескольких частей:
* `METHOD` (**обязательно**) — название [метода API](method), к которому вы хотите обратиться. 
    > **Обратите внимание:** имя метода чувствительно к регистру.
* `PARAMS` (**не обязательно**) — входные параметры соответствующего метода API, последовательность пар `name=value`, разделенных амперсандом. Список параметров указан на странице с описанием метода.
* `TOKEN` (**обязательно**) — [ключ доступа](api/access-token/getting-started).
* `V` (**обязательно**) — используемая версия API. Использование этого параметра применяет некоторые изменения в формате ответа различных методов. Сейчас [актуальная версия API](reference/versions) — :version. Этот параметр следует передавать со всеми запросами.

Параметры могут передаваться как методом `GET`, так и `POST`. Если вы будете передавать большие данные (больше 2 килобайт), следует использовать `POST` и формат `FormData`.

Например, вызовем метод [`users.get`](method/users.get) для пользователя с идентификатором `210700286`:

```
https://api.vk.com/method/users.get?user_ids=210700286&fields=bdate&access_token=533bacf01e11f55b536a565b57531ac114461ae8736d6506a3&v=:version
```

В ответ на такой запрос вы получите ответ в формате JSON:

```JSON
{
  "response": [
    {
      "id": 210700286,
      "first_name": "Lindsey",
      "last_name": "Stirling",
      "bdate": "21.9.1986"
    }
  ]
}
```

## Общие параметры

Каждый метод API имеет собственный набор входных параметров. Помимо этого, существуют общие параметры, которые могут быть использованы во всех методах:
* `lang` — определяет язык, на котором будут возвращаться различные данные, например, названия стран и городов. Может содержать строковое обозначение языка или его идентификатор (получить идентификатор языка пользователя вы можете методом [`account.getInfo`](method/account.getInfo)). Кириллические имена будут автоматически транслитерированы в латиницу для всех языков, кроме русского, украинского и белорусского.
* `ru` (`0`) — русский,
* `uk` (`1`) — украинский,
* `be` (`2`) — белорусский,
* `en` (`3`) — английский,
* `es` (`4`) — испанский,
* `fi` (`5`) — финский,
* `de` (`6`) — немецкий,
* `it` (`7`) — итальянский.
* `test_mode=1` — тестовый режим, позволяет выполнять запросы из нативного приложения без его включения на всех пользователей.

## Ограничения и рекомендации

### Частотные ограничения

К методам API ВКонтакте (за исключением методов из секций [`secure`](method/secure) и [`ads`](method/ads)) с ключом доступа пользователя можно обращаться не чаще **3** раз в секунду. Для ключа доступа сообщества ограничение составляет **20** запросов в секунду. Если логика вашего приложения подразумевает вызов нескольких методов подряд, имеет смысл обратить внимание на метод [`execute`](method/execute). Он позволяет совершить до **25** обращений к разным методам в рамках одного запроса.

Для сервисного ключа доступа лимиты такие:

| Кол-во пользователей приложения | Частотный лимит (кол-во запросов в секунду) |
| ----------- | ----------- |
| до 10 000 | 5 |
| до 100 000 | 20 |
| до 500 000 | 40 |
| до 1 млн | 50 |
| больше 1 млн | 60 |

Для методов секции [`ads`](method/ads) действуют собственные [ограничения](method/ads#Ограничения%20на%20вызов%20методов%20рекламного%20API).

Максимальное число обращений к методам секции [`secure`](method/secure) зависит от числа пользователей, установивших приложение. Если приложение установило меньше 10 000 человек, то можно совершать 5 запросов в секунду, до 100 000 — 8 запросов, до 1 000 000 — 20 запросов, больше 1 млн. — 35 запросов в секунду.

Если вы превысите частотное ограничение, сервер вернет ошибку с кодом `6: "Too many requests per second."`.

### Количественные ограничения

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

После превышения количественного лимита доступ к конкретному методу может требовать ввода капчи (см. [`captcha_error`](api/captcha-error)), а также может быть временно ограничен (в таком случае сервер не возвращает ответ на вызов конкретного метода, но без проблем обрабатывает любые другие запросы).

## Примеры

### Кроссдоменный запрос с использованием JSONP

Запросы к API ВКонтакте могут быть выполнены из браузера со страниц сторонних сайтов или [IFrame приложений](sdk/overview).

Чтобы осуществлять кроссдоменные запросы к API, вы можете использовать протокол [JSONP](https://ru.wikipedia.org/wiki/JSONP). Для этого необходимо подключать к документу скрипт с адресом запроса в `src`. Запрос должен содержать дополнительный параметр `callback` c именем функции, которая будет вызвана при получении результата.

Например:

```HTML
<html>
   <title>JSONP</title>
   <head></head>
   <body>
      <script type="text/javascript">
         var script = document.createElement('SCRIPT');
         script.src = "https://api.vk.com/method/users.get?user_ids=210700286&fields=bdate&v=:version&callback=callbackFunc";
         document.getElementsByTagName("head")[0].appendChild(script);
         function callbackFunc(result) {
         alert(result.response[0].first_name)
         }
      </script>
   </body>
</html>
```

В нашем примере после загрузки документа вызывается метод [`users.get`](method/users.get), а после получения ответа от сервера управление передается функции `callbackFunc()`, которая выводит содержимое поля `first_name` из ответа во всплывающем окне.

### Запрос из PHP

```PHP
<?php
$user_id = 210700286;
$request_params = array(
    'user_id' => $user_id,
    'fields' => 'bdate',
    'v' => '5.52',
    'access_token' => '533bacf01e11f55b536a565b57531ac114461ae8736d6506a3'
);
$get_params = http_build_query($request_params);
$result = json_decode(file_get_contents('https://api.vk.com/method/users.get?' . $get_params));
echo ($result->response[0]
    ->bdate);
?>
```

В нашем примере скрипт выводит дату рождения пользователя (`bdate`), полученную обращением к методу [`users.get`](method/users.get).

### Запрос с использованием Open API

[Open API](api/open-api/getting-started) — JS-библиотека для упрощения работы с API ВКонтакте на внешних сайтах.

```HTML
<script type="text/javascript">
   VK.Api.call('users.get', { user_ids: 210700286, fields: 'bdate' }, function(r) {
   if(r.response) {
   alert(r.response[0].bdate);
   }
   });
</script>
```

Использование API | Формат запросов

# Параметры запуска приложения

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

Параметры передаются в строке запроса для iFrame-приложений и с помощью `flashVars` для flash-приложений.

## Список параметров

### `api_url`
`string`

URL сервиса API, по которому необходимо осуществлять запросы.
### `api_id`
`integer`

Идентификатор запущенного приложения.
### `api_settings`

Битовая маска настроек [прав доступа](reference/access-rights) текущего пользователя в приложении.

### `viewer_id`
`integer`

Идентификатор пользователя, который запустил приложение.
### `viewer_type`

Тип пользователя, который просматривает приложение

### `access_token`

Ключ доступа для вызова [методов API](method).

### `user_id`
`integer`

Идентификатор пользователя, со страницы которого было запущено приложение. Если приложение запущено не со страницы пользователя, содержит `0`.

### `platform`
`string`

Идентификатор платформы, на которой запускается приложение. Содержит одно из значений:
  * `html5_ios` – мобильное приложение ВКонтакте для iOS;
  * `html5_android` – мобильное приложение ВКонтакте для Android;
  * `html5_mobile` – мобильная версия сайта ВКонтакте;
  * `web` – десктопная версия сайта ВКонтакте. 

### `is_app_user`
`integer`, [`0`, `1`]

Если пользователь установил приложение, содержит `1`, иначе — `0`.

### `sign`
`string`

[Подпись параметров запуска](#sign) (пришла на замену `auth_key` как усиленная альтернатива).

### `sign_keys`
`string`

Параметры, необходимые для генерации `sign`.

### `timestamp`
`integer`

Время генерации `sign`.

### `auth_key`
`string`

Ключ, необходимый для авторизации пользователя на стороннем сервере.

### `language`
`integer`

Идентификатор языка пользователя, просматривающего приложение.

### `parent_language`
`integer`

Идентификатор языка, которым можно заменить язык пользователя (возвращается для неофициальных языковых версий).

### `is_secure`
`integer`, [`0`, `1`]

Если пользователем используется защищенное соединение – `1`, иначе — `0`.

### `api_result`
`string`

Результат первого запроса к API, который выполняется при загрузке приложения.

### `referrer`
`string`

Обозначение места, откуда пользователь перешёл в приложение.

### `hash`
`string`

Хеш запроса (данные после символа `#` в строке адреса).

### `lc_name`, `ads_app_id`

Служебные параметры.

### `is_play_machine`
`integer`, [`0`, `1`]

Если приложение было запущено через Play Machine.

### `viewer_type`
Если приложение запущено со страницы сообщества (`group_id != 0`), параметр `viewer_type` может принимать следующие значения:

* `4` — если пользователь является создателем или администратором сообщества;
* `3` — если пользователь является редактором сообщества;
* `2` — если пользователь является модератором сообщества;
* `1` — если пользователь является участником сообщества;
* `0` — если пользователь не состоит в сообществе.

Если приложение запущено со страницы пользователя (`user_id != 0`), параметр `viewer_type` может принимать следующие значения:

* `2` — если пользователь является владельцем страницы;
* `1` — если пользователь является другом владельца страницы;
* `0` — если пользователь не состоит в друзьях владельца страницы.

### sign
Чтобы получить подпись параметров запуска (`sign`), отфильтруйте вернувшиеся параметры по параметрам, перечисленных в `sign_keys`, затем объедините пары "ключ=значение" с амперсандом в качестве разделителя. От полученной после объединения строки вычисляется хеш-код алгоритмом `SHA256` в бинарном представлении с методом `HMAС`, подписанный защищенным ключом из настроек вашего приложения, и затем кодируется `base64 encode`.

`sign` позволяет защититься от подмены любого из параметров, переданных в приложение, в то время как `auth_key` защищает от подмены только `api_id` и `viewer_id`.

[Пример проверки подписи на PHP](#PHP)
[Пример проверки подписи на Node.js](#Node.js)

## Про auth_key
`auth_key` нужен для проверки подлинности сессии на сервере: чтобы вы могли быть уверены, что данные запроса не подменялись на стороне клиента.
> Мы не рекомендуем использовать параметр `auth_key`, так как в будущем он будет упразднён. Для проверки подлинности сессии используйте параметр `sign`.

`auth_key` вычисляется на сервере ВКонтакте следующим образом:
```
auth_key = md5(api_id + '_' + viewer_id + '_' + api_secret)
```
Здесь `api_id` — идентификатор вашего приложения, `viewer_id` — идентификатор пользователя, `api_secret` — защищённый ключ (вы можете узнать его в разделе редактировании приложения на вкладке **Редактирование** → **Настройки**, поле **Защищённый ключ**).
Чтобы не производить дополнительную авторизацию пользователя на своём сервере, всегда проверяйте ключ `auth_key` на правильность.

### language
Параметр `language` может принимать следующие значения:

* `0` — русский язык;
* `1` — украинский язык;
* `2` — белорусский язык;
* `3` — английский язык.

## api_result
`api_result` – результат выполнения API-запроса, формирующийся при просмотре приложения. Параметры этого запроса можно ввести в разделе редактирования приложения. Например, для получения информации об указанных пользователях, можно использовать следующий запрос:

```
method=users.get&user_ids={user_id},{viewer_id},1,6492&format=json&v=5.27
```

В данном запросе параметры `{user_id}` и `{viewer_id}` являются переменными. `{user_id}` содержит `id` пользователя, со страницы которого было запущено приложение. `{viewer_id}` – это id пользователя, который просматривает приложение. Также может быть использован параметр `{group_id}`, содержащий id группы, со страницы которой было запущено приложение.

## referrer

Параметр `referrer` может принимать следующие значения:
* `unknown` — источник перехода неизвестен;
* `menu` — переход из левого меню;
* `notification` — уведомление;
* `recommendation` — приложение запущено из блока рекомендаций;
* `friends_feed` — раздел активности друзей в каталоге;
* `catalog_popular` — список популярных приложений в каталоге;
* `catalog_new` — список новых приложений в каталоге;
* `catalog_ads` — рекламный блок в каталоге;
* `quick_search` — результаты быстрого поиска;
* `user_apps` — список собственных приложений пользователя;
* `group` — список приложений в сообществе;
* `featured` — центральный блок баннеров в каталоге;
* `request` — запрос. В этом случае дополнительно вернутся параметры `request_key` и `request_id`;
* `profile_status` — статус профиля;
* `app_suggestions` — специализированный рекламный блок в разделе «Приложения»;
* `join_request` — название приложения в приглашении друга (со страницы https://vk.com/apps);
* `top_grossing` — подборка «Кассовые приложения» в каталоге;
* `friends_apps` — подборка «Приложения друзей» в каталоге;
* `collections` — тематические подборки в каталоге;
* `genre` — подборки по жанрам в каталоге;
* `notifications_page` — список оповещений на странице https://vk.com/apps;
* `myapps_page` — список «Мои приложения» (https://vk.com/apps?act=apps).
* `bestsellers` — подборка «Популярные» в каталоге;
* `ad_{AD_ID}` – если приложение было открыто в результате перехода по рекламному объявлению. `{AD_ID}` содержит идентификатор рекламного объявления;
* `super_app` — приложение запущено из вкладки «Сервисы»;
* `home_screen` — приложение запущено с домашнего экрана телефона;
* `apps_games_invite_notify` — приложение запущено из уведомления.

## Примеры проверки подписи

### PHP
```PHP
<?php
$client_secret = 'xxxxx';

$url = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? "https" : "http") . "://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]";

$query_params = [];
$parsed = parse_url($url, PHP_URL_QUERY);
parse_str($parsed, $query_params); // Получаем query-параметры из URL
$sign_params = [];
$sign_keys = explode(',', $query_params['sign_keys']);
foreach ($sign_keys as $key)
{
    $sign_params[$key] = $query_params[$key];
}

$sign_params_query = http_build_query($sign_params); // Формируем строку вида "param_name1=value&param_name2=value"
$sign = rtrim(strtr(base64_encode(hash_hmac('sha256', $sign_params_query, $client_secret, true)) , '+/', '-_') , '='); // Получаем хеш-код от строки, используя защищеный ключ приложения. Генерация на основе метода HMAC.
$auth_key = md5($sign_params['api_id'] . '_' . $sign_params['viewer_id'] . '_' . $client_secret);

$sign_status = $sign === $query_params['sign']; // Сравниваем полученную подпись со значением параметра 'sign'
echo 'status: ' . ($sign_status ? 'ok' : 'fail') . "\n";
echo date('Y-m-d H:i:s', $query_params['timestamp']) . PHP_EOL;
```
### Node.js
```javascript
const qs = require('querystring');
const crypto = require('crypto');

const urlParams = qs.parse(URL_PARAMS);
const signKeys = new URLSearchParams(URL_PARAMS)
    .get('sign_keys')
    .split(',');

const ordered = {};

signKeys.forEach(key => ordered[key] = urlParams[key]);

const stringParams = qs.stringify(ordered);
const paramsHash = crypto
    .createHmac('sha256', secretKey)
    .update(stringParams)
    .digest()
    .toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=$/, '');

console.log(paramsHash === urlParams.sign);
```

Использование API | Параметры запуска приложения

# Bots Long Poll API

**Bots Long Poll API** позволяет работать с событиями из вашего сообщества в режиме реального времени. В отличие от [Callback API](api/callback/getting-started), очередь из событий хранится на стороне ВКонтакте — мы не будем присылать отдельное уведомление для каждого события. В противоположность [User Long Poll](api/user-long-poll/getting-started), Bots Long Poll API работает с событиями сообщества, а не пользователя.

Чтобы использовать Bots Long Poll API, откройте раздел **Управление сообществом**, на вкладке **Работа с API** → **Long Poll API** выберите **Включён**.

## Подключение

Перед подключением к Long Poll серверу необходимо получить данные сессии (`server`, `key`, `ts`) методом [`groups.getLongPollServer`](method/groups.getLongPollServer).

Затем составьте запрос такого вида:

```
{$server}?act=a_check&key={$key}&ts={$ts}&wait=25
```

В нём используются следующие параметры:
*  `key` — секретный ключ сессии;
*  `server` — адрес сервера;
*  `ts` — номер последнего события, начиная с которого нужно получать данные;
*  `wait` — время ожидания (так как некоторые прокси-серверы обрывают соединение после 30 секунд, мы рекомендуем указывать `wait`=`25`). Максимальное значение — `90`.

Для первого запроса в рамках сессии значения для параметров `server`, `key` и `ts` необходимо получить методом [`groups.getLongPollServer`](method/groups.getLongPollServer). В последующих запросах используйте те же `server` и `key` и новое значение `ts`, которое придет вам в ответе от Long Poll сервера.

В разделе **Управление сообществом** → **Работа с API** → **Bots Long Poll API** → **Типы событий** отметьте те события, которые вы хотите отслеживать. Полный список событий вы найдёте [на этой странице](api/community-events/json-schema).

### Настройка через API

Вы можете управлять настройками Bots Long Poll API в вашем сообществе не только в веб-интерфейсе, но и с помощью методов API:
* [`groups.getLongPollServer`](method/groups.getLongPollServer) — получает адрес для подключения к Long Poll серверу ВКонтакте;
* [`groups.getLongPollSettings`](method/groups.getLongPollSettings) — получает настройки событий Bots Long Poll API;
* [`groups.setLongPollSettings`](method/groups.setLongPollSettings) — устанавливает настройки событий Bots Long Poll API.

## Формат данных

Когда произойдет новое событие или истечет время ожидания, сервер вернет Вам ответ в формате JSON:

```JSON
{
  "ts": "4",
  "updates": [
    {
      "type": "wall_post_new",
      "event_id": "c68dfb983247fea8ac98ea0ea59717df71d8064f",
      "v": ":version",
      "object": {
        "id": 28,
        "from_id": -123456,
        "owner_id": -123456,
        "date": 1519631591,
        "marked_as_ads": 0,
        "post_type": "post",
        "text": "Post text",
        "can_edit": 1,
        "created_by": 564321,
        "can_delete": 1,
        "comments": {
          "count": 0
        }
      },
      "group_id": 123456
    }
  ]
}
```

JSON-объект в ответе содержит два поля:
* `ts` (`string`) — номер последнего события. Используйте его в следующем запросе.
* `updates` (`array`) — массив, элементы которого содержат представление новых событий. 

После получения любого ответа для продолжения связи нужно отправить запрос с новым `ts`, полученным в последнем ответе.   

### Типы событий

Событие в массиве `updates` представляет собой JSON, имеющий следующую структуру:

```JSON
{
  "type": <тип события>,
  "event_id": <идентификатор события>,
  "v": <версия API, для которой сформировано событие>,
  "object": <объект, инициировавший событие>,
  "group_id": <ID сообщества, в котором произошло событие>
}
```

Например:

```JSON
{
  "type": "group_join",
  "event_id": "c68dfb983247fea8ac98ea0ea59717df71d8064f",
  "v": ":version",
  "object": {
    "user_id": 1,
    "join_type": "approved"
  },
  "group_id": 1
}
```

Структура событий в Bots Long Poll API идентична событиям в Callback API. Полный список событий вы найдёте [на этой странице](api/community-events/json-schema).

### Ошибки

В ответ на запрос сервер может вернуть одну из ошибок:

```JSON
{
  "failed": 1,
  "ts": 30
}
```
```JSON
{
  "failed": 2
}
```
```JSON
{
  "failed": 3
}
```

* `"failed":1` — история событий устарела или была частично утеряна, приложение может получать события далее, используя новое значение `ts` из ответа.
* `"failed":2` — истекло время действия ключа, нужно заново получить `key` методом [`groups.getLongPollServer`](method/groups.getLongPollServer).
* `"failed":3` — информация утрачена, нужно запросить новые `key` и `ts` методом [`groups.getLongPollServer`](method/groups.getLongPollServer).

Обратите внимание: объекты в сообщении об ошибке могут содержать поля, не описанные  в документации. Их необходимо игнорировать и не обрабатывать. 

## Поддержка в SDK

Вы можете работать с Bots Long Poll API средствами наших SDK:
* [Java SDK](sdk/java),
* [PHP SDK](sdk/php),
* [Node.js SDK](https://github.com/Naltox/node-vk-sdk) (неофициальный).

Интеграция | Сообщества и пользователи | Bots Long Poll API

# Клавиатура

## Подключение

Чтобы включить клавиатуры в сообществе, перейдите в **Управление сообществом** → **Сообщения** → **Настройки для бота** и включите **Возможности ботов**. Там же можно добавить кнопку **Начать**. 

## Кнопка «Начать»

Если она включена, и у пользователя еще нет переписки с сообществом, мы показываем кнопку «Начать», которая отправляет команду `start`. [Payload](#Отправка%20клавиатуры) этого сообщения будет выглядеть так: 

```
{"command":"start"}
```

## Внешний вид

Клавиатура представляет собой массив массивов, то есть таблицу, у которой ячейки — это кнопки. У всех кнопок в рамках одной строки одинаковый размер, и они заполняют 100% ширины. Высота всех кнопок — константа. Текст отображается по центру кнопки и обрезается, если не помещается полностью при текущем размере экрана. 

### Стандартное отображение

По умолчанию, если не передан параметр `inline`, клавиатура показывается под полем ввода в диалоге с пользователем. Максимальный размер стандартной клавиатуры — 5 × 10. Максимальное количество клавиш: 40. 

![](23da71d33405de08fec50d8805eb69fbf7024196a16dad3d328de21b "616200134238115590")

### Inline-отображение

Клавиатура может отображаться внутри сообщения — это inline-отображение. Чтобы включить его, передайте параметр inline в объект клавиатуры. Её максимальный размер составит 5 × 6. Максимальное количество клавиш: 10. 

![](ea51b7f45bf0a0d0c1d393d5990e6e51728c00ddb5ab984134578f1a "6537326869192998723")

## Структура данных

### `one_time`
`bool`
Скрывать ли клавиатуру после первого использования. Параметр срабатывает только для кнопок, отправляющих сообщение (поле `type` - `text, location`) Для `type` равных `open_app`, `vk_pay` параметр игнорируется. 
Возможные значения:
* `true` — клавиатура будет скрыта при нажатии на кнопку с типом `text` или `location`;
* `false` — клавиатура не скрывается; 

### `buttons`

`array`
Массив массивов с кнопками. 

### `inline`

`bool`
Должна ли клавиатура отображаться внутри сообщения. Возможные значения:
*  `true` — клавиатура отображается внутри сообщения. Параметр `one_time` при этом не поддерживается;
*  `false` — стандартное отображение клавиатуры.

### `action`

`object`
Объект, описывающий тип действия и его параметры. Поля объекта зависят от значения параметра `type` и описаны в таблице ниже.

### `color`

`string`
Цвет кнопки. Параметр используется только для кнопок с `type`: `text` и `callback`. Возможные значения:
*  `primary` — синяя кнопка, обозначает основное действие. `#5181B8` 
*  `secondary` — обычная белая кнопка. `#FFFFFF` 
*  `negative` — опасное действие, или отрицательное действие (отклонить, удалить и тд). `#E64646` 
*  `positive` — согласиться, подтвердить. `#4BB34B`

Поля объекта `action` в зависимости от типа кнопки.

### `Text`

Текстовая кнопка. Отправляет сообщение c текстом, указанным в `label`. Поля текстовой кнопки:
* `type` (`string`) — для текстовой кнопки имеет значение `text`;
* `label` (`string`) — текст кнопки. Будет отправлен пользователем в диалог с сообществом/беседу при нажатии;
*  `payload` (`string`) — дополнительная информация. Вернется в [событии](api/community-events/json-schema) `message_new` в одноименном поле. Максимум 255 символов.

### `Open Link`

Открывает указанную ссылку. Поля:
* `type` (`string`) — для кнопки открытия ссылки имеет значение `open_link`;
* `link` (`url`) — ссылка, которую необходимо открыть по нажатию на кнопку;
* `label` (`string`) — текст кнопки;
*  `payload` (`string`) — дополнительная информация. В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.

### `Location`

 По нажатию отправляет местоположение в диалог с ботом/беседу. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:
* `type` (`string`) — для кнопки местоположения имеет значение `location`;
* `payload` (`string`) — дополнительная информация. Вернется в [событии](api/community-events/json-schema) `message_new` в одноименном поле. Максимум 255 символов.


### `VK Pay`

Открывает окно оплаты VK Pay с предопределёнными параметрами. Кнопка называется «Оплатить через VK pay», VK pay отображается как логотип. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:
* `type` (`string`) — для кнопки вызова платежного окна имеет значение `vkpay`;
* `payload` (`string`) — дополнительная информация.  В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.
*  `hash` (`string`) — строка, содержащая [параметры платежа VK Pay](pay/getting-started) и идентификатор приложения в параметре `aid` , разделенные `&`. Пример: `action=transfer-to-group&group_id=1&aid=10`.

### `VK Apps`

Открывает указанное приложение VK Apps. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:
* `type` (`string`) — для кнопки открытия сервиса имеет значение `open_app`;
* `app_id` (`int`) — идентификатор вызываемого приложения с типом VK Apps.  
* `owner_id` (`int`) — идентификатор сообщества, в котором установлено приложение, если требуется открыть в контексте сообщества;
* `payload` (`string`) — дополнительная информация.  В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.
* `label` (`string`) — название приложения, указанное на  кнопке. 
* `hash` (`string`) — хеш для навигации в приложении, будет передан в строке параметров запуска после символа `#`.

### `Callback`

Позволяет без отправки сообщения от пользователя получить уведомление о нажатии на кнопку и выполнить необходимое действие.  Поля:
* `type` (`string`) — для callback-кнопки имеет значение `callback`;
* `label` (`string`) — текст кнопки. 
*  `payload` (`string`) —  дополнительная информация. В кнопках, не отправляющих текст, передаётся для совместимости со старыми клиентами. Максимум 255 символов. Подробнее читайте в разделе [Callback-кнопки](api/bots/development/keyboard#Callback-кнопки).

### Пример клавиатуры в JSON

```JSON
{  
   "one_time":false,
   "buttons":[  
      [  
         {  
            "action":{  
               "type":"location",
               "payload":"{\"button\": \"1\"}"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"open_app",
               "app_id":6232540,
               "owner_id":-157525928,
               "hash":"123",
               "label":"LiveWidget"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"vkpay",
               "hash":"action=transfer-to-group&group_id=181108510&aid=10"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"1\"}",
               "label":"Red"
            },
            "color":"negative"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"Green"
            },
            "color":"positive"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"Blue"
            },
            "color":"primary"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"White"
            },
            "color":"secondary"
         }
      ]
   ]
}
```

## Отправка клавиатуры

JSON-объект клавиатуры передается строкой в параметре `keyboard` в методе [`messages.send`](method/messages.send) с последней версией API. 

Как только пользователь нажимает на одну из кнопок клавиатуры, отправляется сообщение с текстом из поля `label`. Если задан параметр `payload`, он дополнительно придет в callback API. 

> **Важное замечание**: чтобы получать параметр `payload`, нужно поднять версию callback API до 5.69 или выше. Параметр `payload` нужно передавать в формате JSON.

## Пример события в Callback API

```JSON
{
    "type": "message_new",
    "object": {
        "id": 41,
        "date": 1526898082,
        "out": 0,
        "user_id": 163176673,
        "read_state": 0,
        "title": "",
        "body": "Blue",
        "payload": "{\"button\":\"4\"}"
    },
    "group_id": 1
}
```

Также, если клавиатура была определена с флагом `one_time`, она сразу же скрывается. Если нет, остается как была и пользователь может отправить еще сколько угодно команд.
Чтобы убрать у пользователя клавиатуру, необходимо отправить сообщение с пустым параметром `buttons`:

```JSON
{"buttons":[],"one_time":true}
```

## Callback-кнопки

Callback-кнопки — тип кнопок, который работает в стандартном и в inline-отображении клавиатур ботов.

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

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

* Реализация основного меню бота: после нажатия на callback-кнопку на клавиатуре бот обновляет её, выполняя переход на уровень глубже по вложенности меню. При этом пользователю не нужно отправлять боту дополнительное сообщение.
* Редактирование сообщения: пользователь нажимает на callback-кнопку в inline-клавиатуре из сообщения, выбирая категорию блюда в меню, — бот редактирует сообщение, предлагая блюда из этой категории. Пользователь при этом не отправляет боту сообщение.
* Отправка результата действия: пользователь нажимает на callback-кнопку, например «Пополнить баланс», которая совершает определённое действие. После его успешного выполнения бот показывает пользователю информацию «Баланс пополнен» при помощи snackbar. Отправка сообщения при этом не требуется.

### Принцип работы

```JSON
{
  action: {
    type: "callback",
    payload: "{}", // максимум 255 символов
    label: "Нажми меня"
  }
}
```
* пользователь нажимает на клавишу;
* бот получает новое событие `message_event` в Callback или LongPoll API:
```JSON
{
  "conversation_message_id": 1234,
  "user_id": 612512941,   // id пользователя, который нажал на кнопку
  "peer_id": 2000000094, // id диалога со стороны бота
  "event_id": "feleyinek", // Случайная строка. Активна в течение минуты, спустя минуту становится недействительной
  "payload": "{}"
}
```
* бот формирует запрос к API, используя метод [`messages.sendMessageEventAnswer`](method/messages.sendMessageEventAnswer);
* клиент пользователя получает ответ от бота и выполняет нужное действие.

### Действие после нажатия на кнопку

Бот отправляет `event_data` — объект действия, которое должно произойти после нажатия на кнопку.
```JSON
{
    "type": "show_snackbar",
    "text": "Покажи исчезающее сообщение на экране"
  }
```
Метод [`messages.sendMessageEventAnswer`](method/messages.sendMessageEventAnswer) можно выполнить только один раз за нажатие на клавишу.  

### Типы действий

1. `show_snackbar` — показать исчезающее сообщение.
    Содержит поле `text` — текст, который нужно вывести (максимум 90 символов). Snackbar показывается в течение 10 секунд и автоматически скрывается, при этом у пользователя есть возможность смахнуть его с экрана.
    ![](de951d983e604c2aabe128a8e5e1ccb37de792b2b582d9ca221db1dc "-3563741600283602501")
2. `open_link` — открыть ссылку. Осуществляется переход по указанному адресу.
    ```JSON
    {
      type: "open_link",
      link: url
    }
    ```
3. `open_app` — открыть VK Mini App. Происходит переход в мини-приложение.
    ```JSON
    {
      type: "open_app",
      app_id: int,
      owner_id: int | null,
      hash: string
    }
    ```
### Внешний вид

Callback-кнопки выглядят так же, как и обычные кнопки, и поддерживают все стили. После нажатия на кнопку на время выполнения действия возникает индикатор загрузки.
![](2ded1e4a35c7dae08f9d64009478dee14f2498cd1876683b67a36bcf "-532726193596602097")

### Обработка ошибок

Если в формате объекта клавиатуры есть ошибки, [`messages.send`](method/messages.send) вернёт ошибку `911. Keyboard format is invalid`.

Интеграция | Чат-боты | Разработка | Клавиатура

Интеграция | Чат-боты | Разработка | Сообщения

# Быстрый старт

**Чат-бот** — это скрипт на вашем сервере, который получает уведомления о новых событиях из ВКонтакте и обрабатывает их. Например, определяет текстовую команду в сообщении от пользователя и присылает в ответ какое-нибудь изображение.

Для создания бота вам потребуются:
*  Сообщество, от имени которого ваш бот будет общаться с пользователями ВКонтакте.
*  Сервер, который будет принимать уведомления о событиях.
*  Логика самого бота — скрипт, который определяет, как бот реагирует на то или иное событие.

В первую очередь вам нужно продумать функциональность чат-бота. Составьте список возможных текстовых команд или событий, на которые бот должен реагировать, и соответствующие им ответные действия бота. Стоит помнить, что люди могут ошибаться, набирая команды, и присылать боту текст, который отличается от всех учтённых вами вариантов — важно предусмотреть действие по умолчанию (можно в таком случае присылать пользователю список всех поддерживаемых команд).

> Если ранее вы не работали с API ВКонтакте, перед началом работы мы рекомендуем вам прочитать [это руководство](api/getting-started).


## Примеры реализации

### PHP

[VK PHP Бот](https://vk.com/botexample), созданный нашим разработчиком на PHP. Для обработки событий используется Callback API, голосовые сообщения генерируются с помощью API [Яндекс SpeechKit](https://tech.yandex.ru/speechkit/). [Код проекта на GitHub](https://github.com/VKCOM/bot-example-php). 

### Java

Бот для работы с Youtrack, созданный нашими разработчиками на Java ([Java SDK](sdk/java)). Для обработки событий используется Callback API. [Код проекта на GitHub](https://github.com/VKCOM/vk-java-sdk/wiki/YouTrack-bot). 

### JS

Библиотека для работы с ботами на Node JS, автор [Михаил Семин](https://vk.com/bifot). Используется Long Poll, предусмотрена возможность быстро и удобно добавлять новые команды и реакции. [Код проекта на GitHub](https://github.com/bifot/node-vk-bot-api). 

## Сообщество

Для подключения чат-бота вы можете использовать любое своё сообщество ВКонтакте — группу, встречу или публичную страницу. Ваш бот должен соответствовать правилам, подробнее о них вы можете узнать [здесь](bots-rules).

Первым делом нужно указать, что в вашем сообществе будет работать бот. Для этого перейдите в **Управление сообществом** → **Сообщения** → **Настройки для бота** и включите пункт **Возможности ботов**.

Сообщество — это точка входа для пользователей, которые будут общаться с вашим ботом. Стоит позаботиться о том, чтобы оно выглядело привлекательно и содержало описание вашего бота, иначе его действия могут стать сюрпризом для пользователей. Не забудьте включить сообщения в вашем сообществе (**Управление сообществом** → **Сообщения**), когда бот будет готов к использованию, чтобы ему можно было написать. 

Итак, если вы выбрали сообщество, можно приступать к настройке уведомлений.

### Получение ключа доступа

Ключ доступа потребуется вам для получения обновлений (в Long Poll), а также для работы с API. 

Откройте раздел **Управление сообществом** (**Управление страницей**, если у вас публичная страница), выберите вкладку **Работа с API** и нажмите  **Создать ключ доступа**.

Отметьте необходимые права доступа и подтвердите свой выбор. 

![](94dbda6f9957847362a13776b0676208b2cedee8d63b617201bc5742 "-8033473622113514247")

Вы можете создать несколько ключей с разными правами доступа. Ключи нельзя размещать публично — узнав его, третье лицо может обращаться к API ВКонтакте от имени вашего сообщества. Если ключ был скомпрометирован, необходимо удалить его из списка — после этого он станет недействителен.

Также вы можете получить ключ доступа с помощью OAuth. Используйте схему авторизации [Authorization Code Flow](api/access-token/authcode-flow-user).

### Добавление ботов в беседы

Чтобы пользователи смогли добавлять бота в беседы, необходимо включить эту возможность в настройках. Перейдите в **Управление сообществом** →**Сообщения** →**Настройки для бота** и поставьте галочку в пункте **Разрешать добавлять сообщество в беседы**. После этого в  сообществе появится кнопка **Пригласить в беседу**, открывающая модальное окно со списком бесед.

Сейчас у бота в беседе есть три уровня доступа:

#### Только упоминания

Этот уровень доступа выдается сразу после добавления в беседу. Бот может:
*  видеть все сообщения, которые его касаются. Это упоминания бота и ответы на его сообщения
*  отправлять сообщения в беседу

#### Доступ ко всей переписке

Выдать его может любой администратор беседы. Бот может:
*  видеть все сообщения в беседе 
*  отправлять сообщения в беседу

#### Администратор

Выдать его может только создатель беседы. Бот может:
*  видеть все сообщения в беседе 
*  отправлять сообщения в беседу
*  Получать [объект беседы](reference/objects/conversation)
*  Получать участников беседы

>  **Важно!** Для получения событий из беседы версия API у callback-сервера должна быть не ниже 5.80.

## Получение событий и обновлений

Чтобы реагировать на какие-либо события, ваш скрипт должен о них узнать. Для этого существуют два подхода — Callback API и Long Poll.

### Callback API

Callback API присылает уведомления на ваш сервер, как только в сообществе происходит нужное событие. Событие может быть каким угодно: комментарий к фотографии, новая запись на стене, вступление в сообщество, отправка сообщения, и многое другое. Посмотреть полный список доступных событий, а также прочитать подробнее о настройке вы можете [в документации Callback API](api/callback/getting-started).

Для подключения Callback API в сообществе нужно указать адрес скрипта на вашем сервере и выбрать события, которые Вы хотите получать. Например, если ваш бот должен распознавать текстовые команды, отметьте событие **Входящее сообщение**.

Уведомления от Callback API выглядят как JSON с основной информацией о событии:
```JSON
{  
   "type":"message_new",
   "object":{  
      "id":694,
      "date":1499441696,
      "out":0,
      "user_id":123456,
      "read_state":0,
      "title":" ... ",
      "body":"start"
   },
   "group_id":1,
   "secret":"sjr948dff3kjnfd3"
}
```
В этом примере пользователь с `id` = `123456` отправил сообществу сообщение с текстом `start`. 

Для каждого события Callback API отправляет отдельный запрос на ваш сервер. Ваш скрипт должен подтверждать получение каждого запроса, отправляя в ответ строку `ok`.

### Пример на PHP
```PHP
<?
define('CALLBACK_API_CONFIRMATION_TOKEN', '213fefef3');  // Строка, которую должен вернуть сервер
define('VK_API_ACCESS_TOKEN', '016cb552 ... 989fb8345');   // Ключ доступа сообщества

define('CALLBACK_API_EVENT_CONFIRMATION', 'confirmation'); // Тип события о подтверждении сервера
define('CALLBACK_API_EVENT_MESSAGE_NEW', 'message_new'); // Тип события о новом сообщении
define('VK_API_ENDPOINT', '[https://api.vk.com/method/]');   // Адрес обращения к API
define('VK_API_VERSION', '5.89'); // Используемая версия API

$event = json_decode(file_get_contents('php://input'), true);

switch ($event['type']) {
  // Подтверждение сервера
  case CALLBACK_API_EVENT_CONFIRMATION:
    echo(CALLBACK_API_CONFIRMATION_TOKEN);
    break;
  // Получение нового сообщения
  case CALLBACK_API_EVENT_MESSAGE_NEW:
    $message = $event['object'];
    $peer_id = $message['peer_id'] ?: $message['user_id'];
    send_message($peer_id, "Hello world! (peer_id: {$peer_id})");
    echo('ok');
    break;
  default:
    echo('Unsupported event');
    break;
}

function send_message($peer_id, $message) {
  api('messages.send', array(
    'peer_id' => $peer_id,
    'message' => $message,
  ));
}

function api($method, $params) {
  $params['access_token'] = VK_API_ACCESS_TOKEN;
  $params['v']            = VK_API_VERSION;
  $query                  = http_build_query($params);
  $url                    = VK_API_ENDPOINT . $method . '?' . $query;
  $curl                   = curl_init($url);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
  $json  = curl_exec($curl);
  $error = curl_error($curl);
  if ($error) {
    error_log($error);
    throw new Exception("Failed {$method} request");
  }
  curl_close($curl);
  $response = json_decode($json, true);
  if (!$response || !isset($response['response'])) {
    error_log($json);
    throw new Exception("Invalid response for {$method} request");
  }
  return $response['response'];
}
```
[Скрипт полностью на GitHub](https://github.com/VKCOM/bot-example-php)

### Bots Long Poll API

Второй способ получения обновлений — это подключение к Bots Long Poll API. Прочитать подробнее о работе с Bots Long Poll API вы можете [на этой странице](api/bots-long-poll/getting-started).

Когда произойдет новое событие или истечет время ожидания, сервер вернет вам ответ в формате JSON:

```JSON
{
  "ts": "4",
  "updates": [
    {
      "type": "wall_post_new",
      "object": {
        "id": 28,
        "from_id": -123456,
        "owner_id": -123456,
        "date": 1519631591,
        "marked_as_ads": 0,
        "post_type": "post",
        "text": "Post text",
        "can_edit": 1,
        "created_by": 564321,
        "can_delete": 1,
        "comments": {
          "count": 0
        }
      },
      "group_id": 123456
    }
  ]
}
```

### Информация о доступных пользователю функциях

Некоторые функции ботов могут быть недоступны, так как пользователи:
*  переходят на новые версии официальных приложений ВКонтакте постепенно;
*  открывают ВКонтакте на разных платформах (iOS, Android, в мобильной и веб-версии);
*  используют приложения от сторонних разработчиков. Например, клавиатура ботов может быть недоступна в старой версии официального приложения ВКонтакте.

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

Начиная с версии API 5.103 информация о доступных функциях будет приходить вместе с событием [`message_new`](api/community-events/json-schema) в Callback API и Bots Long Poll API. Она будет находиться в объекте `client_info`:

```JSON
"client_info": { 
    "button_actions": [ 
      "text", 
      "vkpay", 
      "open_app", 
      "location", 
      "open_link", 
      "callback" 
    ], 
    "keyboard": true, 
    "inline_keyboard": true, 
    "carousel": false, 
    "lang_id": 0 
} 
```

По мере появления новых возможностей в объекте `client_info` и массиве `button_actions` могут появляться новые сущности.

Поля объекта:
*  `button_actions` — массив кнопок, которые поддерживает клиент. Возможные значения смотрите в разделе [Клавиатура](api/bots/development/keyboard#Структура%20данных);
*  `keyboard` (`bool`) — поддерживается ли клавиатура ботов клиентом;
*  `inline_keyboard` (`bool`) — поддерживается ли inline-клавиатура ботов клиентом;
*  `carousel` (`bool`) — поддерживаются ли [карусели](api/bots/development/messages) клиентом;
*  `lang_id` — [ID](api/api-requests) используемого языка.

Интеграция | Чат-боты | Быстрый старт

# Боты для сообществ

**Бот** — это программа, которая имитирует некоторые действия человека. С его помощью можно автоматизировать рутинные задачи. 

Они нужны там, где есть много похожих действий, которые сейчас выполняются руками (или не выполняются вовсе — просто потому что нет столько рук).

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

![](47b0490c93d3c32d6c544be551a8806fe61b18d0ea3a07e85e0fcb85 "-5636580476323788944")

ВКонтакте боты общаются с вашими клиентами через [сообщения сообществ](api/community-messages/getting-started).
Это простой и привычный для пользователя интерфейс.

Бот будет полезен, если вы хотите:
*  обрабатывать много однотипных обращений,
*  организовывать рассылки для подписчиков,
*  фильтровать заявки в системах поддержки,
*  мгновенно реагировать на сообщения.

Это самые распространенные сценарии. На самом деле, боты пригодятся в сообществе любой тематики. Можно придумать собственную реализацию, которая подошла бы для развития именно вашей группы или публичной страницы.

> Бот может стать дополнительным средством для привлечения внимания к сообществу. Создавайте интерактивные квесты, присылайте подписчикам мультимедиа-материалы, подключайте сторонние API для реализации игровых сценариев — пользователи не пройдут мимо интересных предложений.


## Преимущества платформы

### Социальный граф

ВКонтакте вы можете работать с социальным графом, анализируя связи и интересы пользователя. Например, для создания рекомендательной системы или сервиса персональной инфографики.

### Мультимедиа

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

### Кроссплатформенность

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

## Документация

Чтобы научиться создавать ботов ВКонтакте, прочитайте [Быстрый старт](api/bots/getting-started).

## Примеры ботов

* Бот [РБК](https://vk.com/rbc) предлагает подписаться на рассылку актуальных новостей, умеет принимать жалобы на опечатки и решает вопросы, связанные с размещением рекламы.
* Бот принимал обращения от граждан в рамках [Прямой линии с Владимиром Путиным](https://vk.com/moskvaputinu).
* Бот [Vinci](https://vk.com/vinci) обрабатывает присланную фотографию с помощью хитрых алгоритмов и предлагает подходящие теги и Emoji для подписи.

:::carousel
![title=Бот РБК предлагает подписаться на рассылку актуальных новостей, умеет принимать жалобы на опечатки и решает вопросы, связанные с размещением рекламы.](bd62819e0364f07d86ec1137cb419a1bda0aa63058cd4a7e657592d2 "-3327336004805555787")
![title=Бот принимал обращения от граждан в рамках Прямой линии с Владимиром Путиным.](60fac052a021f365547cc1655b896ebab720dd620b13c44658233f3f "-4939451182648991171")
![Бот Vinci обрабатывает присланную фотографию с помощью хитрых алгоритмов и предлагает подходящие теги и Emoji для подписи.](3b415358de0139ef4e6477cf045321cb9c20ca02f52f3ddc270a4caa "7598733202427498813")
:::

Интеграция | Чат-боты | Боты для сообществ

Интеграция | Сообщества и пользователи | Callback API

# Ошибка с Captcha

Если какое-либо действие (например, отправка сообщения) выполняется пользователем слишком часто, то запрос к API может возвращать ошибку `"Captcha needed"`. При этом пользователю понадобится ввести код с изображения и отправить запрос повторно с передачей введенного кода [Captcha](https://ru.wikipedia.org/wiki/CAPTCHA) в параметрах запроса.
```JSON
{
  "error_code": 14,
  "error_msg": "Captcha needed"
}
```
Если возникает данная ошибка, то в сообщении об ошибке передаются также следующие параметры:
* `captcha_sid` — идентификатор `captcha`.
* `captcha_img` — ссылка на изображение, которое нужно показать пользователю, чтобы он ввел текст с этого изображения.

В этом случае следует запросить пользователя ввести текст с изображения `captcha_img` и повторить запрос, добавив в него параметры:
* `captcha_sid` — полученный идентификатор
* `captcha_key` — текст, который ввел пользователь
## Пример ошибки
```JSON
{
  "error":
  {
      "error_code":14,
      "error_msg":"Captcha needed",
      "request_params":
      [{
        "key":"oauth",
        "value":"1"
      },{
        "key":"method",
        "value":"captcha.force"
      },{
        "key":"uids",
        "value":"66748"
      },{
        "key":"access_token",
        "value":"b9b5151856dcc745d785a6b604295d30888a827a37763198888d8b7f5271a4d8a049fefbaeed791b2882"
      }], 
    "captcha_sid":"239633676097",
    "captcha_img":"http:\/\/api.vk.com\/captcha.php?sid=239633676097&s=1"
  }
}
```

Использование API | Обработка ошибок | Ошибка с Captcha

# Виджеты сообществ

Виджет представляет собой  отрисованный в соответствии с формальным описанием блок с информацией: например, список ресторанов или кинотеатров, результаты футбольного матча или киберспортивного поединка, перечень цен на услуги или объекты недвижимости. Блок с виджетом будет находиться в верхней части сообщества и доступен как в полной версии сайта, так и в мобильных клиентах.

Установка виджетов доступна из приложений, которые поддержали у себя эту возможность. Например: «Рассылки», «Тесты», «Пожертвования», «Заявки», «Анкеты», «Магазин товаров» и «Цитаты» (Все они доступны в официальном каталоге приложений: [vk.com/community_apps](https://vk.com/community_apps) ).

 ![title=Виджет Cover List](89451c8f61192a8e0602c173a42ab3fc6a00d1c5ed8dda941c67f482 "-5550232801630865703") 

> В виджете можно отображать список матчей, таблицу, цитату и многое другое. Все доступные типы виджетов подробно описаны [на этой странице](reference/objects/app-widget).

## Шаг 1. Получение ключа доступа

Для работы с виджетами в сообществе необходимо получить токен сообщества с правом доступа `app_widget` при помощи события VK Bridge [`VKWebAppGetCommunityToken`](bridge/VKWebAppGetCommunityToken) в приложении с типом VK Mini Apps.

## Шаг 2. Генерация виджета

Для генерации виджета и его обновления используйте метод  API [`appWidgets.update`](method/appWidgets.update). В качестве аргументов он принимает:
* `type` (`string`) — тип виджета. Может принимать значения `text`, `list`, `table`, `tiles`, `compact_list`, `cover_list`, `match`, `matches`, `donation`.
* `code` (`string`) — код виджета. Аналог параметра`code` в методе [`execute`](method/execute).

Синтаксис вызова методов API можно найти [здесь](api/api-requests).

### Базовые переменные

Переменная `Args` содержит в себе данные, которые могут пригодиться для отрисовки виджета:
*  `Args.uid` — идентификатор текущего пользователя.
*  `Args.platform` — тип платформы, с которой открыта группа:
   *  `web`
   *  `mobile`
   *  `android`
   *  `iphone`
*  `Args.lang` — идентификатор языка пользователя:
   *  `0` — русский
   *  `1` — украинский
   *  `2` — белорусский
   *  `3` — английский
   *  `4` — испанский
   *  `5` — финский
   *  `6` — немецкий
   *  `7` — итальянский

Внутри `code` можно использовать ограниченный набор методов API, по умолчанию используется версия API 5.100.

* [`users.get`](method/users.get)
* [`users.getSubscriptions`](method/users.getSubscriptions)
* [`users.getFollowers`](method/users.getFollowers)
* [`wall.get`](method/wall.get)
* [`wall.search`](method/wall.search)
* [`photos.getAlbums`](method/photos.getAlbums)
* [`photos.get`](method/photos.get)
* [`photos.getById`](method/photos.getById)
* [`photos.search`](method/photos.search)
* [`friends.get`](method/friends.get)
* [`widgets.getComments`](method/widgets.getComments)
* [`widgets.getPages`](method/widgets.getPages)
* [`wall.getById`](method/wall.getById)
* [`wall.getReposts`](method/wall.getReposts)
* [`wall.getComments`](method/wall.getComments)
* [`groups.isMember`](method/groups.isMember)
* [`groups.getById`](method/groups.getById)
* [`groups.getMembers`](method/groups.getMembers)
* [`board.getTopics`](method/board.getTopics)
* [`board.getComments`](method/board.getComments)
* [`likes.getList`](method/likes.getList)
* [`apps.getCatalog`](method/apps.getCatalog)
* [`apps.get`](method/apps.get)



`code` должен возвращать JSON-объект, описывающий виджет. Элементы виджета могут содержать только внутренние ссылки на vk.com (кроме away.php) и vk.me. 

В общем случае параметр `code` выглядит так:

```JSON
return {
    '''widget'''
};
```

Структура объекта `widget` зависит от типа виджета, подробное описание вы найдёте [на этой странице](reference/objects/app-widget).

Обновлять данные виджета через приложение можно не чаще 1 раза в 30 секунд.

![](6afc6ad9b639c9c32b833769889e9f7ce727c254d1e32abcfcb1f4c9 "-5747787520618281419")

Чтобы скрыть виджет у пользователя, передайте в `code` значение `"return false"`.  

## Изображения в виджете

В виджете могут быть использованы изображения из двух коллекций — относящиеся к приложению (для использования в разных сообществах) и к сообществу (для использования в одном конкретном сообществе). 

Для загрузки изображений нужно использовать соответственно методы API:
* [`appWidgets.getGroupImageUploadServer`](method/appWidgets.getGroupImageUploadServer),
* [`appWidgets.getAppImageUploadServer`](method/appWidgets.getAppImageUploadServer),
* [`appWidgets.saveGroupImage`](method/appWidgets.saveGroupImage),
* [`appWidgets.saveAppImage`](method/appWidgets.saveAppImage).

Необходимо загружать изображения в утроенном размере (например, для картинки с конечным размером 160x160 нужно загружать изображение размером 480x480).

> **Важно!** Вы можете использовать главные фотографии профилей, сообществ и других приложений внутри виджета. Для этого передайте в поле `icon_id` для квадратного изображения значение `id123456` — для главной фотографии профиля пользователя с id 123456, `club123456` — для сообщества или `app123456` — для приложения. В этом случае во всех аналогичных полях виджета также должны использоваться главные фотографии (соответственно, пользователей, сообществ или приложений).

Интеграция | Сообщества и пользователи | Виджеты сообществ

Интеграция | Сообщества и пользователи | События в сообществах

# Сообщения сообществ

Сообщения сообществ — сервис для прямого диалога между пользователем и сообществом ВКонтакте. 

![](45ee4961609a0b9362f7cedaf27e3c682d2e5bdb2f0e1304b6bf6486 "-5881812424441223520")

Это удобно для ваших клиентов. Не нужно искать форму обратной связи, проходить регистрацию, отвечать через email — никаких лишних действий.

Это удобно для вас. Вместе с сообщением вы получаете все необходимые данные о его авторе, можете автоматически обрабатывать типовые заявки и мгновенно отвечать на сообщения с помощью бота.

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

Сообщения сообществ работают в полной и мобильной версиях ВКонтакте, а также во всех официальных приложениях:  с вашей компанией можно связаться на любой платформе.

![](7bc2a650a8d1ec1313f0acc698c6b3302a648aaea8b8102b6618e049 "9214525706664327534")

Подробнее обо всех преимуществах для бизнеса мы рассказали на [отдельной странице](https://vk.com/page-19542789_51260895).

## API для сообщений сообществ

В этом руководстве рассказывается о том, как использовать API для работы с сообщениями сообществ. 

## Ключ доступа

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

Ключ доступа — это строка, включающая латинские буквы и цифры. Ее необходимо передавать в параметре `access_token`, обращаясь к методам API от имени сообщества.

## Получение ключа доступа в настройках сообщества

Откройте раздел **Управление сообществом** (**Управление страницей**, если у вас публичная страница), выберите вкладку **Работа с API** и нажмите  **Создать ключ доступа**.

Отметьте необходимые права доступа и подтвердите свой выбор. 
![](94dbda6f9957847362a13776b0676208b2cedee8d63b617201bc5742 "-8033473622113514247")

Вы можете создать несколько ключей с разными правами доступа. Ключи нельзя размещать публично — узнав его, третье лицо может обращаться к API ВКонтакте от имени вашего сообщества. Если ключ был скомпрометирован, необходимо удалить его из списка — после этого он станет недействителен.

## Получение ключа доступа на oauth.vk.com

Мы предлагаем два способа авторизации, основанных на протоколе OAuth 2.0. Используйте этот подход, если необходимо работать со многими сообществами пользователя, например, при разработке мобильного приложения. 

Для работы с API с серверной стороны используйте [Authorization Code Flow](api/access-token/authcode-flow-community).

Для работы с API со стороны клиента используйте [Implicit Flow](api/access-token/implicit-flow-community).

## Работа с сообщениями

В API сообщений сообществ используются те же методы, что и для работы с личными сообщениями пользователя. Если раньше вы уже имели дело с сообщениями в API ВКонтакте, схема работы будет вам знакома. Стоит, однако, учитывать некоторые особенности:
*  необходимо проставлять статус прочитанности сообщения при общении с клиентом; 
*  если ответ получен пользователем, его необходимо помечать как прочитанный; 
*  в диалогах сообществ доступны специальные метки: **Важные**, **Неотвеченные**, **Непрочитанные**. 

Чтобы вы могли отправлять пользователю сообщения от имени сообщества, пользователь должен разрешить их получение. Если пользователь написал сообщение сообществу первым, это приравнивается к согласию на получение ответных сообщений (без ограничений по времени, если пользователь не запретил сообщения вручную). Чтобы запросить у пользователя разрешение на отправку сообщений, используйте:
*  Метод [`showAllowMessagesFromCommunityBox`](sdk/javascript#showAllowMessagesFromCommunityBox) Client API в приложениях сообществ;
*  Метод [`messages.allowMessagesFromGroup`](method/messages.allowMessagesFromGroup) в Standalone-приложениях;
*  Виджет [Разрешить писать сообществу](widgets/allow-messages-from-community) на внешнем сайте.

В [Callback API](api/callback/getting-started) и [Bots Longpoll API](api/bots-long-poll/getting-started) события `message_allow` и `message_deny` помогут отслеживать факт разрешения и запрета сообщений от сообщества. **Обратите внимание**, получить список всех пользователей, разрешивших сообщения сообществу, через API нельзя, необходимо хранить и синхронизировать этот список на своей стороне.

## Доступные инструменты и методы

*  [Long Poll сервер](api/user-long-poll/getting-started) — синхронизация обновлений; 
*  [Callback API](api/callback/getting-started) — мгновенные оповещения о новых сообщениях и других действиях пользователей в сообществе.
*  [`messages.getDialogs`](method/messages.getDialogs) — метод для получения списка диалогов; 
*  [`messages.markAsRead`](method/messages.markAsRead) — метод для присвоения сообщению метки **Прочитано**;
*  [`messages.markAsImportantDialog`](method/messages.markAsImportantDialog), [`messages.markAsAnsweredDialog`](method/messages.markAsAnsweredDialog) — методы для присвоения меток диалогам;
*  [`messages.send`](method/messages.send) — метод для отправки нового сообщения;
*   [`messages.delete`](method/messages.delete), [`messages.deleteDialog`](method/messages.deleteDialog), [`messages.restore`](method/messages.restore) — методы для удаления и восстановления сообщений и диалогов;
*  [`messages.search`](method/messages.search) — метод для поиска по сообщениям;
*  [`messages.allowMessagesFromGroup`](method/messages.allowMessagesFromGroup), [`messages.denyMessagesFromGroup`](method/messages.denyMessagesFromGroup) — методы для подписки на сообщения сообщества и запрета на получение сообщений;
*   [`docs.getWallUploadServer`](method/docs.getWallUploadServer), [`docs.save`](method/docs.save), ,  — методы для загрузки фотографий и документов.
*  [`groups.getCallbackConfirmationCode`](method/groups.getCallbackConfirmationCode), [`groups.getCallbackServerSettings`](method/groups.getCallbackServerSettings), [`groups.getCallbackSettings`](method/groups.getCallbackSettings), [`groups.setCallbackSettings`](method/groups.setCallbackSettings) — методы для работы с настройками Callback API.

## Получение списка диалогов

Метод [`messages.getDialogs`](method/messages.getDialogs). 

Параметр `start_message_id` используется для защиты от смещения из-за новых сообщений при подгрузке старых диалогов. При первом вызове не передавайте `start_message_id`, запомните значение `id` у сообщения в первом диалоге и используйте его в качестве `start_message_id` в последующих вызовах при подгрузке диалогов.
 
```
https://api.vk.com/method/messages.getDialogs?v=5.41&access_token=ACCESS_TOKEN&count=10&offset=0
```

## Получение новых диалогов

Метод [`messages.getDialogs`](method/messages.getDialogs). 

Передавайте в `start_message_id` значение `id` сообщения в первом диалоге, в `count` максимальное количество новых диалогов, а в `offset`, соответственно, отрицательное значение. 

```
https://api.vk.com/method/messages.getDialogs?v=5.41&access_token=ACCESS_TOKEN&count=10&unread=1&offset=-10&start_message_id=64
```

## Получение истории сообщений в диалоге

Метод [`messages.getHistory`](method/messages.getHistory).

Чтобы получить историю конкретного диалога, используйте параметр `peer_id`. Параметр `start_message_id` используется для защиты от смещения из-за новых сообщений при подгрузке истории. При первом вызове не передавайте `start_message_id`, `запомните` значение `id` первого сообщения из ответа и используйте его в качестве `start_message_id` в последующих вызовах. 

```
https://api.vk.com/method/messages.getHistory?v=5.41&access_token=ACCESS_TOKEN&peer_id=494075&offset=0&count=10
```

```
https://api.vk.com/method/messages.getHistory?v=5.41&access_token=ACCESS_TOKEN&peer_id=494075&offset=10&count=10&start_message_id=60
```


## Получение новых сообщений с помощью Callback API

[Callback API](api/callback/getting-started) позволяет мгновенно получать информацию о новых сообщениях в адрес сообщества.

Для работы с Callback API вам потребуется серверный скрипт для обработки уведомлений. Настройте оповещения, следуя [документации](api/callback/getting-started), среди типов событий выберите **Получение нового сообщения** (`message_new`).

ВКонтакте будет отправлять на ваш сервер оповещение о каждом новом сообщении с [объектом личного сообщения](reference/objects/message) в таком формате:

```JSON
{
  "type": "message_new",
  "object": "..."
}
```

В уведомлении содержится исчерпывающая информация о сообщении — вы можете сразу ответить на него, используя метод [`messages.send`](method/messages.send).

## Передача произвольного параметра с помощью ссылки vk.me

vk.me — это сервис коротких URL, который перенаправляет пользователей в указанный диалог. 
Ссылка имеет формат http://vk.me/{group_name}, где `group_name` —  идентификатор сообщества. К примеру, vk.me/apiclub.

Вы можете  не только создать красивую ссылку на  диалог с сообществом, но и передать в такой ссылке произвольные параметры `ref` и `ref_source`, которые вернутся в объекте сообщения в [событии](api/community-events/json-schema) `message_new` [Callback API](api/callback/getting-started)  или [Bots Long Poll API](api/bots-long-poll/getting-started), в случае если пользователь начнет или продолжит беседу по ссылке вида vk.me.

Это полезно для отслеживания эффективности ссылок, размещенных в разных каналах, или привязки пользователя к сеансу или аккаунту во внешнем приложении. В зависимости от переданного параметра можно варьировать ответы бота в сообществе.

Ссылка vk.me с дополнительными параметрами выглядит следующим образом:

```
vk.me/{group_name}?ref={ref}&ref_source={ref_source}
```

Также сработает вот такая ссылка:

```
vk.com/write-{group_id}?ref={ref}&ref_source={ref_source}
```

## Отправка изображений

Чтобы отправить изображение в сообщении, используйте параметр `attachments` в методе [`messages.send`](method/messages.send). Вы можете использовать изображение, которое уже есть на сайте ВКонтакте, либо [загрузить новое](api/upload#Загрузка%20фотографии%20в%20личное%20сообщение).


Для загрузки фотографий и документов в сообщения сообщества используйте, соответственно, методы [`photos.getMessagesUploadServer`](method/photos.getMessagesUploadServer) и [`docs.getMessagesUploadServer`](method/docs.getMessagesUploadServer). Это позволит загружать вложения для неограниченного числа собеседников.

Интеграция | Сообщества и пользователи | Сообщения сообществ

# Прямая авторизация

> **Внимание!** 
> * Доступ к этому типу авторизации может быть получен только после предварительного согласования с администрацией ВКонтакте.
> * Для подачи заявки на получение доступа необходимо обратиться в службу поддержки по адресу [https://vk.com/support](https://vk.com/support), указав идентификатор вашего приложения. В заявке необходимо кратко описать функционал приложения.
> * В настоящий момент эта возможность есть только у платформ, не поддерживающих [стандартную авторизацию](api/access-token/implicit-flow-user). 

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

Обратите внимание, что приложение не должно хранить пароль пользователя. 
Выдаваемый `access_token` не привязан к IP-адресу пользователя, поэтому его достаточно для последующей работы с API без повторения процедуры авторизации. 

## Параметры запроса

Для авторизации нужно послать запрос на адрес [`https://oauth.vk.com/token`](https://oauth.vk.com/token), передав следующие `POST`-параметры:

* `grant_type` (**обязательный параметр**) — тип авторизации, должен быть равен `password`.
* `client_id` (**обязательный параметр**) — id вашего приложения.
* `client_secret` (**обязательный параметр**) — секретный ключ вашего приложения.
* `username` (**обязательный параметр**) — логин пользователя.
* `password` (**обязательный параметр**) — пароль пользователя.
* `scope` — [права доступа](reference/access-rights), необходимые приложению.
* `test_redirect_uri` — использовать ли тестовую проверку. Допустимые значения:
    * `1` — инициировать тестовую проверку пользователя, используя `redirect_uri`.
    * `0` — обычная авторизация (по умолчанию).
* `v` — [Версия API](reference/versions), которую вы используете. При повышении версии пожалуйста ознакомьтесь со [списком изменений](reference/versions). Актуальная версия: **:version**.
* `2fa_supported` — передайте `1`, чтобы включить поддержку двухфакторной аутентификации.

### Пример запроса авторизации

```
https://oauth.vk.com/token?grant_type=password&client_id=1914441&client_secret=***&username=***&password=***&v=:version&2fa_supported=1
```

## Обработка дополнительных проверок аккаунта

В случаях, когда требуется дополнительная проверка пользователя, например при авторизации из подозрительного места, будет возвращена следующая ошибка:

```JSON
{
  "error": "need_validation",
  "error_description": "please open redirect_uri in browser",
  "redirect_uri": "https://oauth.vk.com/security_check?type=test&mid=66748&hash=23132d8b8744f8b1b2"
}
```

В этом случае необходимо открыть браузер со страницей, указанной в поле `redirect_uri` и ждать, пока пользователь будет направлен на страницу blank.html с параметром `success=1` в случае успеха и `fail=1` в случае, если пользователь отменил проверку своего аккаунта. 

Для тестового вызова проверки добавьте параметр `test_redirect_uri=1`. 

## Двухфакторная аутентификация

Если вы передали в запросе параметр `2fa_supported=1` и у пользователя включена двухфакторная аутентификация, на запрос с верными логином и паролем вернется ошибка `need_validation` со следующими полями:

* `validation_type` — тип подтверждения. Возможные значения:
    * `2fa_sms` — подтверждение через SMS;
    * `2fa_app`  — подтверждение с помощью приложения для генерации кодов.
* `phone_mask` — маска номера телефона.

Необходимо запросить у пользователя код подтверждения и повторно отправить запрос на авторизацию с дополнительным параметром `code`, содержащим код подтверждения.

Если возникли проблемы с получением кода из приложения или пользователь не хочет использовать приложение для генерации кодов, вы можете форсировать получение кода по SMS, повторно передав запрос авторизации с параметром `force_sms`=`1`.

### Пример ответа

```JSON
{
  "access_token": "9d77c727986d7668986d7668049870402D1986d986d76684bbc9b1bf8488de9",
  "expires_in": 0,
  "user_id": 85635407
}
```


### Пример ответа при необходимости ввода CAPTCHA

```JSON
{
  "error": "need_captcha",
  "captcha_sid": "854844498568",
  "captcha_img": "http://api.vk.com/captcha.php?sid=854844498568&s=1"
}
```

В этом случае необходимо повторить запрос, добавив к нему следующие параметры:
* `captcha_sid` — поле `captcha_sid`, полученное в предыдущем запросе;
* `captcha_key` — то, что ввёл пользователь.

Использование API | Ключ доступа | Прямая авторизация

# VK Donut API

**API ВКонтакте** позволяет получать информацию о платных подписках и подписчиках в сообществах, использующих [VK Donut](https://vk.com/@donut-faq), а также публиковать в них платный контент.

## Для кого этот раздел

Этот раздел для разработчиков приложений, которые хотят использовать API ВКонтакте. Вам будет проще, если вы уже знакомы с [API ВКонтакте](api/getting-started), методами [авторизации](api/access-token/getting-started) и знаете, что такое [VK Donut](https://vk.com/@donut-faq).

Если вы уже используете [VK Donut](https://vk.com/@donut-faq) и разобрались, как получить [ключ доступа](api/access-token/getting-started) к API ВКонтакте, переходите к разделу [Методы](#Методы). Если нет, сначала прочитайте раздел [Подготовка](#Подготовка).

## Подготовка

1. Подключите [VK Donut](https://vk.com/@donut-faq) в настройках сообщества.

2. [Создайте приложение](api/getting-started#Регистрация%20приложения). API можно использовать в приложении любого типа. Если вы пока не знаете, какой тип выбрать, создайте **Standalone-приложение**. Идентификатор приложения понадобится вам на следующем шаге, чтобы получить ключ доступа к API.

3. Получите [ключ доступа](api/access-token/getting-started). Ключ доступа нужно будет указывать во всех запросах из приложения (параметр `access_token`). Получить его можно разными способами. Всё зависит от того, какие [права доступа](reference/access-rights) вам нужны и как вы будете отправлять запросы (от имени пользователя или сообщества, со стороны клиента или сервера).

> **Совет.** Отправлять запросы можно прямо из [документации](method/donut.isDon). Идентификатор приложения и ключ доступа указывать не понадобится, достаточно войти в свой аккаунт ВКонтакте.

## Методы

В [запросе](api/api-requests) нужно указать:

* Метод. В таблице ниже собраны методы, которые понадобятся для работы с сообществами, использующими VK Donut. Название метода может начинаться с префиксов: [`donut`](method/donut.isDon), [`groups`](method/groups.getMembers), [`wall`](method/wall.post).

* Параметры. Обязательные параметры: `access_token` (ключ доступа) и `v` (версия API). В [справочнике методов](method) написано, к какой версии API относится каждый метод, какие ещё параметры есть у метода и какие нужны [права доступа](reference/access-rights). В запросе нужно указать тот ключ доступа, права доступа которого соответствуют методу.

### Пример

Чтобы узнать, является ли пользователь доном (так мы называем получателей платного контента в сообществе), отправьте запрос:

```
https://api.vk.com/method/donut.isDon?owner_id=-1&access_token=42&v=:version
```

В этом примере замените `-1` на идентификатор сообщества (со знаком минуса), а `42` — на ключ доступа пользователя.

> **Совет.** Войдите в свой аккаунт ВКонтакте и отправьте запрос прямо из [документации](method/donut.isDon).

### Методы, которые относятся к работе VK Donut

| Метод | Результат |
| --- | --- |
| [`donut.isDon`](method/donut.isDon) | Подписан ли пользователь на платный контент (является ли доном).|
| [`donut.getSubscription`](method/donut.getSubscription) | Стоимость подписки, статус, дата следующего платежа.|
| [`donut.getSubscriptions`](method/donut.getSubscriptions) | Подписки пользователя.|
| [`donut.getFriends`](method/donut.getFriends) | Список донов из числа друзей пользователя.|
| [`groups.getMembers`](method/groups.getMembers) | Список донов сообщества по ключу пользователя (ключ должен принадлежать как минимум редактору сообщества) и по ключу сообщества (см. параметр `filter`).|
| [`wall.post`](method/wall.post) | Публикует на стене запись только для донов. Позволяет задать время, через которое запись появится для всех подписчиков, то есть станет бесплатной (см. параметр `donut_paid_duration`).|
| [`wall.edit`](method/wall.edit) | Меняет значение параметра `donut_paid_duration`.|

## События

Вы можете получать информацию о [событиях](api/events/overview), которые происходят в вашем сообществе, с помощью:

* [Callback API](api/callback/getting-started). Мы будем отправлять на ваш сервер уведомление о каждом новом событии.
* [Bots Long Poll API](api/bots-long-poll/getting-started). Очередь из событий хранится на серверах ВКонтакте, вы получаете уведомления когда захотите, используя запросы.

### События, которые относятся к работе VK Donut

|Название события | Что произошло в сообществе |
| --- | --- |
|[`donut_subscription_create`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Пользователь оформил подписку.|
|[`donut_subscription_prolonged`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Пользователь продлил подписку.|
|[`donut_subscription_expired`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Подписка пользователя истекла.|
|[`donut_subscription_cancelled`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Пользователь отменил подписку.|
|[`subscription_price_changed`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Изменилась стоимость подписки.|
|[`donut_money_withdraw`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Руководитель сообщества вывел деньги.|
|[`donut_money_withdraw_error`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Ошибка при выводе денег.|

## FAQ

#### Зачем нужен VK Donut?

VK Donut позволяет руководителям сообществ принимать платежи от подписчиков.

#### Где ещё можно прочитать про VK Donut?

В [сообществе](https://vk.com/donut) есть [правила публикаций](https://vk.com/@donut-pravila) и подробный FAQ, в котором мы рассказали, например, про [платежи](https://vk.com/@donut-faq?anchor=chto-vybrat-kartu-ili-vk-pay).

#### Кто такие доны?

Доны — это получатели платного контента, которые подписываются на него с помощью VK Donut.

#### Как выглядит идентификатор сообщества?

Идентификатор сообщества — это целое число (порядковый номер). Например, на странице нашего официального сообщества указан `ID:` [192668858](https://vk.com/donut). Но при работе с API используется отрицательное число -192668858, чтобы отличить идентификатор сообщества от идентификатора пользователя.

#### Почему в примере идентификатор сообщества: `-1`?

Пользователи и сообщества нумеруются по порядку, поэтому у пользователя и сообщества может быть одинаковый идентификатор. Например, есть [пользователь](https://vk.com/id1) и [сообщество](https://vk.com/apiclub) с `ID:` 1. Если метод требует передать идентификатор пользователя, нужно указывать `owner_id=1` (положительное число), если идентификатор сообщества, то `owner_id=-1` (отрицательное число).

#### В запросах можно передавать `lang`?

Да. [Параметры, общие для всего API](api/api-requests#Общие%20параметры), можно использовать во всех методах API ВКонтакте.

#### Можно ли сделать платным бесплатный контент?

Нет, если запись уже опубликована. Можно, если вы создали [отложенную запись](api/posts#Публикации%20из%20приложений) и она ещё не опубликована.

#### Можно ли сделать бесплатным платный контент?

Да. Используйте метод [`wall.post`](method/wall.post), в запросе укажите идентификатор записи (`post_id`). Обратите внимание, что в этом случае создастся бесплатная копия платной записи. Но только одна — создать больше копий не получится.

#### Я создал запись для донов, но потом решил сделать её бесплатной пораньше. Можно ли изменить время, указанное в donut_paid_duration?

Да. Чтобы изменить значение `donut_paid_duration` (время, через которое платная запись должна стать бесплатной), нужно задать новое значение этого параметра с помощью метода [`wall.edit`](method/wall.edit). Обратите внимание, что когда время истечёт, появится копия платной записи.

Интеграция | Платежи | VK Donut API

# События в реальном времени

API ВКонтакте позволяет работать с событиями пользователя или сообщества в реальном времени. Это нужно для отображения нового сообщения, для моментальной реакции на комментарий в сообществе, для создания [чат-ботов](api/bots/overview) или для анализа текстовых данных.

## Для сообществ

Для работы с событиями сообществ мы предлагаем два разных подхода:

* [Callback API](api/callback/getting-started) — в этом случае мы будем отправлять уведомление на ваш сервер о каждом новом событии.
* [Bots Long Poll API](api/bots-long-poll/getting-started) — очередь из событий хранится на стороне ВКонтакте, вы получаете их, используя Long Polling запросы.

Callback API и Bots Long Poll API поддерживают события, связанные с сообщениями сообщества, активностью пользователей на стене и в остальных разделах вашей группы или публичной страницы. Полный список событий в сообществах вы можете найти [на этой странице](api/community-events/json-schema).

## Для пользователей

[User Long Poll API](api/user-long-poll/getting-started) нужен для работы с событиями пользователя в вашем приложении. Очередь из событий хранится на стороне ВКонтакте, вы получаете их, используя Long Polling запросы.

User Long Poll API поддерживает все события, связанные с личными сообщениями (получение, редактирование, удаление), изменение статуса онлайн или счётчиков в меню.

## Для аналитики

[Streaming API](api/streaming/getting-started) позволяет получать текстовые публикации из ВКонтакте по заданным ключевым словам, не совершая лишних поисковых запросов.

Streaming API доставляет данные с помощью технологии WebSocket. Благодаря этому инструменту вы можете проанализировать частоту, тональность и контекст упоминания вашего бренда ВКонтакте, провести социологическое исследование, и многое другое.

Интеграция | Сообщества и пользователи | События пользователей и сообществ

# Быстрый старт

В этом руководстве вы найдете базовую информацию о принципах работы API ВКонтакте и о подготовке к его использованию. Если вы уже работали с нашим API или с аналогичными сервисами других платформ, и знаете, какое приложение хотите создать, мы рекомендуем вам перейти в соответствующий раздел документации.

[API (application programming interface)](https://ru.wikipedia.org/wiki/API) — это посредник между разработчиком приложений и какой-либо средой, с которой это приложение должно взаимодействовать. API упрощает создание кода, поскольку предоставляет набор готовых классов, функций или структур для работы с имеющимися данными.

## Методы и объекты

**API ВКонтакте** — это интерфейс, который позволяет получать информацию из базы данных [vk.com](https://vk.com) с помощью http-запросов к специальному серверу.  Вам не нужно знать в подробностях, как устроена база, из каких таблиц и полей каких типов она состоит — достаточно того, что API-запрос об этом знает. Синтаксис запросов и тип возвращаемых ими данных строго определены на стороне самого сервиса. 

Например, для получения данных о пользователе с идентификатором `210700286` необходимо составить запрос такого вида:

```
https://api.vk.com/method/users.get?user_id=210700286&v=:version
```

Рассмотрим отдельно все его составляющие:

* `https://` — протокол соединения,
* `api.vk.com/method` — адрес API-сервиса,
* `users.get` — название метода API ВКонтакте,
* `?user_id= &v= ` — параметры запроса.

Методы представляют собой условные команды, которые соответствуют той или иной операции с базой данных — получение информации, запись или удаление. Например, `users.get` — метод для получения информации о пользователе, `video.add` — метод для добавления видеозаписи в свой список, `likes.delete` — метод для удаления отметки «Мне нравится».

Все методы разделены на секции. Например, для работы с сообществами вам нужны методы секции `groups`, для работы с фотографиями — `photos`, и так далее. Полный список методов по секциям доступен в разделе [Методы API](method).

После названия метода нужно передать его входные данные (если они есть) — как обычные GET-параметры в http-запросе. В нашем примере мы сообщаем серверу, что хотим получить данные о пользователе с `id=210700286` и формат этих данных должен соответствовать версии API  :version (о версиях мы еще поговорим позже). Входные параметры всегда перечислены на странице с описанием метода.

В ответ сервер вернет JSON-объект с запрошенными данными (или сообщение об ошибке, если что-то пошло не так). 
**JSON** — это формат записи данных в виде пар «имя свойства»: «значение». Если вы раньше не встречались с этим форматом, мы рекомендуем познакомиться с ним, прежде чем продолжить чтение: [JSON, Wikipedia](https://ru.wikipedia.org/wiki/JSON).

Ответ на наш запрос выглядит так:

```JSON
{
  "response": [
    {
      "id": 210700286,
      "first_name": "Lindsey",
      "last_name": "Stirling"
    }
  ]
}
```

Структура ответа каждого метода также строго задана, и при работе с API вы заранее знаете, что в поле `id` придет число, а в поле `first_name` — строка. Такие правила оговариваются на страницах с описанием метода и соответствующих объектов, которые он возвращает в ответе. Например, [`users.get`](method/users.get) — здесь описаны входные параметры метода и структура его ответа, а здесь — [`user`](reference/objects/user) подробно расписано каждое поле объекта из ответа.

Объект из ответа может быть не уникален для конкретного метода. Например, [объект пользователя](reference/objects/user) с набором полей, содержащих данные о его образовании, возрасте, интересах, может возвращаться в ответе от методов [`users.get`](method/users.get), [`users.search`](method/users.search), [`groups.getMembers`](method/groups.getMembers) и еще нескольких.

## Регистрация приложения

В [примере](#Методы%20и%20объекты) мы использовали метод [`users.get`](method/users.get), который позволяет получить информацию о пользователях, но для разработки приложений этого будет мало. Чтобы использовать все возможности API ВКонтакте, нужно зарегистрировать своё приложение.

Выберите [Мои приложения](https://vk.com/apps?act=manage) в верхнем меню и нажмите кнопку [Создать](https://vk.com/editapp?act=create). Создать приложение можно для одной из четырех платформ:

*  Встраиваемое приложение — вы получите приложение, которое можно встроить во фрейм с внешнего сайта. Готовые приложения можно увидеть в наших каталогах: [Мини-приложения](https://vk.com/services), [Игры](https://vk.com/apps).
*  Standalone-приложение — вы получите `API_ID` для внешнего сайта, мобильного или десктопного клиента. Основная мысль в том, что запросы к API должны отправляться с устройства пользователя. В интерфейсе такого приложения можно настроить [SDK](sdk/overview) и подключить сертификаты для push-уведомлений. 
*  Сайт — вы получите `API_ID` для внешнего сайта и работы с API через сервер. Если вы хотите написать скрипт (например, на PHP), который будет обращаться к API ВКонтакте, выберите именно этот вариант. 
*  Скилл Маруси — платформа для создания приложений, которые взаимодействуют с голосовым помощником. 

> **Совет.** Если вы пока не знаете, какую платформу выбрать, используйте Standalone-приложение. Мы обычно рекомендуем его для тренировки.

После подтверждения откроется страница с информацией о приложении. 
Откройте раздел **Настройки** в меню слева. В поле **ID приложения** будет число (например, `5490057`). Это идентификатор вашего приложения, в дальнейшем он понадобится вам, чтобы указать значение `API_ID`, `APP_ID` или `client_id`.

## Авторизация пользователя

ВКонтакте — социальная сеть, где есть дружеские связи, настройки приватности и даже черные списки. Многое зависит от того, кто просматривает страницу: кто-то увидит на ней всю ту же информацию, что и владелец, а кто-то — лишь общедоступные данные.

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

В общем случае для идентификации в API используется специальный ключ доступа, который называется `access_token`. 
**Токен** — это строка из цифр и латинских букв, которую вы передаете на сервер вместе с запросом. Из этой строки сервер получает всю нужную ему информацию. Есть разные способы получения токена, более того, он может быть выдан не только пользователю, но и сообществу, и сразу всему приложению — подробнее об этом вы можете прочитать [здесь](api/access-token/getting-started).

Мы воспользуемся самым простым способом ([Implicit flow](api/access-token/implicit-flow-user)) и получим токен для работы с API из созданного вами на прошлом этапе приложения.

Откройте новую вкладку в браузере и введите в адресную строку такой запрос:

```
https://oauth.vk.com/authorize?client_id=5490057&display=page&redirect_uri=https://oauth.vk.com/blank.html&scope=friends&response_type=token&v=:version
```

Число `5490057` в запросе нужно заменить на `API_ID` вашего приложения.

Нажмите **Enter**. Откроется окно с запросом прав. В нем отображаются название приложения, иконки прав доступа, и ваши имя с фамилией.

Нажмите **Разрешить**. вы попадете на новую страницу с предупреждением о том, что токен нельзя копировать и передавать третьим лицам. В адресной строке будет URL [`https://oauth.vk.com/blank.html`](https://oauth.vk.com/blank.html), а после `#` вы увидите дополнительные параметры — `access_token`, `expires_in` и `user_id`. Токен может выглядеть, например, так:

```
51eff86578a3bbbcb5c7043a122a69fd04dca057ac821dd7afd7c2d8e35b60172d45a26599c08034cc40a
```

Токен — это ваш ключ доступа. При выполнении определенных условий человек, получивший ваш токен, может нанести существенный ущерб вашим данным и данным других людей. Поэтому очень важно не передавать свой токен третьим лицам.

Поле `expires_in` содержит время жизни токена в секундах. 86400 секунд — это ровно сутки. Через сутки полученный токен перестанет действовать, для продолжения работы нужно будет получить новый. Есть возможность получить токен без срока действия — для этого в `scope` добавьте значение `offline`. Вы можете принудительно отозвать токен (например, в том случае, если он стал известен постороннему), сбросив сеансы в настройках безопасности вашего аккаунта или сменив пароль. Также, если речь идет о токене не из вашего собственного приложения, можно просто удалить приложение из настроек: [https://vk.com/settings?act=apps](https://vk.com/settings?act=apps)

Поле `user_id` содержит id пользователя, для которого получен токен.

Теперь вы можете сделать вызов метода от своего имени. Например, получить список друзей, которые сейчас находятся на сайте.

Для этого введите в адресную строку:

```
https://api.vk.com/method/friends.getOnline?v=:version&access_token=
```

и вставьте после знака `=` свой `access_token`, затем нажмите Enter. В ответе сервер вернет список идентификаторов ваших друзей, которые сейчас онлайн. Почитать подробнее о работе этого метода можно [здесь](method/friends.getOnline). Заметьте, вы не указали в запросе, для какого пользователя (`user_id`) нужно получить список — сервер использовал значение по умолчанию, т.е. ваш идентификатор, который он получил из токена.

Подробное руководство о получении ключей доступа находится [на этой странице](api/access-token/getting-started).

## Права доступа

Как вы уже знаете, все методы делятся на секции — `friends`, `photos`, `video` и так далее. Каждая секция соответствует определенному разделу на сайте. Часто приложения создаются для работы с конкретным разделом. Например, для просмотра фотографий или для редактирования видео. При этом логично, что приложению, которое работает только с аудиозаписями пользователя, не нужен доступ одновременно и к его личным сообщениям.

Поэтому в API права доступа приложения разграничены, как и методы. Приложение может запросить доступ только к группам, а может — к группам, фотографиям и аудиозаписям. [На этой странице](reference/access-rights) перечислены все существующие права доступа, которые можно запросить.

Чтобы запросить права, используйте параметр `scope` диалога авторизации. Когда вы получали токен для своего приложения, в `scope` было указано значение `friends` — и в окне авторизации приложение запросило доступ к друзьям.

У каждого права доступа есть уникальное название (`friends`, `video` и т.д.) и код (+2, +4, +4096). 
В `scope` можно перечислить названия нужных прав доступа (например, `scope`=`friends,video,photos`), а можно указать сумму их кодов (например, `scope`=`22`). Каждый код представляет собой степень двойки, и полученную таким образом сумму (битовую маску) вы всегда можете проверить на предмет содержания какого-то конкретного кода (например, с помощью [`account.getAppPermissions`](method/account.getAppPermissions)). 

Некоторые права доступа из соображений безопасности можно запрашивать только в Standalone-приложениях и только в процессе авторизации Implicit Flow, обратите на это внимание. 

## Что дальше

Вы познакомились с основными понятиями, связанными с API ВКонтакте. Дальше все зависит лишь от вашего вдохновения.

Конечно, на практике никто не работает с API из соседней вкладки браузера. Для этого используют самые разные языки программирования, SDK, генераторы кода. Сам механизм работы с API весьма прост, средства для отправки http-запросов и обработки ответа от сервера предусмотрены практически в любой среде разработки: а значит, возможность выбора всегда есть.

Использование API | Быстрый старт

# API для товаров

Для работы с товарами используются методы секции [`market`](method/market). В этом руководстве мы расскажем подробнее о том, что можно сделать с их помощью.

## Подготовка к работе

> [Знакомство с API](api/getting-started) — если вы ранее не имели дела с API ВКонтакте, перед началом работы мы рекомендуем узнать об основных принципах его использования.

В первую очередь подключите сервис «Товары» в настройках вашего сообщества или с помощью метода [`groups.edit`](method/groups.edit).

Вам нужно создать приложение: [https://vk.com/editapp?act=create](https://vk.com/editapp?act=create)
Для работы со стороны клиента (например, в мобильном приложении) выберите платформу **Standalone**. Для работы со стороны сервера выберите платформу **Веб-сайт**.

Укажите название и сохраните данные, подтвердив действие через СМС. вы попадете в интерфейс администрирования приложения. В дальнейшем вам понадобятся значения полей **ID приложения** (в документации — `API_ID`, `APP_ID`, `client_id`) и **Защищенный ключ** (`client_secret`, `app_secret`). 

Затем необходимо получить ключ доступа для вызова методов API. вы можете использовать один из этих подходов:

* [Implicit Flow](api/access-token/implicit-flow-user) для работы со стороны клиента.
* [Authorization Code Flow](api/access-token/authcode-flow-user) для работы со стороны сервера.
При авторизации нужно запросить у пользователя права доступа `market`. Список всех возможных прав доступа вы найдете [на этой странице](reference/access-rights).

Вызывать методы для работы с товарами вы можете [напрямую](api/api-requests) или с использованием наших [SDK](sdk/overview). 

## Действия с товарами

### Добавление товара

Используйте метод [`market.add`](method/market.add), чтобы добавить новый товар в сообщество. В `owner_id` необходимо передать идентификатор вашего сообщества со знаком минус. Название и описание задаются параметрами `name` и `description`, цена — параметром `price`. `category_id` — категория товара (например, «Аксессуары»). Список категорий можно получить методом [`market.getCategories`](market.getCategories). Если товар пока недоступен, чтобы он не отображался для пользователей, передайте `deleted = 1`.

В `main_photo_id` и `photo_ids` нужно передать идентификаторы фотографий (основной и дополнительной) для товара. вы можете узнать подробнее о загрузке фотографий [в следующем разделе](#3.%20Загрузка%20изображений).

После успешного добавления товара метод вернет его идентификатор в поле `market_item_id`. Товар можно использовать как вложение в записях на стене и личных сообщениях, для этого передайте в параметре `attachments` (`attachment`) его строковый идентификатор в виде `market-{owner_id}_{market_item_id}`, например, `market-12345_54321`.

### Действия с заказами

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

* [`market.getGroupOrders`](method/market.getGroupOrders) — возвращает заказы сообщества;
* [`market.getOrderById`](method/market.getOrderById) — возвращает заказ по идентификатору;
* [`market.getOrderItems`](method/market.getOrderItems) — возвращает товары в заказе;

Отслеживать заказы можно с помощью [событий](api/community-events/json-schema) `market_order_new` и `market_order_edit` по  [Callback API](api/callback/getting-started) или [Bots Longpoll API](api/bots-long-poll/getting-started).

Также API позволяет управлять статусами заказов. Например, обновлять их, когда заказы собраны, переданы в доставку или завершены. Для этого используется метод [`market.editOrder`](method/market.editOrder).

### Другие действия

* [`market.edit`](market.edit) — редактирование информации о товаре;
* [`market.delete`](market.delete) — удаление товара;
* [`market.addToAlbum`](market.addToAlbum) — добавление товара в одну или несколько подборок;
* [`market.get`](market.get) — получение списка товаров из сообщества;
* [`market.getById`](market.getById) — получение товара по его идентификатору;
* [`market.search`](market.search) — поиск товаров в сообществе;
* [`market.getComments`](market.getComments) — получение списка комментариев к товару;
* [`market.createComment`](market.createComment) — добавление комментария к товару;
* [`market.deleteComment`](market.deleteComment) — удаление комментария к товару;
* [`market.reorderItems`](market.reorderItems) — сортировка товаров в подборке;
* [`market.getAlbums`](market.getAlbums) — получение списка подборок из сообщества;
* [`market.getAlbumById`](market.getAlbumById) — получение подборки по ее идентификатору;
* [`market.editAlbum`](market.editAlbum) — редактирование подборки товаров;
* [`market.addAlbum`](market.addAlbum) — добавление подборки товаров.

## Загрузка изображений

### Загрузка основного изображения для товара

Допустимые форматы: JPG, PNG, GIF.
Ограничения: минимальный размер фото — 400x400px, сумма высоты и ширины не более 14000px, файл объемом не более 50 МБ.
Поле `POST`-запроса: `file`.

#### Получение адреса

Вызовите метод  с параметром `main_photo` = `1`, чтобы получить адрес для загрузки фото. 

#### Передача файла

Передайте файл на адрес `upload_url`, полученный в предыдущем пункте, сформировав `POST`-запрос с полем `file`. Это поле должно содержать изображение в формате `multipart/form-data`.

После успешной загрузки сервер возвращает в ответе JSON-объект с полями `server`, `photo`, `hash`, `crop_data`, `crop_hash`:

```json
{
"server":625831,
"photo":"[{\"photo\":\"8d81799f90:w\",\"sizes\":[[\"s\",\"625831075\",\"45839\",\"-5fbUeQq1YY\",75,56],[\"m\",\"625831075\",\"4583a\",\"G8yAYbsk7M4\",130,97]]}]",
"hash":"8954a4da5ba06d4e",
"crop_data":"oAAmMpwAAAAAlTWyjA",
"crop_hash":"729155760247b391134"
}
```

Поле `server`  содержит числовое значение, в `hash`, `crop_data` и `crop_hash` возвращаются строки, а в поле `photo` находится JSON-объект, структуру которого важно сохранить в исходном виде (убрав, однако, экранирование символов перед дальнейшим использованием). В PHP вы можете использовать `json_decode()` для всего ответа и затем `stripslashes()` для объекта `photo`.

#### Сохранение результата

Чтобы сохранить фотографию, вызовите метод  с параметрами `server`, `photo`, `crop_data`, `crop_hash`, полученными на предыдущем этапе.

После успешной загрузки фотографии вы можете прикрепить ее к товару, используя методы [`market.add`](method/market.add) или [`market.edit`](method/market.edit) и указав идентификатор фотографии в параметре `main_photo_id`.

### Загрузка дополнительных изображений

Допустимые форматы: JPG, PNG, GIF.
Ограничения: минимальный размер фото — 400x400px, сумма высоты и ширины не более 14000px, файл объемом не более 50 МБ.
Поле `POST`-запроса: `file`.

#### Получение адреса

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

#### Передача файла

Передайте файл на адрес `upload_url`, полученный в предыдущем пункте, сформировав `POST`-запрос с полем `file`. Это поле должно содержать изображение в формате `multipart/form-data`.

После успешной загрузки сервер возвращает в ответе JSON-объект с полями `server`, `photo`, `hash`:

```json
{
"server":625831,
"photo":"[{\"photo\":\"8d81799f90:w\",\"sizes\":[[\"s\",\"625831075\",\"45839\",\"-5fbUeQq1YY\",75,56],[\"m\",\"625831075\",\"4583a\",\"G8yAYbsk7M4\",130,97]]}]",
"hash":"8954a4da5ba06d4e",
}
```

Поле `server`  содержит числовое значение, в `hash`, а в поле `photo` находится JSON-объект, структуру которого важно сохранить в исходном виде (убрав, однако, экранирование символов перед дальнейшим использованием). В PHP вы можете использовать `json_decode()` для всего ответа и затем `stripslashes()` для объекта `photo`.

#### Сохранение результата

Чтобы сохранить фотографию, вызовите метод  с параметрами `server` и `photo`, полученными на предыдущем этапе.

После успешной загрузки фотографии вы можете прикрепить ее к товару, используя методы [`market.add`](method/market.add) или [`market.edit`](method/market.edit) и указав идентификатор фотографии в параметре `photo_ids`.

### Загрузка фотографии для подборки товаров

Допустимые форматы: JPG, PNG, GIF.
Ограничения: минимальный размер фото — 1280x720px, сумма высоты и ширины не более 14000px, файл объемом не более 50 МБ.
Название поля POST-запроса: `file`.

#### Получение адреса

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

#### Передача файла

Передайте файл на адрес `upload_url`, полученный в предыдущем пункте, сформировав `POST`-запрос с полем `file`. Это поле должно содержать изображение в формате `multipart/form-data`.

После успешной загрузки сервер возвращает в ответе JSON-объект с полями `server`, `photo`, `gid`, `hash`

```json
{
"server":999,
"photo":"eyJwaG90byI6IntcInBob",
"gid":102416739,
"hash":"0adc3bd6509fdcf97052b0594c4063ff"
}
```

Поля `server` и `gid` содержат числовые значения, а в полях `photo` и `hash` возвращаются строки.

### Сохранение результата

Чтобы сохранить фотографию, вызовите метод  с параметрами `server`, `photo`, `hash`, полученными на предыдущем этапе.

После успешной загрузки фотографии вы можете прикрепить ее к подборке товаров, используя методы [`market.addAlbum`](method/market.addAlbum) или [`market.editAlbum`](method/market.editAlbum) и указав идентификатор фотографии в параметре `photo_id`.

## Готовые инструменты

Популярные платформы интернет-магазинов предлагают готовые решения для интеграции с сервисом товаров ВКонтакте:

### Конструкторы интернет магазинов  

*  [InSales](https://www.insales.ru/collection/integratsiya-s-vkontakte/product/nastroyka-vygruzki-tovarov-iz-insales-vo-vkontkakte)
*  [AdvantShop](https://www.advantshop.net/help/pages/module-vkmarket)
*  [Эквид](https://www.ecwid.ru/blog/ecwid-with-vkmarket.html)
*  [Tilda](https://help-ru.tilda.cc/online-store-payments/vk)
*  [Setup.ru](https://www.setup.ru/instructions/vk)
*  [OpenCart](https://github.com/crmagent-developers/opencart-vk-module)
*  [WordPress](https://github.com/crmagent-developers/woocommerce-vk-module)
*  [Woocommerce](https://wordpress.org/plugins/vkmarket-for-woocommerce/)

### CRM системы  

* [RetailCRM](https://vk.cc/bVtnwH)
* [1C:CRM](https://1crm.ru/help/integratsiya-s-magazinom-vkontakte/)
* [Бизнес.Ру](https://vk.com/@ecom-integraciya-magazina-vkontakte-i-biznesru)

### Программы складского учёта  

*  [МойСклад](https://support.moysklad.ru/hc/ru/articles/226865387)

### Прочее  

*  October CMS — плагин [Shopaholic for VK Goods](https://octobercms.com/plugin/lovata-vkgoodsshopaholic)
*  [Workzen](https://workzen.mts.ru/help/vk)
*  [ZoomKit](https://vkm.zoomkit.ru) — загрузка товаров в vk.com через фиды данных Яндекс.Маркета, Яндекс.Недвижимости и Auto.ru
*  [Cloudparser](https://cloudparser.ru) — выгрузка товаров с сайтов поставщиков
* [iBurattino](http://iburattino.com), [VK-Sync](http://vk-sync.ru), [Soc-commerce](http://soc-commerce.com), [vkExport](https://vkexport.net/) — YML
*  [1С-Битрикс](https://marketplace.1c-bitrix.ru/solutions/vkapi.vkmarket/), [https://marketplace.1c-bitrix.ru/solutions/bxmaker.vk/](https://marketplace.1c-bitrix.ru/solutions/bxmaker.vk/)
*  [Электронный Заказ](https://ez-catalog.ru/) — электронный заказ, импорт товаров из XML, YML, CSV
*  [Trimpo](https://trimpo.org/) — импорт из YML, Excel, ручное добавление товаров
*  CMS ShopScript — [vkgoods](https://www.webasyst.ru/store/plugin/shop/vkgoods/)
*  [Sliza](https://sliza.ru/pages/instruction)
*  [Выгрузка товаров ВКонтакте и Одноклассники](https://my-market-app.ru/)

API ВКонтакте | Товары | API для товаров

# Товары ВКонтакте

**Товары ВКонтакте** – это витрина с товарами и услугами в вашем сообществе ВКонтакте. 

![title=Блок с товарами на главной странице сообщества](11022d528d5d387fbb61f51e4b046d5e0d78379a23f968b0861afd1d "-5203208861033356884")

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

## Как это работает?

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

![title=В разделе с товарами доступен поиск по наименованию и цене](2cc1ea6be1122788c3e90128a73878337ddd05d50a8fcb2ec055c406 "2682289002888373244")

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

![title=Карточка товара – сюда можно добавить любую информацию, полезную для покупателя](b386c4e88a09935cb2b07d43dfdcc36b04ad0e3353da8b99f177dbf1 "-637134464653778470")

Кнопка **Написать продавцу** в карточке товара откроет переписку с сообществом или выбранным руководителем сообщества. К сообщению будет прикреплена ссылка на товар, который заинтересовал пользователя. 

В настройках сервиса (раздел **Управление сообществом** → **Товары**) вы можете задать валюту магазина, регионы доставки, контактное лицо. Заполните вики-страницу **Описание магазина** – здесь пользователи смогут прочитать об условиях оплаты и доставки перед покупкой. 

Выбор способа оплаты и доставки заказов остается за вами. 

## Доставка

Теперь доставлять товары через Boxberry и СДЭК можно прямо из Магазина ВКонтакте. Это удобное решение для бизнеса и клиентов, которое поможет продавать быстрее и больше. 

![](d84302030ec7bf82e0824216cd40405b0f35762c05c8fbd7f123eeb8 "-536902625946196038")

### Подключите доставку

Вначале убедитесь, что у вас включён Магазин 2.0 в настройках сообщества. 

Нажмите **Управление** → **Настройки** → **Разделы**. Включите раздел **Товары**. Для работы с доставкой должен быть выбран **Расширенный** режим. 

![](d2b5b34c5da9100bff19aec8d49be18a7d99ded64798fe42c557a02e "8014173844027144298")

Нажмите **Показать настройки** → **Доставка**. Также перейти в настройки магазина можно через главную страницу сообщества. 

![](7a6b0cd237030915c8546f4023ef9e4f75796655401306a5c23a113c "7767136780412586436")

Нажмите **Включить** для Boxberry и СДЭК. 

![](39a7f82a6cf220740f1e7d3b86b4a387e7bc86579d064c6207bc7827 "-4074010642457854577")

Для СДЭК и Boxberry стоимость доставки рассчитывается по габаритам и весу товара. Указать эти параметры вы можете заранее в карточке товара – тогда прогноз для покупателя будет точным. Вес и габариты также можно прописать на этапе получения заказа. 

## Укажите свойства товаров

Помимо веса и габаритов товара вы можете указать его дополнительные свойства: цвет, материал, размер и другие. 

![](75cafdffa3a261a3af5ebdb6788b3c3a0e9c6f0168e611b45a0802c2 "-4967459588447635267")

## Проверьте поступивший заказ

Внимательно проверьте все данные. При необходимости вы можете отредактировать здесь вес и габариты заказа, если не указали их ранее, —стоимость доставки рассчитается автоматически. 

Из этого же окна вы можете связаться с покупателем и уточнить детали заказа. 

![](7dd640fdd996ee64368dd36520497c5f916cda6c226e47d2a1e03d9d "-6931970821843698708")

Включите сообщения сообщества, чтобы отвечать покупателям. Написать от лица сообщества можно сразу после того, как поступил заказ. 

## Договоритесь об оплате

В сообщениях сообщества договоритесь с покупателем о способе оплаты. Вы можете предложить перевести деньги через денежные переводы ВКонтакте: тогда клиенту не придётся вводить данные вашей карты – вы сами выберете, куда зачислить средства. 

>  **Важно.** Доставку оплачивает покупатель. Она уже будет включена в стоимость заказа, если вы указали габариты и вес товара. Если вы не вносили эти данные, то клиент увидит сообщение **Стоимость уточняйте у продавца**. 

Отправка через СДЭК рассчитывается по тарифу **Экспресс-лайт**, подробности описаны по [ссылке](https://cdek.ru/express-light). Стоимость доставки Boxberry рассчитывается по специальному тарифу для магазинов ВКонтакте. 

## Отправьте заказ

Получив заказ, в котором указан способ доставки через СДЭК или Boxberry, нужно убедиться, что рассчитана стоимость. 

Если вы заранее прописали габариты товара – заказ поступит к вам уже с фиксированной стоимостью доставки. 

Если ещё не сделали этого – перейдите в карточку заказа и укажите габариты и вес в специальном поле, и мы автоматически всё подсчитаем. 

Что делать дальше:

*  Принять у покупателя оплату удобным ему способом. 
*  Отвезти заказ в ближайшее отделение выбранной службы или вызвать курьера, который заберёт от вас посылку. 
*  Сервис доставки закрепит за вашим отправлением трек-номер и сразу сообщит его вам. 

Найти ближайшее отделение можно здесь: [Boxberry](https://boxberry.ru/find_an_office/) и [СДЭК](https://cdek.ru/offices). Обе компании работают с физическими и юридическими лицами. 

## Добавьте трек-номер

Впишите трек-номер в соответствующее поле. Так пользователю будет проще отслеживать посылку на сайте доставки – будет достаточно одного клика из раздела **Заказы**. 

![](a5b0a5d31fbae44ec0aedc30e75625128639282b0279dc8529c5ffd8 "1565333712537667774")

> **Важно.** Не забудьте при отправке сменить статус заказа на **Доставляется**: тогда пользователь сразу получит уведомление о том, что товар в пути. 

![](55f4339a699abb4df078b1f3293c5fc25900ecae0c844aac4b617bd0 "5578399229701508714")

## API для товаров

API позволяет автоматизировать работу с товарами и заказами. Используйте готовое решение для импорта товаров из внешней базы или создайте собственный инструмент – это просто. 

> Подробнее о методах API ВКонтакте для работы с товарами в сообществах мы рассказали в разделе [API для товаров](api/market/getting-started).

## Готовые инструменты

Используйте готовые решения, созданные нашими партнерами, для быстрого импорта товаров из вашего магазина в сообщество ВКонтакте:

###  Конструкторы интернет магазинов

*  InSales – [https://www.insales.ru/collection/integratsiya-s-vkontakte/product/nastroyka-vygruzki-tovarov-iz-insales-vo-vkontkakte](https://www.insales.ru/collection/integratsiya-s-vkontakte/product/nastroyka-vygruzki-tovarov-iz-insales-vo-vkontkakte)
*  AdvantShop – [https://www.advantshop.net/help/pages/module-vkmarket](https://www.advantshop.net/help/pages/module-vkmarket)
*  Эквид – [https://www.ecwid.ru/blog/ecwid-with-vkmarket.html](https://www.ecwid.ru/blog/ecwid-with-vkmarket.html)
*  Tilda – [https://help-ru.tilda.cc/online-store-payments/vk](https://help-ru.tilda.cc/online-store-payments/vk)
*  Setup.ru – [https://www.setup.ru/instructions/vk](https://www.setup.ru/instructions/vk)
*  OpenCart – [https://github.com/crmagent-developers/opencart-vk-module](https://github.com/crmagent-developers/opencart-vk-module)
*  WordPress – [https://github.com/crmagent-developers/woocommerce-vk-module](https://github.com/crmagent-developers/woocommerce-vk-module)
*  Nethouse – [https://vk.nethouse.ru/](https://vk.nethouse.ru/)

###  CRM системы

*  RetailCRM – [https://vk.cc/bVtnwH](https://vk.cc/bVtnwH)
*  1C-CRM – [https://1crm.ru/help/integratsiya-s-magazinom-vkontakte/](https://1crm.ru/help/integratsiya-s-magazinom-vkontakte/)
*  amoCRM – [https://cmdf5.ru/widjety-amocrm/vk-amocrm](https://cmdf5.ru/widjety-amocrm/vk-amocrm)
*  Битрикс 24 – [https://www.bitrix24.ru/apps/?app=integrations24.vkmarket](https://www.bitrix24.ru/apps/?app=integrations24.vkmarket&_ga=2.210223517.984684472.1635850697-325262892.1635850697&)
*  1С-Битрикс – [https://marketplace.1c-bitrix.ru/solutions/vkapi.market](https://marketplace.1c-bitrix.ru/solutions/vkapi.market)

###  Программы складского учёта

*  МойСклад – [https://support.moysklad.ru/hc/ru/articles/226865387](https://support.moysklad.ru/hc/ru/articles/226865387)
*  Бизнес.Ру – [https://vk.com/@ecom-integraciya-magazina-vkontakte-i-biznesru](https://vk.com/@ecom-integraciya-magazina-vkontakte-i-biznesru)

###  Прочее

*  October CMS – плагин [Shopaholic for VK Goods](https://octobercms.com/plugin/lovata-vkgoodsshopaholic)
*  Workzen – [https://workzen.mts.ru/help/vk](https://workzen.mts.ru/help/vk)
*  Загрузка товаров в vk.com через фиды данных Яндекс.Маркета, Яндекс.Недвижимости и Auto.ru – [ZoomKit](https://vkm.zoomkit.ru)
*  Выгрузка товаров с сайтов поставщиков – [Cloudparser](https://cloudparser.ru)
*  Soc-commerce – [https://soc-commerce.com/](https://soc-commerce.com/)
*  Albato – [https://albato.ru/app-vkmarket](https://albato.ru/app-vkmarket)
* [iBurattino](http://iburattino.com), [VK-Sync](http://vk-sync.ru), [Soc-commerce](http://soc-commerce.com), [vkExport](https://vkexport.net/) — YML
*  [1С-Битрикс](https://marketplace.1c-bitrix.ru/solutions/vkapi.vkmarket/), [https://marketplace.1c-bitrix.ru/solutions/bxmaker.vk/](https://marketplace.1c-bitrix.ru/solutions/bxmaker.vk/)
*  [Электронный Заказ](https://ez-catalog.ru/) — электронный заказ, импорт товаров из XML, YML, CSV
*  [Trimpo](https://trimpo.org/) — импорт из YML, Excel, ручное добавление товаров
*  CMS ShopScript — [vkgoods](https://www.webasyst.ru/store/plugin/shop/vkgoods/)
*  [Sliza](https://sliza.ru/pages/instruction)
*  [Выгрузка товаров ВКонтакте и Одноклассники](https://my-market-app.ru/)

API ВКонтакте | Товары | Товары ВКонтакте

# Диалог авторизации OAuth

Для того, чтобы авторизовать пользователя, необходимо перенаправить его браузер по адресу [`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный параметр**) — Идентификатор вашего приложения.  
* `redirect_uri` (**обязательный параметр**) — Адрес, на который будет переадресован пользователь после прохождения авторизации (домен указанного адреса должен соответствовать основному домену в настройках приложения).
* `display` (**обязательный параметр**) — Указывает тип отображения страницы авторизации. Поддерживаются следующие варианты:
    *  `page` — форма авторизации в отдельном окне;
    *  `popup` — всплывающее окно;
    *  `mobile` — авторизация для мобильных устройств (без использования Javascript).
    Если пользователь авторизуется с мобильного устройства, будет использован тип  `mobile`.  
* `scope` — Битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации пользователя и запросить, в случае отсутствия необходимых.  
* `response_type` —Тип ответа, который вы хотите получить:
    *  `code` —  если вы хотите делать запросы со стороннего сервера (по умолчанию);
    *  `token` — если вы хотите делать запросы с клиента.

#### Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&redirect_uri=http://example.com/callback&scope=12&display=mobile
```
> **Примечание.** Если вы разрабатываете Standalone-приложение в параметре `response_type` передаете `token`, то в качестве параметра  `redirect_uri` необходимо указывать адрес [https://oauth.vk.com/blank.html](https://oauth.vk.com/blank.html), на который будут переданы данные авторизации. Обратите внимание, что только в данном случае у вас будет возможность использовать расширенные методы работы с API.

Использование API | Диалог авторизации OAuth

Интеграция | Сообщества и пользователи | Open API

# Быстрый старт

**Платёжный API** — это API для работы с платёжной системой в играх и мини-приложениях. Он нужен, чтобы продавать в приложении виртуальные товары или услуги. 

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

![title=Диалоговое окно платежа в приложении.](6bdd0b4f3e1eb1e9b339105672c7472128d9b3aa284d76f8c3c9799b "-708128452752560712")

В этом руководстве мы расскажем, как подключить платёжную систему в вашем приложении ВКонтакте.

## Платежи ВКонтакте

> Для платежей за товары и услуги используйте [VK Pay](pay/getting-started).

Подойдёт для платежей в чат-ботах, сообществах ВКонтакте, сервисах VK Mini Apps и на сторонних сайтах. Оплата происходит с баланса VK Pay или привязанных к нему банковских карт.

> Для платежей в играх и мини-приложениях используйте голоса.

Голоса — универсальная платёжная единица ВКонтакте, которая используется для оплаты виртуальных товаров. Пользователи могут пополнить свой виртуальный счёт голосами с помощью банковских карт, электронных кошельков, СМС и другими способами. 

Пользователь оплачивает покупки в игре или мини-приложении внутренней валютой ВКонтакте (голосами) следующим образом:
1. Пользователь выбирает виртуальный товар в приложении.
2. С его личного баланса списывается число голосов, равное стоимости покупки.
3. Счёт приложения пополняется на стоимость покупки.

## Подготовка серверной части 

В первую очередь нужно реализовать на вашем сервере скрипт для [обработки уведомлений от платёжной системы ВКонтакте](api/payments/notifications/overview). Такое уведомление представляет собой `POST`-запрос с заданной структурой данных. Ваш сервер должен уметь своевременно отправлять ответ с запрошенной информацией. Например, это могут быть данные о товаре, который хочет купить пользователь в вашем приложении.

## Настройки платежей в приложении 

Откройте страницу редактирования вашего приложения и перейдите на вкладку **Платежи**. Здесь нужно указать адрес обратного вызова (URL на вашем сервере, где размещён скрипт обработки уведомлений). Чтобы проводить оплату в [тестовом режиме](#Тестовый%20режим), в поле **Тестировщики платежей** выберите пользователей, которые будут тестировать платёжную систему.

Пока приложение не прошло модерацию, в нём доступны только тестовые платежи.

## Вызов диалогового окна 

Пользователь выбирает виртуальный товар или подписку в приложении, после этого открывается диалоговое окно ВКонтакте с описанием и стоимостью. Можно подтвердить покупку или отменить её. Если на балансе недостаточно голосов, будет предложено пополнить его одним из доступных способов.

![title=Диалоговое окно платежа в приложении;](d1be181ea82a0a515a5476d52cb862a79143548e587b81e2a0db94cb "-2162674972032947764")

Чтобы показать диалоговое окно, используйте метод [`showOrderBox`](sdk/javascript#showOrderBox) или [`showSubscriptionBox`](sdk/javascript#showSubscriptionBox) из Client API. 

Типовой JS-код для открытия окна:

```JavaScript
function order() {
    const params = {
        type: 'item',
        item: 'item_25new'
    };

   VK.callMethod('showOrderBox', params);
}
```

После успешной оплаты товара приложению будет отправлено событие `onOrderSuccess` с идентификатором заказа. 

**Внимание!** Это событие нельзя использовать для принятия решения о предоставлении пользователю виртуального товара. Проверяйте специальное уведомление [`order_status_change`](api/payments/notifications/order-status-change), которое отправляется на ваш сервер.

### Диалоговое окно платежа

Этот диалог показывается пользователю после выбора виртуального товара на странице приложения.

![title=Диалоговое окно платежа в приложении.](d1be181ea82a0a515a5476d52cb862a79143548e587b81e2a0db94cb "-2162674972032947764")

#### Параметры `showOrderBox`

Чтобы показать диалоговое окно платежа, используйте метод [`showOrderBox`](sdk/javascript#showOrderBox) из Client API. Он принимает следующие параметры:

### `type` 

`string`

 Тип заказа. Возможные значения: 
  `votes` — окно для ввода голосов на счёт приложения; 
  `offers` — окно со списком специальных предложений (офферов), которые могут быть использованы пользователем для получения голосов; 
  `item` — покупка товара. 

### `votes` 

`integer`

Количество голосов для ввода на счёт приложения (для `type = votes`). 

### `offer_id` 

`integer`

Идентификатор рекламной акции (для `type = offers`). 

### `currency` 

`integer`, [`0`,`1`]

`1` — стоимость специальных предложений будет отображена в [валюте приложения](#Платежи%20в%20валюте%20приложения) (для `type = offers`). 

### `item` 

`string`

Наименование товара, которое будет отправлено в уведомлении `get_item` (для `type = item`). Строка длиной до 64 символов. Например, `item_25new`.   

#### События

После завершения оплаты в зависимости от результата в обработчик отправляется одно из трёх событий:

 | Название | Параметры | Описание |
|---|---|---|
 | `onOrderCancel` | — | Пользователь отменил покупку. |
 | `onOrderSuccess` | `orderId` (`integer`) | Покупка закончилась успешно. 
 `orderId` — идентификатор заказа. Подробную информацию об обработке платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview). |
 | `onOrderFail` | `errorCode`  (`integer`)| Покупка закончилась неуспешно. 
 `errorCode` — код ошибки. Подробную информацию об ошибках платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview#Формат%20ответа%20в%20случае%20ошибки). |

#### Пример кода на JavaScript 

```JavaScript
<script type="text/javascript">

// Функция order() отображает окно для покупки товара с наименованием "item_25new". 
// Названия платёжных событий пишутся в контейнер с id="callbacks".

  function order() {
    var params = {
      type: 'item',
      item: 'item_25new'
    };
    VK.callMethod('showOrderBox', params);
  }

  var callbacksResults = document.getElementById('callbacks');

  VK.addCallback('onOrderSuccess', function(order_id) {
    callbacksResults.innerHTML += '<br />onOrderSuccess '+order_id;
  });
  VK.addCallback('onOrderFail', function() {
    callbacksResults.innerHTML += '<br />onOrderFail';
  });
  VK.addCallback('onOrderCancel', function() {
    callbacksResults.innerHTML += '<br />onOrderCancel';
  });
</script>
```

### Диалоговое окно подписки

#### Параметры `showSubscriptionBox`

Чтобы показать диалоговое окно подписки, нужно вызвать метод [`showSubscriptionBox`](sdk/javascript#showSubscriptionBox) из Client API. Вторым аргументом передайте `action` — действие, которое необходимо совершить. Возможные значения:
* `create` — приобрести подписку;
* `resume` — возобновить подписку;
* `cancel` — отменить подписку.

Метод `showSubscriptionBox` принимает следующие параметры:

### `item` 

`string`

Наименование подписки, которое будет отправлено в уведомлении [`get_subscription`](api/payments/notifications/get-subscription). Строка длиной до 64 символов. Например: `subscription_25new` (для `action = create`). 

### `subscription_id` 

`integer`

Идентификатор подписки (для `action = resume, cancel`). 

#### События

После завершения оплаты в зависимости от результата в обработчик отправляется одно из трёх событий:

 | Название | Параметры | Описание |
|---|---|---|
 | `onSubscriptionCancel` | — | Пользователь отменил покупку. |
 | `onSubscriptionSuccess` | `subscription_id` (`integer`) | Покупка закончилась успешно. 
`subscription_id` — идентификатор подписки. Подробную информацию об обработке платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview). |
 | `onSubscriptionFail` | `errorCode` (`integer`)| Покупка закончилась неуспешно. 
 `errorCode` — код ошибки. Подробную информацию об ошибках платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview#Формат%20ответа%20в%20случае%20ошибки). |

> Обратите внимание — в тестовом режиме подписка 5 раз автоматически продлевается раз в 10 минут (для `period = month`) и раз в 2 минуты для других значений `period`. После этого подписка автоматически отменяется.

#### Пример кода на JavaScript

```JavaScript
<script type="text/javascript">
  function order() {
    VK.callMethod('showSubscriptionBox', 'create', {item: 'subscription1'});
  }

  var callbacksResults = document.getElementById('callbacks');

  VK.addCallback('onSubscriptionSuccess', function(subscription_id) {
    callbacksResults.innerHTML += '<br />onSubscriptionSuccess '+subscription_id;
  });
  VK.addCallback('onSubscriptionFail', function() {
    callbacksResults.innerHTML += '<br />onSubscriptionFail';
  });
  VK.addCallback('onSubscriptionCancel', function() {
    callbacksResults.innerHTML += '<br />onSubscriptionCancel';
  });
</script>
```

Функция `order` позволяет отобразить пользователю окно для покупки товара с наименованием `'subscription_25new'`. Названия произошедших платёжных событий пишутся в контейнер с `id="callbacks"`.

## Тестовый режим

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

Тестовый режим необходимо использовать пока ваше приложение не прошло проверку администрацией ВКонтакте. Платежи осуществляются в «боевом» режиме сразу после прохождения процедуры проверки приложения.

Для осуществления платежей в тестовом режиме необходимо добавить всех пользователей, совершающих тестовые платежи, в специальный список в настройках приложения (поле **Тестировщики платежей**).

![](33327db1023a46d0548612a270d8330ee0e7e4678ca689697daefe49 "4424661819184374092")

В тестовом режиме к параметру `notification_type` добавляется суффикс `'_test'`. Таким образом, уведомления будут называться `'get_item_test'`, `'order_status_change_test'`, `'get_subscription_test'`, `'subscription_status_change '` соответственно (см. [Платёжные уведомления](api/payments/notifications/overview)).

При этом идентификаторы заказов в тестовом режиме – параметры `order_id` у уведомлений – могут пересекаться с идентификаторами заказов в рабочем режиме.

Обратите внимание — в тестовом режиме подписка 5 раз автоматически продлевается раз в 10 минут (для `period = month`) и раз в 2 минуты для других значений `period`. После этого подписка автоматически отменяется. Уведомления приходят только при изменении статуса подписки, в случае продления уведомления не приходят. Подробнее см. [Изменение статуса подписки](api/payments/notifications/subscription-status-change).

## Модерация приложения 

Если ваше приложение ещё не отправлялось на проверку и не размещено в общем каталоге, самое время сделать это. Иначе пользователи не смогут оплатить что-либо в нём.
После проверки вы можете убрать себя из списка тестировщиков платежей в настройках приложения, чтобы начать осуществлять платежи в боевом режиме.

Чтобы приложение успешно прошло модерацию, убедитесь, что оно соответствует Правилам.

## Методы `orders` 

Метод API [`orders.get`](method/orders.get) позволяет получить список заказов с их текущими статусами. 
Чтобы отменить заказ, используйте метод [`orders.changeState`](method/orders.changeState), передав идентификатор заказа и новый статус заказа `refund`. Голоса вернутся на баланс пользователя. На балансе приложения должно быть достаточно голосов для возврата. Весь список методов секции `orders` можно посмотреть [здесь](method/orders).

Интеграция | Платежи | Платёжный API | Быстрый старт

# Получение информации о товаре

Это уведомление отправляется при открытии [диалогового окна покупки товара](api/payments/getting-started#Диалоговое%20окно%20платежа) через приложение. Полученная информация о товаре затем отображается в диалоговом окне покупки. 

## Параметры уведомления

 | **Имя** | **Тип** | **Примечание** |
|---|---|---|
 | `notification_type` | `string` | Равен `"get_item"`.  |
 | `app_id` | `int` | Идентификатор приложения. |
 | `user_id` | `int` | Идентификатор пользователя, создавшего заказ. |
 | `receiver_id` | `int` | Идентификатор получателя заказа (в данный момент совпадает с `user_id`, но в будущем может отличаться). |
 | `order_id` | `int` | Идентификатор заказа в системе платежей ВКонтакте. |
 | `lang` | `string` | Язык пользователя в формате «язык_страна». На данный момент поддерживается 4 языка: `ru_RU` - русский, `uk_UA` - украинский, `be_BY` - белорусский, `en_US` - английский. |
 | `item` | `string`  | Наименование товара, переданное диалоговому окну покупки (см. [Параметры диалогового окна платежей](api/payments/getting-started#Диалоговое%20окно%20платежа)). |
 | `sig` | `string` | Подпись уведомления (см. [Проверка подписи уведомления](api/payments/notifications/overview#Проверка%20подписи)). |

## Параметры ответа

По полученному в уведомлении наименованию товара `item` разработчик должен вернуть актуальную информацию о нём. При отсутствии товара необходимо выдать в ответе ошибку 20, «Товара не существует» (см. [Коды ошибок](api/payments/notifications/overview#Формат%20ответа%20в%20случае%20ошибки)). 
> **Внимание!** Так как `item` передаётся на клиентской стороне, этот параметр может быть изменён пользователем. 

 | **Название параметра** | **Тип** |   **Описание** |
|---|---|---|
 | `title` (обязательный) | `string`  | Название товара, до 48 символов |
 | `photo_url` | `string` |  URL изображения товара на сервере разработчика. Рекомендуемый размер изображения – 75х75px. |
 | `price` (обязательный)| `int` | Стоимость товара в голосах |
 | `discount` | `int` | Размер скидки на товар в голосах. Должно быть в пределах от 1 до 1000 голосов и меньше, чем стоимость товара `price`. |
 | `item_id` | `string` | Идентификатор товара в приложении |
 | `expiration` | `int` | Разрешает кэширование товара на `{expiration}` секунд. Допустимый диапазон от 600 до 604800 секунд. **Важно!** При отсутствии параметра возможно кэширование товара на 3600 секунд при большом количестве подряд одинаковых ответов. Для отмены кэширования необходимо передать `0` в качестве значения параметра.  |

Если `expiration = 0` или не определён, то для товара с одним идентификатором `item` допускается возвращать различные названия, изображения и цены. 

> **Важно!** Рекомендуется всегда использовать кэширование товаров, чтобы пользователи не ожидали получения информации о них, и уменьшить количество обращений к серверу приложения. 
> 
> В случае, если информация о товаре с идентификатором `item` была закэширована на время `expiration`, то последующие запросы для данного товара не будут выполняться в течение заданного времени. 

## Пример ответа

```JSON
{
  "response": {
        "title":"300 золотых монет", 
        "photo_url":"http://somesite.ru/images/coins.jpg", 
        "price": 10
    }
}

```

Интеграция | Платежи | Платёжный API | Платёжные уведомления | Получение информации о товаре

# Получение информации о подписке

Это уведомление отправляется при открытии [диалогового окна подписки](api/payments/getting-started#Диалоговое%20окно%20подписки) через приложение. 

## Параметры уведомления

| Название параметра | Примечение |
 |---|---|
 | `app_id` `integer` | Идентификатор приложения. |
 | `item` `string` | Наименование товара, переданное [диалоговому окну подписки](api/payments/getting-started#Диалоговое%20окно%20подписки). |
 | `lang` `string` | Язык пользователя в формате `язык_страна`. Сейчас поддерживается 4 языка: `ru_RU` — русский, `uk_UA` — украинский, `be_BY` — белорусский, `en_US` — английский. |
 | `notification_type` `string` | Тип уведомления. Равен `get_subscription` или `get_subscription_test`. |
 | `order_id` `integer` | Идентификатор заказа в системе платежей ВКонтакте. |
 | `receiver_id` `integer` | Идентификатор получателя заказа (совпадает с `user_id`, но в будущем может отличаться). |
 | `user_id` `integer` | Идентификатор пользователя, создавшего заказ. |
 | `sig` `string` | Подпись уведомления (см. [Проверка подписи](api/payments/notifications/overview#Проверка%20подписи)). |

## Параметры ответа

По полученному в уведомлении наименованию товара `item` разработчик должен вернуть актуальную информацию о нём. При отсутствии товара необходимо выдать в ответе ошибку 20, «Подписки не существует». 

> **Внимание!** Так как `item` передаётся на клиентской стороне, этот параметр может быть изменён пользователем. 

| Название параметра | Примечение |
 |---|---|
 | `item_id` `integer` | Идентификатор товара в приложении. |
 |`title` `string`, обязательный | Название подписки. |
 | `description` `string` | Описание подписки.  |
 | `photo_url` `string` | URL изображения для подписки на сервере разработчика.  |
 | `price` `integer` | Стоимость подписки в голосах. |
 | `period` `integer` | Период действия подписки. Возможные значения: `7` — 7 дней, `30` — 30 дней, `90` — 90 дней. |
 |`trial_duration` `integer` | Длительность триал-периода. Возможные значения: `3` — 3 дня, `7` — 7 дней, `30` — 30 дней. |
 |`expiration` `integer` | Разрешает кэширование товара на `{expiration}` секунд. Допустимый диапазон от 600 до 604800 секунд. **Важно!** При отсутствии параметра возможно кэширование товара на 3600 секунд при большом количестве подряд одинаковых ответов. Для отмены кэширования необходимо передать `0` в качестве значения параметра. |

Если `expiration = 0` или не определён, то для подписки с одним идентификатором `item` допускается возвращать различные названия, изображения и цены. 

> **Внимание!** Рекомендуется всегда использовать кэширование, чтобы пользователи не ожидали получения информации, и чтобы уменьшить количество обращений к серверу приложения. 

## Пример ответа

```JSON
{
    "response": {
        "item_id":50,
        "title":"VIP Status",
        "photo_url":"http:\/\/vk.com\/images\/gift\/90\/96.jpg",
        "price":1,
        "period":7,
        "trial_duration":7,
        "expiration":600
    }
}

```

Интеграция | Платежи | Платёжный API | Получение информации о подписке

# Изменение статуса заказа

Присылается в момент изменения статуса заказа. 

> **Важно!** В случае получения повторного уведомления типа **Изменения статуса заказа** (с тем же `order_id`) ответ должен в точности повторять ответ для исходного уведомления. 

Например, если было отправлено это уведомление, и был получен положительный ответ, но он не дошел до сервера ВКонтакте, или по каким-то временным причинам не удалось перевести заблокированные средства на счет приложения сразу после получения ответа, такое же уведомление будет отправлено повторно. При этом не нужно выполнять новый заказ, достаточно просто прислать тот же ответ, что и в предыдущий раз (сохранив у себя `order_id` и проверив по нему, что такое уведомление уже приходило). 

## Параметры уведомления

 | Название параметра | Примечение |
 | --- | --- |
 | `notification_type` `string` |  Тип уведомления. Равен `order_status_change` или `order_status_change_test`. |
 | `app_id` `integer` | Идентификатор приложения. |
 | `user_id` `integer` | Идентификатор пользователя, сделавшего заказ |
 | `receiver_id` `integer` | Идентификатор получателя заказа (в данный момент совпадает с `user_id`, но в будущем может отличаться). |
 | `order_id` `integer` | Идентификатор заказа в системе платежей ВКонтакте |
 | `date` `integer` | Дата создания заказа (в формате `Unixtime`). |
 | `status` `string` | Новый статус заказа. Возможные значения: `chargeable` — заказ готов к оплате. Необходимо оформить заказ пользователю внутри приложения. В случае ответа об успехе платёжная система зачислит голоса на счёт приложения. Если в ответ будет получено сообщение об ошибке, заказ отменяется. `refunded` — заказ отменён. Необходимо забрать игровые ценности, выданные пользователю за платежи. Доступен начиная с версии API 5.132. |
 | `sig` `string` | Подпись уведомления (см. [Проверка подписи уведомления](api/payments/notifications/overview#Проверка%20подписи)) |
 | `item` `string` | Наименование товара, переданное диалоговому окну покупки (см. [Параметры диалогового окна платежей](api/payments/getting-started)). |
 | `item_id` `integer` | Идентификатор товара в приложении. |
 | `item_title` `string` | Название товара. |
 | `item_photo_url` `string` | Изображение товара. |
 | `item_price` `string` | Стоимость товара. |
 | `item_discount` `string` | Размер скидки на товара, если она есть. |

## Параметры ответа

 | Название параметра | Примечение |
 |---|---|
 | `order_id` `integer`, обязательный | Идентификатор заказа в системе платежей ВКонтакте. |
 | `app_order_id` `integer` | Идентификатор заказа в приложении. Должен быть уникальным для каждого заказа.  |

## Пример ответа

```JSON
{
  "response": {
    "order_id": 1111,
    "app_order_id": 6492
  }
}

```

## Пример ответа в случае ошибки

```JSON

{
  "error": {
        "error_code":21, 
        "error_msg":"Нет в наличии",
        "critical":1
    }
}

```

Интеграция | Платежи | Платёжный API | Изменение статуса заказа

# Публикации ВКонтакте

## Публикации с сайтов

### Share

Для публикации ссылки на страницу вашего сайта используйте виджет [Публикация ссылок](widgets/share) или его упрощенную версию — ссылку вида [`https://vk.com/share.php?url=`](https://vk.com/share.php?url=).

![width=50%;height=200px](a0aafaec2d6784e88292f269935d0dce9d70b14e9fc87ec2bd762190 "-6087573413949829335")

### Другие виджеты

Возможность поделиться с друзьями реализована в нескольких виджетах для внешних сайтов. В каждом из этих случаев к записи на стене пользователя будет прикреплена ссылка на страницу вашего сайта, где размещен виджет:
*  [Виджет комментариев](widgets/comments) — пользователь может поделиться комментарием на своей стене. Параметр `autoPublish` позволяет настроить публикацию по умолчанию.
*  [Виджет «Мне нравится»](widgets/like) — действие **Рассказать друзьям** создает на странице пользователя запись с  опциональным комментарием.
*  [Виджет опросов](widgets/poll) — пользователь может поделиться результатом голосования в опросе. 

## Публикации из приложений

Для публикации записей из клиентских и серверных приложений используйте метод [`wall.post`](method/wall.post). Вы можете обращаться к нему напрямую, используя [классическую схему взаимодействия с API](api/api-requests), из [SDK](sdk/overview), из [Open API](api/open-api/getting-started), если речь идет о приложении-сайте. В Open API и приложениях на vk.com действие потребует подтверждения пользователя.

### Медиаконтент в записи на стене

Чтобы добавить к записи аудио, видео или фото, передайте в параметре `attachments` тип объекта и его строковый идентификатор.

Тип объекта — `audio`, `video`, `photo` или `doc`.

Строковый идентификатор — это строка, включающая идентификатор владельца объекта (`owner_id`) и идентификатор самого объекта (`audio_id`, `video_id` и т.д.).

Например, для фотографии [`photo34_408897832`](https://vk.com/photo34_408897832) в `attachments` нужно передать значение `photo34_408897832`.

```
https://api.vk.com/method/wall.post
?owner_id=-1
&message="Tanya"
&attachments="photo34_408897832"
&access_token={YOUR_ACCESS_TOKEN}
&v=:version
```

Запрос к методу [`wall.post`](method/wall.post) для публикации записи с текстом «Tanya» и прикреплённой фотографией [`photo34_408897832`](https://vk.com/photo34_408897832) на стену сообщества [`club1`](https://vk.com/club1).

Если вы хотите прикрепить новый объект к записи на стене, необходимо сначала загрузить его на сервер ВКонтакте. В зависимости от типа контента используйте один из подходов, описанных [на этой странице](api/upload). Затем используйте идентификатор загруженного объекта в параметре `attachments`.

### Предложенные и отложенные записи

С помощью [`wall.post`](method/wall.post) вы можете работать с предложенными и отложенными записями. Чтобы создать предложенную запись, передайте в `owner_id` идентификатор публичной страницы, в которой текущий пользователь не является руководителем.

Чтобы создать отложенную запись, передайте время публикации в параметре `publish_date`.

Для публикации предложенных и отложенных записей используйте параметр `post_id`, значение для которого можно получить методом [`wall.get`](method/wall.get) с `filter`=`suggests` и `postponed` соответственно.

### Ссылки на внешние сайты

Чтобы добавить к записи сниппет ссылки с внешнего сайта (превью-изображение, заголовок и описание), передайте URL в параметре `attachments`. Например, [`https://yandex.ru/`](https://yandex.ru/). Сниппет генерируется автоматически, более подробно об этом вы можете прочитать в следующем разделе.

## Оформление внешних ссылок

### Данные сниппета

![alt=Сниппет ссылки на внешний сайт в записи на стене;title=Сниппет ссылки на внешний сайт в записи на стене](6532be6f132bb58468fa5d9b40ad6ee64076944dc2dc3dd16ba777eb "-3983918226128625608")

**Сниппет** — это карточка с обложкой, изображением и заголовком для ссылки. Когда вы публикуете ссылку в записи на стене, в комментарии или личном сообщении, сниппет генерируется автоматически — для этого используются данные с той страницы, на которую ведёт ссылка.

А именно:
*  Заголовок. Если на странице есть теги `og:title`, `mrc__share_title` или `twitter:title`, то заголовок будет взят из одного из них (указанного первым), иначе будет использован тег `<title>`. 
*  Иллюстрация. Если на странице есть тег `vk:image`, то адрес изображения для иллюстрации будет взят из него. Если такого тега нет, проверяется содержимое тегов `og:image`, `twitter:image`, `image` — адрес изображения для иллюстрации будет взят из указанного первым, иначе будут взяты первые 8 тегов `<img src="...">`, и из них предложены в качестве иллюстрации те картинки, размер которых по ширине и высоте превышает 160 пикселей. 

Мы рекомендуем использовать картинки размером не менее 510x228 пикселей. В этом случае ссылка будет сопровождаться увеличенной картинкой (510x228 пикселей) в сниппете на стене. Если картинка имеет меньший размер (но не менее 160 пикселей по каждой из сторон), или к записи помимо ссылки прикреплены другие вложения, картинка в сниппете будет уменьшенная — 150x83 пикселя.

Например, указать заголовок и картинку для сниппета можно так: 

```HTML
 <head>
 <meta property="og:title" content="Заголовок страницы" />
 <meta property="vk:image"  content="https://pp.vk.me/c629531/v629531034/3172e/xEBYyER1WE4.jpg" />
</head>
```

Обратите внимание, данные для публикации могут кэшироваться. Если вы изменили данные на своем сайте, а ВКонтакте при публикации отображаются старые значения, сбросьте кэш для ссылки на странице [`pages.clearCache`](method/pages.clearCache).

## Предпросмотр содержимого страниц сайтов

В записях сообщества можно размещать ссылки на статьи, содержимое которых пользователь сможет посмотреть в интерфейсе ВКонтакте без перехода на внешний сайт. В таких записях появляется кнопка **Просмотреть**. Нажав на неё, пользователь увидит содержимое статьи на странице с адресом, начинающимся с `https://vk.com/@`, который будет сформирован автоматически. 

![alt=Кнопка предпросмотра под записью;title=Кнопка предпросмотра под записью](ce804419bf7ada3eef0a74df08aca4e6718180ebed2cc25be2abe7ae "2184200479553297311")

Чтобы подключить предпросмотр для ссылок с вашего сайта, пожалуйста, напишите в [Поддержку](https://vk.com/support?act=new_api). В заявке необходимо указать ссылки на несколько примеров статей, ссылку на сообщество вашего сайта ВКонтакте, а также данные о посещаемости сайта и сообщества.

Интеграция | Публикации | Публикации

# Client Credentials Flow для получения сервисного ключа доступа

> **Важно!** Способ получения ключа доступа, о котором рассказывает эта страница, **устарел**. В скором времени он **перестанет работать**. Не используйте его при разработке нового кода. Если вы применяете этот способ в существующих приложениях — обновите их. Для работы с API используйте [сервисный ключ доступа](mini-apps/management/settings) из настроек приложения. [Подробности](reference/roadmap).

&nbsp;

Схема **Client Credentials Flow** предполагает получение сервисного ключа доступа через API-вызов. Полученный ключ можно использовать для работы с API-методами группы [`secure`](method/secure).

## Как получить ключ

### Запрос

Для получения сервисного ключа доступа отправьте следующий GET-запрос:

```
https://oauth.vk.com/access_token?client_id= + CLIENT_ID + &client_secret= + CLIENT_SECRET + &v=:version&grant_type=client_credentials
```

В URL запроса передайте следующие параметры:

| Параметр | Описание |
| --- | --- |
| `client_id`&#x0d;&#x0a;*обязательный* | Идентификатор вашего приложения.&#x0d;&#x0a;Вы можете найти его в настройках приложения ([Настройки](mini-apps/management/settings) &rarr; **ID приложения**). |
| `client_secret`&#x0d;&#x0a;*обязательный* | Защищённый ключ вашего приложения.&#x0d;&#x0a;Вы можете найти его в настройках вашего приложения ([Настройки](mini-apps/management/settings) &rarr; **Защищённый ключ**). |
| `grant_type`&#x0d;&#x0a;*обязательный* | Тип авторизации. Передайте значение `client_credentials`.|  
| `v`&#x0d;&#x0a;*обязательный* | [Версия API](reference/versions), которую вы используете. Актуальная версия: `:version`. |

### Ответ

Сервер ВКонтакте в ответе вернёт значение  `access_token`, которое является значением сервисного ключа доступа вашего приложения.

```JSON
{
  "access_token": "533bacf01e11f55b536a565b57531ac114461ae8736d6506a3"
}
```

## Использование ключа

Это значение можно использовать при отправке API-запросов [`secure`](method/secure). При вызове указывайте ключ в параметре `access_token` запроса.

> **Важно!** Зная секретный ключ приложения, можно от его имени работать с API-методами [`secure`](method/secure) без ведома владельца.
>
> Никогда не передавайте свой секретный ключ третьей стороне и не храните его в открытом виде. Если секретный ключ был скомпрометирован, обязательно измените его в настройках приложения.

Использование API | Ключ доступа | Client Credentials Flow для получения сервисного ключа доступа

# API историй

Статистика историй ВКонтакте — 12 миллионов авторов, 71 миллион историй, 4,4 миллиарда просмотров от 46 миллионов пользователей каждый месяц. Загружать истории с помощью API могут любые пользователи и сообщества.

![](d0618ed378f440b275f817e6cce855080d6a77c542f56f07848f6566 "4448781307036623856")

#### Как работать с API историй

Пошаговая инструкция при работе с API Историй ВКонтакте заключает в себе несколько шагов:

1. Авторизуйте пользователя ВКонтакте [одним из этих способов](api/access-token/getting-started) или с помощью наших SDK для [Android](sdk/android) и [iOS](sdk/ios).
2. Подготовьте историю — фотографию или видео.
3. Если вы разрабатываете мини-приложение, опубликуйте историю с помощью редактора историй (событие [`VKWebAppShowStoryBox`](bridge/VKWebAppShowStoryBox)).
4. Если вы работаете над другим приложением, размещайте историю с помощью методов секции [`Stories`](method/stories). Сначала получите адрес для загрузки с помощью [`stories.getPhotoUploadServer`](method/stories.getPhotoUploadServer), затем загрузите фотографию или видео и сохраните историю, воспользовавшись [`stories.save`](method/stories.save).

История появится в новостях у друзей и подписчиков пользователя в зависимости от настроек приватности. [С помощью API](method/stories) можно также управлять историями и следить за количеством просмотров.

API ВКонтакте | Истории | API историй 

# Стикеры в историях

Интерактивные стикеры — это стикеры в историях, с которыми можно взаимодействовать. Например, «Мнения», «Музыка», «Фото». На платформе VK Mini Apps вы можете создавать собственные интерактивные стикеры — с любым оформлением и функциональностью.

## Зачем это нужно

Этот инструмент позволяет воспользоваться вашим мини-приложением прямо при просмотре истории. Например, пообщаться с автором истории в анонимном чате, заказать товар или услугу, записаться на экскурсию. Стикеры с логотипом вашей компании помогут рассказать о продукте, повысить лояльность к бренду и его узнаваемость. 

## Пример реализации

Посмотреть, как работают интерактивные стикеры, можно на примере мини-приложения [Планы](https://vk.com/plans). В нём пользователю предлагается выбрать вариант совместного досуга с друзьями: пообедать, созвониться, сходить в кино и так далее. Для каждого действия существует свой отдельный интерактивный стикер. 

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

Пользователь публикует историю. Просматривая её, друзья автора могут нажать на интерактивный стикер или на специальную кнопку в правой части истории — и попасть на экран мини-приложения с кнопкой «Хочу!». Когда человек нажмёт на эту кнопку, автор истории получит уведомление в «колокольчик», что друг готов составить ему компанию.

:::carousel
![title=Экран мини-приложения с выбором действия и экран редактора истории с интерактивным  стикером;](6bbc24564c6521921080ef0470c3159c3fbc89c7c262c7d0bd85de6e "-2155430077254898191")
![title=Опубликованная история с интерактивным стикером и экраны мини-приложения;](83f7af3c4e435a48a150d7621875cf91e5ae91e6a77b6acc691907ce "5622990721197478099")
![title=Пример уведомления;](168752632d99a3f871ebe8c7ad7bb91e46bac651f1775e247de9087c "-489840235644126560")
:::

Это только одно из [мини-приложений с новой механикой](https://vk.com/press/mini-apps-stickers). Добавить в свой проект уникальные интерактивные стикеры может любой разработчик: платформа VK Mini Apps бесплатна, а вся документация находится в открытом доступе — в [сообществе VK Mini Apps.](https://vk.com/vkappsdev)

Стикеры в историях

Интеграция | Публикации | Загрузка файлов

Интеграция | Сообщества и пользователи | User Long Poll API

# Сервис распознавания речи

[Сервис распознавания речи ВКонтакте](https://vk.com/voice-tech) позволяет преобразовать аудиозапись в текстовую расшифровку. Сервис использует ASR (Automatic Speech Recognition)&nbsp;— технологию распознавания речи на базе нейросетей, которая считывает голос и переводит его в текст. Эта технология используется ВКонтакте для расшифровки голосовых сообщений, генерации субтитров в видео и многого другого.

В сервисе используются следующие модели распознавания речи:

* Спонтанная — распознавание речи со сленгом и ненормативной лексикой.
* Нейтральная — распознавание разборчивой речи, как в интервью или телешоу.

Сервис можно встроить как в мини-приложение, так и в игру на любой платформе.

## Ограничения

* Поддерживаемые форматы аудиозаписи: OGG, WAV, MP3 в качестве от 16000&nbsp;Гц (16&nbsp;кГц).
* Максимальный размер файла аудиозаписи: 100&nbsp;МБ.
* Суммарная максимальная длительность файлов аудиозаписей в сутки: 100 минут.
* [Ссылка на адрес сервера для загрузки аудиозаписи](method/asr.getUploadUrl) доступна 1 сутки.
* Методы, указанные в разделе [Интеграция](#Интеграция), можно вызвать только с сервисным ключом доступа.
* Поддерживается распознавание только русского языка.

> **Обратите внимание!** Безлимитное использование технологии возможно за дополнительную плату. Об условиях можно узнать, отправив заявку на электронную почту `bizdev@corp.vk.com`.

## Интеграция

Чтобы получить текстовую расшифровку аудиозаписи, встройте методы API в свое приложение. Выполните следующие шаги:

1. [Получите адрес сервера для загрузки аудиозаписи](method/asr.getUploadUrl).
1. [Отправьте аудиозапись по адресу сервера загрузки](#Запрос%20на%20отправку%20аудиозаписи).
1. [Запустите распознавание аудиозаписи](method/asr.process).
1. [Получите результат распознавания аудиозаписи](method/asr.checkStatus).

### Запрос на отправку аудиозаписи

Сформируйте и отправьте POST-запрос по адресу сервера, полученному из метода [`asr.getUploadUrl`](method/asr.getUploadUrl), с файлом аудиозаписи, преобразованным в формат [`multipart/form-data`](https://ru.wikipedia.org/wiki/Multipart/form-data).

Пример запроса:

```HTTP
POST https://pu.vk.com/gu/speech/v2/upload?token=eyJ0e13iOiJKV1QiLCJhbGmdOiJIUzI1NiJ9.eyqlmAQiOjE2NjM1OTAzNDYsInZrX3VzZXJfaWQiOjgxNDI3MDksInZrX2FwcF9pZCI6ODE0MjcwOSwidmtfdXBsb2FkX3R5cGUiOiJzcGVlY2gifQ.9PStNUU8cf-rlFdPhM5hKQ2xSjhbxzxy7SRKYHvXC_M HTTP/1.1

Content-Type: multipart/form-data

{
  "file": "\x9b\x9f\xf4\xac\xce\xb5\xac,\xf1o,\x9e6\xf3\xadQl\xb4.3~.\xaf\xa8\xb3\x95/\xd4\xbf\xdd\xaf\x06\x96\x100\..."
}
```

Пример успешного ответа:

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "sha": "894e6ab2092d7d2bb093dc8f7e5c60d0ce09c2ane698121c53fefcdc",
  "secret": "1248134271945096002",
  "meta": {
    "duration": "43.6652",
    "size": "1065633",
    "type": "ogg"
  },
  "hash": "50a9f8dasf073969e92ca20ad47031e6",
  "server": "230305",
  "user_id": 123,
  "request_id": "19d5e34ca1e740e283dfc844027a1df7",
  "app_id": 123
}
```

Пример ответа с ошибкой:

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "request_id": "19d5e34ca1e740e283dfc844027a1df7",
  "error_code": 123,
  "error_msg": "Internal Server Error"
}
```

Интеграция | Распознавание речи | Сервис распознавания речи

Условия размещения приложений на сайте VK.com

Правила | Оферта на оказание услуг по размещению рекламы

Оферта о заключении договора

Оферта о заключении договора оказания услуг от 21.10.2021

# Одобренные способы оплаты

> **Важно!**
>
> Обратите внимание, что приложения-магазины **не могут** использовать как средство оплаты **SMS-платежи и подписки**.
>

В приложениях, соответствующих [требованиям к магазинам ВКонтакте](market-rules), разрешено использовать следующие внешние платёжные системы:
* QIWI Кошелёк
* WebMoney
* Яндекс.Деньги
* Google Checkout
* Paypal
* Money Mail
* RBK Money
* Robokassa
* 2pay
* Деньги-Онлайн
* Intellect Money
* Moneta.ru
* А также все платёжные шлюзы, осуществляющие приём банковских карт (Assist, Cyberplay, Platezh.ru и другие). Помимо указанных платёжных систем к оплате может также приниматься **оплата курьеру во время доставки** и **оплата товара наложенным платежом при получении**.

Правила | Одобренные способы оплаты

# Правила для ботов

**1.** Ботам запрещено использовать подписку на сообщество, отметки «Нравится», репосты и подписку на рассылку как обязательное условие работы бота. Полная или частичная функциональность ботов не должна зависеть от того, является пользователь участником сообщества, поставил ли он отметку «Нравится», сделал ли он репост и подписался ли на рассылку. Например, если основная функция бота — обрабатывать фотографии, то он не может делать это только после подписки на сообщество.
**1.1.** Примеры запрещённых условий: «Чтобы получить арт, подпишись на меня», «Эта возможность доступна только подписчикам», «Если хочешь продолжить игру, сделай репост закреплённой записи и поставь лайк на аватар» и подобные. Такие просьбы недопустимы в переписке с пользователями, приветственном сообщении, на стене сообщества и т. д.
**1.2.** Разрешено устраивать раздачи и конкурсы на стене сообщества, благодаря которым участники могут получить пользу (игровую валюту, дополнительные жизни, бесплатные выполнения команд в платных ботах и т. д.), сделав репост, поставив лайк или написав комментарий. Например: «Раздаём 100 монет всем, кто сделает репост», «10 дополнительных бесплатных артов за репост» и т. д. 
**1.2.1.** Любые раздачи и конкурсы должны соответствовать [Правилам проведения конкурсов ВКонтакте](https://vk.com/page-59800369_53731448).

**2.** Если бот обещает выполнить какую-то функцию (обработать фото или видео, прислать ключ, анекдот и так далее), то должен сделать это в течение суток с момента запроса пользователя. 
**2.1.** Если бот не работает по техническим причинам, информация об этом должна быть размещена на видном месте в его сообществе. 
**2.2.** Если бот должен выполнить функцию в будущем — в ответ на вызов команды бот должен прислать информацию о времени выполнения команды. Например, если результат работы команды зависит от внешних факторов, таких как события, мероприятия, или если команда является запланированным напоминанием. Взаимодействие с ботом при этом не должно быть заблокировано.

**3.** Просьбы подписаться на сообщество, поставить лайк, сделать репост и т. д.
**3.1.** Пока бот обрабатывает запрос от пользователя и не выполнил свою команду, ему не следует отправлять такие просьбы. Примеры неправильного ответа: «Пока ждёшь арт, подпишись», «Запрос принят в обработку, не забудь поставить лайк на закреплённую запись». 
**3.2.** Подобные просьбы недопустимы в приветственном сообщении сообщества. 
**3.3.** Подобные просьбы разрешено рассылать не более одного раза в сутки и только после выполнения основной функции бота.
**3.4.** Подобные просьбы разрешено отправлять только в сообщениях, которые отвечают за запрос пользователя, например: «Держи обработанную фотографию. Если тебе нравится наш бот — подпишись на сообщество, чтобы быть в курсе всех новостей».

**4.** Название команды должно ясно и чётко отражать действие, которое произойдёт в результате её выполнения.
**4.1.** Если по команде бота пользователю будут предложены ссылки на другие сообщества или сайты, не имеющие прямого отношения к боту или касающиеся его косвенно, команда должна иметь соответствующее название или содержать предупреждение. Например, если при выполнении команды бот пришлёт ссылку на официальный сайт партнёра, команда должна так и называться: «Ссылка на оф. сайт партнёра».
**4.2.** Запрещено вводить пользователя в заблуждение, намерено указывая неправильные названия команд.

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

**6.** Бот может отправлять рекламные сообщения / рассылки пользователю, если они соответствуют [Правилам размещения рекламы в сообществах](https://vk.com/page-59800369_53731475) и [Правилам монетизации ботов](bots-rules#Правила%20монетизации%20ботов).

**7.** Администрация Сайта имеет право отключить бота, если он не соответствует вышеперечисленным правилам или противоречит стандартам Администрации. 
**7.1.** Любые рекламные сообщения / рассылки в многопользовательские беседы запрещены. При нарушении этого правила сообществу будут отключены сообщения.

**8.** При отправке сообщений, содержащих пользовательский контент, необходимо [передавать его источник](api/bots/development/messages#Сообщения%20с%20пользовательским%20контентом). Им может быть: фотография из альбома, запись, комментарий, сообщение и т. д. Наличие источника позволит избежать блокировок, если пользователи будут отправлять запрещённые [Правилами платформы](https://vk.com/terms) материалы, и может быть полезно любым ботам, пересылающим пользовательский контент. Например, ботам, позволяющим людям общаться между собой, или дейтинг-ботам с анкетами, в которых можно добавлять фотографии, указывать информацию о себе и т. д., особенно в тех случаях, когда её видят другие пользователи чат-бота.

## Правила монетизации ботов
Вы можете монетизировать бота следующими способами: 
**1.** Платная подписка. 
**1.1.** Бот может выполнять свои команды платно: давать пользователям необходимую информацию и удовлетворять их запросы за вознаграждение. Разработчик сам определяет стоимость запроса, а также настраивает систему оплаты. 
**1.2.** Бот может работать по платным подпискам разных уровней доступа к возможностям бота. 
**1.3.** Информация о платных вариантах работы бота должна быть легкодоступна и хорошо видна. Например, в меню сообщества, приветственном сообщении или в закреплённой записи. 
**1.4.** Пример платной подписки: «Получить дополнительно ещё 10 фотографий можно, оплатив 50 рублей», «Купите 30 дней неограниченного использования всех возможностей бота за 490 рублей».

**2.** Бот может просить подписаться на рекламную рассылку. Сообщения из этой рассылки пользователь должен получать не чаще, чем один раз в семь дней. 
**2.1.** За подписку на рекламную рассылку бот может предлагать выполнение какой-то команды или бонусы (это может быть игровая валюта, бесплатное выполнение платных команд бота и другое).
**2.2.** Попросить подписаться на рассылку можно в приветственном сообщении, которое задается в настройках сообщества, в основном меню бота или в его подменю. Например, можно сделать следующую структуру: «Основное меню» -> «Управление рассылкой» -> «Подписаться на рекламную рассылку». При этом запрещено просить подписаться на рассылку во время выполнения команд пользователя или в процессе взаимодействия с ботом.
**2.3.** Просьба подписаться на рассылку и кнопка, которая выполняет подписку, должна в явном виде давать понять пользователю, что он будет подписан на рекламную рассылку и будет получать сообщения не чаще, чем один раз в семь дней. 
**2.4.** После нажатия на кнопку подписки бот должен написать пользователю, что тот подписан на рекламную рассылку, и указать способ отписки. 
**2.5.** Каждое сообщение рекламной рассылки должно сопровождаться кнопкой для отписки от рассылки. 
**2.6.** Сообщение должно быть помечено интентом — `promo_newsletter`.

**3.** Бот может получить доступ к Рекламному API, если он проходит по критериям, описанным в пункте **3-1**, и прошёл модерацию командой ВКонтакте. 
**3.1.** Критерии:
**3.1.1.** Среднесуточная аудитория бота за последние 30 дней — не менее 50К пользователей.
**3.1.2.** Бот включён в сообществе более трёх месяцев.
**3.1.3.** К сообществу бота не применялось каких-либо наказаний за нарушения правил сайта за последние полгода.
**3.1.4.** Администрация оставляет за собой право отказать боту в доступе к Рекламному API, если он не соответствует правилам или противоречит стандартам Администрации.
**3.2.** После прохождения модерации бот сможет отправлять сообщения, используя Рекламный API.
**3.2.1.** В диалоге с ботом пользователю будет показано предупреждение о том, что этот бот может присылать рекламные сообщения.
**3.3.** Бот может отправлять рекламу пользователю не более одного раза в сутки и только после выполнения своей основной функции. При этом бот предварительно должен спросить у пользователя разрешение на показ рекламы.
**3.3.1.** Сообщение с приглашением получить рекламу должно в явном виде быть помечено как реклама (внутри сообщения текстом должно быть написано, что это реклама / партнёрский материал / акция и т. д.). Хороший пример такого сообщения: «Сообщение от партнёра: „Привет! Сегодня твоя анкета популярнее других. У меня есть несколько свободных мест на кастинг для фотомоделей. Одно из этих мест я решил отдать тебе. Это уникальная возможность пройти обучение и стать топ-моделью. Хочешь узнать больше?“»
**3.3.2.** Сообщение с предложением получить рекламу должно быть помечено интентом `bot_ad_invite`.
**3.3.3.** В ответ на приглашение получить рекламу пользователь может согласиться получить рекламу или отказаться от получения рекламы. 
**3.3.4.** Пользователь должен иметь возможность продолжить пользоваться ботом после отказа получить рекламу. 
**3.3.5.** Рекламное сообщение должно отправляться пользователю только после его согласия получить рекламу и должно отмечаться интентом `bot_ad_promo`.
**3.3.6.** Сообщение с предложением получить рекламу и рекламное сообщение должно соответствовать 
[правилам платформы](https://vk.com/terms) и [правилам размещения рекламы](https://vk.com/page-59800369_53731475).
**4.** При нарушении правил, перечисленных в разделе [Правила монетизации ботов](#Правила%20монетизации%20ботов), сообществу будут отключены сообщения.
**5.** Бот, которого наказали за нарушение правил сайта, автоматически отключается от возможностей Рекламного API. Получить разрешение для повторного подключения он может через Поддержку, если произошла ошибка. Либо через полгода, согласно критериям отбора сообществ.

Правила | Правила для ботов

# VKWebAppAllowMessagesFromGroup

`VKWebAppAllowMessagesFromGroup` показывает окно с запросом прав доступа на отправку сообщений от имени сообщества.

## Пример

```JavaScript
bridge.send('VKWebAppAllowMessagesFromGroup', {
  group_id: 166562603,
  key: 'dBuBKe1kFcdemzB' 
  })
  .then((data) => { 
    if (data.result) {
      // Пользователь разрешил отправку сообщений от имени сообщества
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `group_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор сообщества. |
| `key` &#x0d;&#x0a;*необязательное* | `string` | Произвольная строка. Этот параметр можно использовать для идентификации пользователя. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppAllowMessagesFromGroupResult` и `VKWebAppAllowMessagesFromGroupFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `User denied`, если пользователь запретил отправку сообщений от имени сообщества.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если пользователь разрешил отправку сообщений от имени сообщества. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppAllowMessagesFromGroupResult`

Сигнализирует, что пользователь разрешил отправку сообщений от имени сообщества. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppAllowMessagesFromGroupResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppAllowMessagesFromGroupFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

 [VKWebAppAllowMessagesFromGroup](https://vk.cc/bZfqcr)


VK Bridge | Сообщества | VKWebAppAllowMessagesFromGroup

# VKWebAppAllowNotifications

`VKWebAppAllowNotifications` показывает окно с предложением запросить у пользователя разрешение на отправку уведомлений от мини-приложения или игры.  

## Пример

```JavaScript
bridge.send('VKWebAppAllowNotifications')
  .then((data) => { 
    if (data.result) {
      // Разрешение на отправку уведомлений мини-приложением или игрой получено
    } else {
      // Ошибка
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web 

## Параметры

— 

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppAllowNotificationsResult` и `VKWebAppAllowNotificationsFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение или игра запущены в фоновом режиме.
* `User denied`, если пользователь закрыл окно с предложением запросить у пользователя разрешение на отправку уведомлений от мини-приложения или игры.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если разрешение на отправку уведомлений мини-приложением или игрой получено. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppAllowNotificationsResult`

Сигнализирует, что разрешение на отправку уведомлений мини-приложением или игрой получено. В обработчик события на стороне пользователя передаются следующие данные:

```JavaScript
{
  detail: {
    type: "VKWebAppAllowNotificationsResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppAllowNotificationsFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppAllowNotifications](https://vk.cc/bZfspS)


VK Bridge | Общие события | VKWebAppAllowNotifications

# VKWebAppBannerAdClosedByUser

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

## Пример

```JavaScript
bridge.subscribe((e) => {
  if (e.detail.type === 'VKWebAppBannerAdClosedByUser') {
    // Логика мини-приложения
  }
});
```

## Платформы

Android, iOS

## Параметры

—

## Результат

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

`VKWebAppBannerAdClosedByUser` сигнализирует, что баннер закрыт пользователем. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `banner_location` | `string` | Расположение баннера. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `top` —  баннер будет прижат кверху.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `bottom` — баннер будет прижат книзу. Значение по умолчанию. |
| `banner_width` | `integer` | Ширина баннера в пикселях.|
| `banner_height` | `integer` | Высота баннера в пикселях.|
| `layout_type` | `string` | Тип фона баннера. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `resize` — WebView станет меньше на размер баннера. Значение по умолчанию.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `overlay` — баннер отрисуется поверх WebView. Если нужно сдвинуть контент, разработчик мини-приложения делает это сам. |

В обработчик события на стороне пользователя передаются следующие данные:

```JavaScript
{
  detail: {
    type: "VKWebAppBannerAdClosedByUser",
    data: {
      "banner_width": 100,
      "banner_height": 64,
      "banner_location": "top",
      "layout_type": "resize"
    }
  }
}
```

## Пример обработки события

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | Баннерная реклама| VKWebAppBannerAdClosedByUser

# VKWebAppCallAPIMethod

`VKWebAppCallAPIMethod` получает результат вызова метода API ВКонтакте.

## Пример

```JavaScript
bridge.send('VKWebAppCallAPIMethod', {
  method: 'users.get',
  params: {
    user_ids: '743784474,743784479',
    v: '5.131',
    access_token: 'ПОЛЬЗОВАТЕЛЬСКИЙ_КЛЮЧ_ДОСТУПА'
  }})
  .then((data) => { 
    if (data.response) {
      // Метод API выполнен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `method` &#x0d;&#x0a;*обязательное* | `string` | Имя вызываемого [метода API](methods). |
| `params` &#x0d;&#x0a;*обязательное* | `object` | Параметры метода API. Возможные поля:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `access_token` (`string`) — ключ доступа пользователя с соответствующими правами, полученный с помощью события [`VKWebAppGetAuthToken`](bridge/VKWebAppGetAuthToken).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `v` (`string`) — версия API, используемая для запроса (последняя доступная версия: `:version`).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; другие обязательные параметры метода API. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppCallAPIMethodResult` и `VKWebAppCallAPIMethodFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `response` | `array[object]` | Результат выполнения метода API. Описание структуры объекта `response` можно найти на странице соответствующего метода. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppCallAPIMethodResult`

Сигнализирует, что метод API выполнен. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppCallAPIMethodResult",
    data: {
      response: [
        {
          id: 743784474,
          first_name: "Персик",
          last_name: "Рыжий",
          can_access_closed: true,
          is_closed: false
        },
        {
          id: 743784479,
          first_name: "Сеня",
          last_name: "Хомяк",
          can_access_closed: true,
          is_closed: false
        }
      ]
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppCallAPIMethodFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppCallAPIMethod](https://vk.cc/bZfnNu)


VK Bridge | Пользователи | VKWebAppCallAPIMethod

# VKWebAppChangeFragment

`VKWebAppChangeFragment` отправляется платформой, если пользователь открывает мини-приложение по ссылке вида: `https://vk.com/app6909581#fragment`.

Если мини-приложение поддерживает [навигацию по хешу](bridge/VKWebAppSetLocation), вы можете перенаправить пользователя на конкретное навигационное состояние этого мини-приложения по ссылке вида: `https://vk.com/app6909581#fragment`.

## Пример

```JavaScript
bridge.subscribe((e) => {
  if (e.detail.type === 'VKWebAppChangeFragment') {
    // Логика мини-приложения
  }
});
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

—

## Обработка события

Если пользователь открывал мини-приложение раньше, его навигационное состояние уже хранится в кеше. Чтобы отобразить правильный экран мини-приложения без перезагрузки WebView:

1. Подпишитесь на событие `VKWebAppChangeFragment` с помощью метода `subscribe`.
1. После получения события откройте экран мини-приложения, который соответствует переданному в событии полю `location`.

:::note
**Примечание.** Событие `VKWebAppChangeFragment` всегда отправляется до события [VKWebAppViewRestore](bridge/VKWebAppViewRestore), что позволяет приложению открыть нужный экран, пока восстановленный из кеша экран ещё не отобразился полностью.
:::

## Результат

`VKWebAppChangeFragment` сигнализирует, что хеш получен. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `location` | `string` | Хеш — строка после символа `#` в URL вида `vk.com/app6909581#`. |

 В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppChangeFragment",
    data: {
      location: "fragment"
    }
  }
}
```

## Пример обработки события

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | События жизненного цикла | VKWebAppChangeFragment

# VKWebAppClose

`VKWebAppClose` закрывает мини-приложение или игру. Если закрываемое мини-приложение или игра были запущены с помощью события [`VKWebAppOpenApp`](bridge/VKWebAppOpenApp), при успешном закрытии в родительское приложение будет передано событие `VKWebAppCloseResult`.

## Пример

```JavaScript
bridge.send('VKWebAppClose', {
  status: 'success',
  payload: {
    name: 'value'
  }})
  .then((data) => { 
    if (data.status) {
      // Событие отправлено
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `status` &#x0d;&#x0a;*обязательное* | `string` | Статус закрытия мини-приложения или игры, передаваемый в родительское приложение. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `success` — мини-приложение или игра закрылись успешно.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `failed` — мини-приложение или игра закрылись с ошибкой. |
| `payload` &#x0d;&#x0a;*необязательное* | `object` | Данные, передаваемые в родительское приложение. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppCloseResult` и `VKWebAppCloseFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение или игра запущены в фоновом режиме.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `status` | `string` | Статус закрытия мини-приложения или игры, передаваемый в родительское приложение. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `success` — мини-приложение или игра закрылись успешно.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `failed` — мини-приложение или игра закрылись с ошибкой. |
| `payload` | `object` | Данные, передаваемые в родительское приложение. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppCloseResult`

Сигнализирует, что событие отправлено. В обработчик события на стороне пользователя передаются следующие данные:

```JavaScript
{
  detail: {
    type: "VKWebAppCloseResult",
    data: {
      status: "success",
      payload: {
        name: "value"
      }
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppCloseFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppClose](https://vk.cc/bZfsEx)


VK Bridge | Общие события | VKWebAppClose

# VKWebAppConversionHit

`VKWebAppConversionHit` позволяет отслеживать [конверсионные действия](https://vk.com/faq16578) пользователей в мини-приложении.

## Пример

```JavaScript
bridge.send("VKWebAppConversionHit", {
    "pixel_code": "VK-Boo-427253-dUuM", 
    "conversion_event": "purchase",
    "conversion_value": 3500
  })

```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

`pixel_code` 
`string`, `required` 
Код пикселя. Например: `VK-Boo-427253-dUuM`. Код пикселя можно найти в [рекламном кабинете](https://vk.com/ads?act=retargeting&show=pixels). 

`conversion_event`
`string`, `required`
Конверсионное действие, которое необходимо отслеживать. Например, чтобы отслеживать добавление товара в корзину, значение `conversion_event` должно быть равно `add_to_cart`, если покупку товара, значение `conversion_event` должно быть равно `purchase`. Список всех возможных значений описан в [документации рекламного кабинета](https://vk.com/faq16578). 

`conversion_value` 
`float`
 Стоимость (ценность) конверсионного события (если есть). Например, если пользователь купил товар за 3500 рублей, значение `conversion_event` должно быть равно `purchase`, а значение `conversion_value` должно быть равно `3500`. 

> Обратите внимание. При создании пикселя в рекламном кабинете можно указывать только идентификатор мини-приложения (поле **Разрешённый Mini App id**). Указывать домен или поддомен не обязательно.

## Результат

После успешного выполнения возвращается событие `VKWebAppConversionHitResult`.

```JSON
{
  "type":"VKWebAppConversionHitResult",
  "data":{
    "result":true
  }
}
```

В случае ошибки генерируется событие `VKWebAppConversionHitFailed`.

```JSON
{ 
  "type": "VKWebAppConversionHitFailed", 
  "data": {
     "error_type": "...",
     "error_data": {
        ...
     }
  }
}
```

VK Bridge | Отслеживание пользователей | VKWebAppConversionHit

# VKWebAppCreateHash

`VKWebAppCreateHash` генерирует хеш. Хеш помогает защититься от подмены данных, которые ВКонтакте отправляет мини-приложению или игре, например при показах рекламы.

Чтобы убедиться, что данные приходят именно от сервера ВКонтакте, достаточно [вычислить хеш](#Вычисление%20хеша) и сравнить с тем, что мини-приложение или игра получило в ответе.

## Пример

```JavaScript
bridge.send('VKWebAppCreateHash')
  .then((data) => { 
    if (data.sign) {
      // Хеш сгенерирован
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `request_id` &#x0d;&#x0a;*необязательное* | `string` | Идентификатор запроса. Используется для проверки соответствия запроса и ответа. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppCreateHashResult` и `VKWebAppCreateHashFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `sign` | `string` | Хеш, который генерирует сервер ВКонтакте, используя защищённый ключ и текущее значение времени. Такой же принцип используется для подписи [параметров запуска](mini-apps/development/launch-params). |
| `ts` | `integer` |  Дата и время в секундах, когда хеш был сгенерирован ([Unix Timestamp](https://www.unixtimestamp.com/)). |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### VKWebAppCreateHashResult

Сигнализирует, что хеш сгенерирован. В обработчик события на стороне пользователя передаются следующие данные:

```JavaScript
{
  detail: {
    type: "VKWebAppCreateHashResult",
    data: {
      sign: "m7TwcoveOwy4BE180UCTwyTkPApprYP81RjrOEuQcos",
      ts: 1664541985
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### VKWebAppCreateHashFailed

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Вычисление хеша

Чтобы вычислить хеш:

1. Добавьте в ответ идентификатор пользователя `user_id` и идентификатор мини-приложения или игры `app_id`.
1. Отсортируйте параметры ответа по ключу (в алфавитном порядке) и объедините пары «ключ=значение» в строку с амперсандом в качестве разделителя.
1. Сериализуйте строку с помощью алгоритма хеширования [HMAC-SHA256](https://ru.wikipedia.org/wiki/HMAC). В качестве ключа используйте защищённый ключ из настроек [мини-приложения](mini-apps/management/settings) или игры. Выбранная реализация HMAC должна использовать хеш-функцию SHA-256.
1. Преобразуйте в строку двоичные данные, полученные на предыдущем шаге. Используйте алгоритм [Base64](https://ru.wikipedia.org/wiki/Base64).

### Пример

```PHP
$sign_param = 'fSibt9N1v3DYflFKFl2qyRk-g3szAKiGDL0p6fYGFSI';

$hash_params = [
  'ts' => 1630076629,
  'request_id' => '123',
];

// Добавляем идентификатор пользователя и мини-приложения или игры к ответу на событие.
$hash_params['user_id'] = 123;
$hash_params['app_id'] = 123;

// Сортируем массив по ключам.
ksort($hash_params);

// Формируем строку вида param_name1=value&param_name2=value.
$sign_params_query = http_build_query($hash_params);

// Получаем хеш-код от строки, используя защищёный ключ приложения (метод HMAC).
$sign = rtrim(strtr(base64_encode(hash_hmac('sha256', $sign_params_query, $client_secret, true)), '+/', '-_'), '=');

// Сравниваем полученную строку со значением из VKWebAppCreateHash.
$status = $sign === $sign_param;

echo ($status ? 'ok' : 'fail')."\n";
```

## Песочница

[VKWebAppCreateHash](https://vk.cc/c6kfQV)


VK Bridge | Общие события | VKWebAppCreateHash

# VKWebAppFlashGetInfo

`VKWebAppFlashGetInfo` запрашивает информацию о фонарике.

## Пример

```JavaScript
bridge.send("VKWebAppFlashGetInfo");
```

## Платформы

Android, iOS

## Параметры

—

## Результат

После успешного выполнения возвращается событие `VKWebAppFlashGetInfoResult`.

```JSON
{
  "type":"VKWebAppFlashGetInfoResult",
  "data":{
    "is_available": true,
    "level": 0.5
  }
}
```

### Структура объекта `data`

* `is_available` (`bool`)
Доступна ли работа с фонариком. Возможные значения: 
`false` — фонарик недоступен, 
`true` — фонарик доступен. 
* `level` (`float`) 
Уровень яркости фонарика от 0 до 1. 

В случае ошибки или отмены действия пользователем генерируется событие `VKWebAppFlashGetInfoFailed`.

```JSON
{ 
  "type": "VKWebAppFlashGetInfoFailed", 
  "data": {
     "error_type": "..."
     "error_data": {
        ...
     }
  }
}
```

## Песочница

[VKWebAppFlashGetInfo](https://vk.cc/bZfrEB)

VK Bridge | Управление фонариком | VKWebAppFlashGetInfo

# VKWebAppFlashSetLevel

`VKWebAppFlashSetLevel` устанавливает уровень яркости фонарика.

## Пример

```JavaScript
bridge.send("VKWebAppFlashSetLevel", {"level": 1});
```

## Платформы

Android, iOS

## Параметры

* `level` (`bool`)
Уровень яркости фонарика от `0` до `1`. 

## Результат

После успешного выполнения устанавливается яркость фонарика и возвращается событие `VKWebAppFlashSetLevelResult` c полем `result` (`boolean`), содержащим значение `true`.

```JSON
{
  "type":"VKWebAppFlashSetLevelResult",
  "data":{
    "result": true
  }
}
```

В случае ошибки или отмены действия пользователем генерируется событие `VKWebAppFlashSetLevelFailed`.

```JSON
{ 
  "type": "VKWebAppFlashSetLevelFailed", 
  "data": {
     "error_type": "..."
     "error_data": {
        ...
     }
  }
}
```

VK Bridge | Управление фонариком | VKWebAppFlashSetLevel

# VKWebAppGetAuthToken

`VKWebAppGetAuthToken` показывает окно с запросом доступа у пользователя и получает ключ доступа для работы с API. Чтобы идентифицировать пользователя в мини-приложении, ключ доступа запрашивать не нужно, воспользуйтесь [подписью параметров запуска](mini-apps/development/launch-params). 

:::note
**Примечание.** `window.location`, c которого запрашивается токен, должен совпадать с [URL из настроек](mini-apps/management/settings).
:::

## Пример

```JavaScript
bridge.send('VKWebAppGetAuthToken', { 
  app_id: 6909581, 
  scope: 'friends,status'
  })
  .then((data) => { 
    if (data.access_token) {
      // Ключ доступа пользователя получен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `app_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор мини-приложения. |
| `scope` &#x0d;&#x0a;*обязательное* | `string` | Список [прав доступа](reference/access-rights), перечисленных через запятую. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `friends` — доступ к списку друзей пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `photos` — доступ к фотографиям.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `video` — доступ к видео.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `stories` — доступ к историям.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `pages` — доступ к вики-страницам.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `status` — доступ к статусу пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `notes` — доступ к заметкам пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `wall` — доступ к методам работы со стеной.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `docs` — доступ к документам.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `groups` — доступ к сообществам пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `stats` — доступ к статистике групп и приложений пользователя, администратором которых он является.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `market` — доступ к товарам.&#x0d;&#x0a;&#x0d;&#x0a; Чтобы получить ключ доступа без дополнительных прав, передайте в поле пустую строку. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppAccessTokenReceived` и `VKWebAppGetAuthTokenFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `access_token` | `string` | Ключ доступа пользователя. |
| `scope` | `string` | Права доступа, выданные пользователем. Может отличаться от запрошенных прав доступа. |
| `expires` | `integer` | Дата и время секундах, когда время жизни `access_token` истечёт ([Unix Timestamp](https://www.unixtimestamp.com/)). |
| `status` | `boolean` | Индикатор, что событие выполнилось успешно (всегда `true`). |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppAccessTokenReceived`

Сигнализирует, что ключ доступа пользователя получен. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppAccessTokenReceived",
    data: {
      access_token: "vk12XyJnfX7mG7PE1MBW...6KV4dcdjVjzwwwSDkX",
      scope: "docs",
      expires: 1665151371,
      status: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetAuthTokenFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppGetAuthToken](https://vk.cc/bZfnlf)


VK Bridge | Пользователи | VKWebAppGetAuthToken

# VKWebAppGetCommunityToken 

`VKWebAppGetCommunityToken` показывает окно с запросом прав доступа у пользователя и получает ключ доступа для работы с API от имени сообщества. Получить ключ доступа сообщества может только его администратор.

> **Совет.** Чтобы получить список идентификаторов администрируемых сообществ, вызовите метод [`groups.get`](method/groups.get) с параметром `filter=admin`. Для работы с этим методом необходим [ключ доступа пользователя](bridge/VKWebAppGetAuthToken) с правами `scope=groups`.

## Пример

```JavaScript
 bridge.send("VKWebAppGetCommunityToken", {
   app_id: 6909581,
   group_id: 166562603,
   scope: 'messages'
   });
  .then((data) => { 
    if (data.access_token) {
      // Ключ доступа сообщества получен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
   
```
   
## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `app_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор мини-приложения. |
| `group_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор сообщества. |
| `scope` &#x0d;&#x0a;*обязательное* | `string` | Список [прав доступа](reference/access-rights), перечисленных через запятую. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `stories` — доступ к историям.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `photos` — доступ к фотографиям.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `app_widget` — доступ к [виджетам сообществ](api/community-apps-widgets/getting-started).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `messages` — доступ к сообщениям сообщества.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `docs` — доступ к документам.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `manage` — доступ к администрированию сообщества. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetCommunityTokenResult` и `VKWebAppGetCommunityTokenFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `access_token` | `string` | Ключ доступа сообщества. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppGetCommunityTokenResult`

Сигнализирует, что ключ доступа сообщества получен. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetCommunityTokenResult",
    data: {
      access_token: "cc9521551d93ddb290b32648a37a006d87438a67f953dd37e564eb6db1ec28f79d05c16e207f00a0" 
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetCommunityTokenFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppGetCommunityToken](https://vk.cc/bZfqzK)


VK Bridge | Сообщества | VKWebAppGetCommunityToken

# VKWebAppGetConfig

`VKWebAppGetConfig` получает информацию о конфигурации используемого мини-приложения или игры (информацию о родительском приложении, в котором открыто мини-приложение или игра).

## Пример

```JavaScript
bridge.send('VKWebAppGetConfig')
  .then((data) => { 
    if (data.api_host) {
      // Информация получена
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

> **Совет.** Используйте это событие, если вам нужно получить конфигурацию до вызова события [`VKWebAppInit`](bridge/VKWebAppInit). В остальных случаях используйте стандартный способ получения конфигурации — подпишитесь на событие [`VKWebAppUpdateConfig`](bridge/VKWebAppUpdateConfig).

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

 —

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [события](#События) `VKWebAppGetConfigResult`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Платформа | Значение |
|---|---|---|---|
| `api_host` | `string` | Mobile Web, Web | API-хост для вызовов, не использующих VK Bridge. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `api.vk.com`&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `api.vk.ru` |
|`app` | `string` | Android, iOS | Тип клиента. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `vkclient` — приложение ВКонтакте.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `vkme` — мессенджер ВКонтакте. |
|`app_id` | `string` | Android, iOS, Mobile Web, Web | Идентификатор приложения, которому соответствует нативное мобильное приложение ВКонтакте. |
|`appearance` | `string` | Android, iOS, Mobile Web, Web | Тема мини-приложения или игры. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `light`— светлая тема.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `dark` — тёмная тема. |
|`insets` | `string` | iOS | Текущие отступы, которые необходимо выдержать от края экрана до контента (если показана клавиатура, её высота будет в bottom-инсете). |
|`gaid` | `string` | Android, iOS | [Google Advertising ID](https://developer.android.com/training/articles/ad-id). |
|`sak_version` | `string` | Android, iOS | Версия SuperAppKit. |
|`scheme` | `string` | Android, iOS, Mobile Web, Web | Цветовая схема мини-приложения или игры. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `space_gray` — тёмная схема мобильного приложения и мобильной версии сайта.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `bright_light` — светлая схема мобильного приложения и мобильной версии сайта.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `vkcom_light` — светлая схема десктопной версии сайта.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `vkcom_dark` — тёмная схема десктопной версии сайта. |
|`start_time` | `integer` | Android, iOS  | Время и дата открытия модального экрана ([Unix Timestamp](https://www.unixtimestamp.com/)). Передаётся только при открытии модального экрана. |
|`viewport_height` | `integer` | Mobile Web, Web  | Высота родительского окна мини-приложения или игры. |
|`viewport_width` | `integer` | Mobile Web, Web  | Ширина родительского окна мини-приложения или игры. |
|`is_layer` | `boolean` | Web  | Поле приходит, если мини-приложение или игра открыты в слое. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppGetConfigResult`

Сигнализирует, что информация получена. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetConfigResult",
    data: {
      api_host: "api.vk.com",
      app_id: "8142709",
      appearance: "light",
      scheme: "vkcom_light",
      viewport_height: 680,
      viewport_width: 1258
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetConfigFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | Общие события | VKWebAppGetConfig

# VKWebAppGetEmail

`VKWebAppGetEmail` показывает окно с запросом доступа к адресу электронной почты пользователя.

> **Совет.** Если вашему мини-приложению требуется запросить не только адрес электронной почты, но и номер телефона, вызовите [карточку контактов](bridge/VKWebAppGetPersonalCard).

## Пример

```JavaScript
bridge.send('VKWebAppGetEmail')
  .then((data) => { 
    if (data.email) {
      // Доступ к электронной почте получен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Web

## Параметры

—

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetEmailResult` и `VKWebAppGetEmailFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.
* `User denied`, если пользователь запретил доступ к адресу электронной почты.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `email` | `string` | Адрес электронной почты пользователя. |
| `sign` | `string` | Подпись полученных данных. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### `VKWebAppGetEmailResult`

Сигнализирует, что доступ к электронной почте получен. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetEmailResult",
    data: {
      email: "persik_ryzhiy@mail.ru",
      sign: "lY_KLjwfRmx9X1_z4iowRz1pTKHL98PW-14XURLWKYI"
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetEmailFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Вычисление подписи

Для подписи последовательно объединяются значения:

* Идентификатор мини-приложения `app_id`.
* [Защищённый ключ](mini-apps/management/settings#Защищённый%20ключ) `api_secret`.
* Идентификатор пользователя `user_id`.
* Пара `$field_name.$field_value`, вернувшаяся в событии.

От полученной после объединения строки вычисляется криптографический хеш SHA256 в байтовом представлении, затем хеш кодируется с помощью алгоритма Base64 Encode.

Пример формирования подписи события на PHP, где `app_id = 7770000`, `api_secret = W7kVvxVxZ4`, `user_id = 162447`, `field_name = email`, `field_value = test@gmail.com`:

```PHP
$sign = rtrim(strtr(base64_encode(hash('sha256', '7770000W7kVvxVxZ4162447emailtest@gmail.com', true)), '+/', '-_'), '=');
```

## Песочница

[VKWebAppGetEmail](https://vk.cc/bZfkjJ)


VK Bridge | Пользователи | VKWebAppGetEmail

# VKWebAppGetFriends

`VKWebAppGetFriends` показывает окно выбора друзей из списка и получает информацию о них.

## Пример

```JavaScript
bridge.send('VKWebAppGetFriends')
  .then((data) => { 
    if (data.users) {
      // Данные о пользователях получены
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `multi` &#x0d;&#x0a;*обязательное* | `boolean` | Информация о том, выбрать ли нескольких друзей из списка или одного. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `false` — выбор одного друга из списка (значение по умолчанию).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `true` — выбор нескольких друзей из списка. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetFriendsResult` и `VKWebAppGetFriendsFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.
* `User denied`, если пользователь закрыл окно выбора друзей.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `users` | `array[object]` | Массив объектов пользователей. Объект содержит следующие поля:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `id` (`integer`) — идентификатор пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `first_name` (`string`) — имя пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `last_name` — фамилия пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `sex` — пол пользователя. Возможные значения: &#x0d;&#x0a; &nbsp;&nbsp;&nbsp;&nbsp; &bullet; `1` — женский.&#x0d;&#x0a; &nbsp;&nbsp;&nbsp;&nbsp; &bullet; `2` — мужской.&#x0d;&#x0a; &nbsp;&nbsp;&nbsp;&nbsp; &bullet; `0` — пол не указан.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `photo_200` — URL квадратной фотографии пользователя с шириной 200 пикселей. Если у пользователя отсутствует фотография, возвращается `https://vk.com/images/camera_200.png`. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### `VKWebAppGetFriendsResult`

Сигнализирует, что данные о пользователях получены. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetFriendsResult",
    data: {
      users: [
        {
          id: 743784479,
          sex: 2,
          last_name: "Хомяк",
          first_name: "Сеня",
          photo_200: "https://sun1-88.userapi.com/s/v1/ig2/ffZYc9qa-E8wPmfGsv-7erYVc83oWBUPeZjY0KSt7i7mkJ6y5YgwrNVs8K9E8TfCK8PuWXhu3l6O5cyCnlUSUCl3.jpg?size=200x200&quality=96&crop=26,26,204,204&ava=1"
        },
        {
          id: 743784474,
          sex: 2,
          last_name: "Рыжий",
          first_name: "Персик",
          photo_200: "https://sun1-91.userapi.com/s/v1/ig2/Dcf-SWu7nVYDDldq9oQegiC06VqsSa43-HpDxzPjrvFCUUk9nSevY2Uf9xzm0bxvLfgsTOH6XiiW-zeLcDhPDj_w.jpg?size=200x200&quality=96&crop=26,26,204,204&ava=1"
        }
      ]
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetFriendsFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppGetFriends](https://vk.cc/bZflVs)


VK Bridge | Пользователи | VKWebAppGetFriends

# VKWebAppGetGeodata

`VKWebAppGetGeodata` показывает окно с запросом доступа к местоположению пользователя и получает эти данные.

## Пример

```JavaScript
bridge.send('VKWebAppGetGeodata')
  .then((data) => { 
    if (data.available) {
      // Местоположение получено
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

—

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetGeodataResult` и `VKWebAppGetGeodataFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
|---|---|---|
 |`available` | `boolean` или `integer` | Информация о том, доступны ли приложению данные о текущем местоположении пользователя. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `true` или `1` — данные доступны мини-приложению.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `false` или `0` — данные недоступны мини-приложению (остальные поля не возвращаются). Это означает, что пользователь разрешил передавать данные мини-приложению, но запретил доступ к геолокации в настройках операционной системы. |
 |`lat`| `double` | Географическая широта в градусах. Диапазон возможных значений: от `-90` до `90`. |
 |`long` | `double` | Географическая долгота в градусах. Диапазон возможных значений: от `-180` до `180`. |
 |`accuracy` | `double` | Радиус окружности, которая обозначает границу, внутри которой находится пользователь. Широта и долгота — это центр круга, а `accuracy` — его радиус, заданный в метрах. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppGetGeodataResult`

Сигнализирует, что местоположение получено. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetGeodataResult",
    data: {
      available: true,
      lat: 78.0217862,
      long: 76.2881822,
      accuracy: 15.024
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetGeodataFailed`

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

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppGetGeodata](https://vk.cc/bXLRid)


VK Bridge | Пользователи | VKWebAppGetGeodata

# VKWebAppGetGroupInfo

`VKWebAppGetGroupInfo` получает информацию о сообществе.

## Пример

```JavaScript
bridge.send('VKWebAppGetGroupInfo', {
  group_id: 166562603
  })
  .then((data) => { 
    if (data.id) {
      // Данные о сообществе получены
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `group_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор сообщества. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetGroupInfoResult` и `VKWebAppGetGroupInfoFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `id` | `integer` | Идентификатор сообщества. |
| `name` | `string` | Название сообщества. |
| `screen_name` | `string` | Короткий адрес. |
| `is_closed` | `integer` | Информация о том, является ли сообщество закрытым. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `0` — открытое.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `1` — закрытое.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `2` — частное. |
| `description` | `string` | Описание сообщества. |
| `members_count` | `integer` | Количество участников сообщества. |
| `photo_50` | `string` | URL квадратной фотографии сообщества с шириной 50 пикселей. Если у сообщества отсутствует фотография, возвращается `https://vk.com/images/community_50.png`. |
| `photo_100` | `string` | URL квадратной фотографии сообщества с шириной 100 пикселей. Если у сообщества отсутствует фотография, возвращается `https://vk.com/images/community_100.png`. |
| `photo_200` | `string` | URL квадратной фотографии сообщества с шириной 200 пикселей. Если у сообщества отсутствует фотография, возвращается `https://vk.com/images/community_200.png`. |
| `photo_400` | `string` | URL квадратной фотографии сообщества максимального размера. Если у сообщества отсутствует фотография, возвращается `https://vk.com/images/community_200.png`. |
| `is_member` | `integer` | Информация о том, является ли текущий пользователь участником сообщества. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `1` — является.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `0` — не является. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppGetGroupInfoResult`

Сигнализирует, что данные сообщества получены. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetGroupInfoResult",
    data: {
      id: 166562603,
      name: "VK Mini Apps",
      screen_name: "vkappsdev",
      is_closed: 0,
      description: "Документация\n• VK Mini Apps и не только: dev.vk.com/guide\n• VKUI: vkcom.github.io/vkui-styleguide\n\nМакеты VKUI в Figma\n• figma.com/@vk\n\nБыстрое создание приложения\n• dev.vk.com/mini-apps/getting-started\n• npmjs.com/package/@vkontakte/create-vk-mini-app\n\nХостинг статики\n• npmjs.com/package/@vkontakte/vk-miniapps-deploy\n\nПолезные материалы\n• vk.com/@vkappsdev-poleznye-materialy\n• vk.com/@vkappsdev\n\nПесочница событий VK Bridge\n• vk.com/sandbox_app \n\nОбсуждения\n• VK Mini Apps: vk.com/topic-166562603_40071994\n• VKUI: vk.com/topic-166562603_40072026",
      members_count: 52104,
      photo_50: "https://sun1-95.userapi.com/s/v1/if1/SrTI7tgAv79jphLz5OHUTFRzURtWS0axJCL1cSIFzI5p8Ja7iJm1dKN-4SiGEdQJQOiBENHX.jpg?size=50x50&quality=96&crop=100,100,599,599&ava=1",
      photo_100: "https://sun1-95.userapi.com/s/v1/if1/7R1EtxtmMuhQSfGVD4Vt5Bzeq5TqHgpCCYG0hDi3RsIwfdOEiCht65OC_q1qOx1vfZIVHbn5.jpg?size=100x100&quality=96&crop=100,100,599,599&ava=1",
      photo_200: "https://sun1-95.userapi.com/s/v1/if1/MTmSdynigJoHXdY0krbacTurak0PmEfuhkT0c1aIKnRhgACEi1v0je0guGvhnnc1rZnQ6sZb.jpg?size=200x200&quality=96&crop=100,100,599,599&ava=1",
      photo_400: "https://sun1-95.userapi.com/s/v1/if1/_pd7kU0FVnLSN_a_W8U77BFyGa_qmXK0lDTKlRVnelRfHbmKr0RroAEoZ0jtm5ypMZKj2lbq.jpg?size=200x200&quality=96&crop=26,26,748,748&ava=1"
      is_member: 1
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetGroupInfoFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppGetGroupInfo](https://vk.cc/bZfonS)


VK Bridge | Сообщества | VKWebAppGetGroupInfo

# VKWebAppGetPersonalCard

`VKWebAppGetPersonalCard` вызывает карточку контактов пользователя с полями, которые вы запросили. Мобильное приложение показывает экран с запросом доступа к выбранным данным.

**Карточка контактов** — это место, где пользователь сохраняет контактные данные (номер телефона, адрес, email), которыми он готов поделиться с сервисами сторонних разработчиков.

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

## Пример

```JavaScript
bridge.send('VKWebAppGetPersonalCard', {
  type: [
    'phone',
    'email',
    'address'
  ]})
  .then((data) => { 
    if (data.phone) {
      // Данные получены
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS

## Параметры

| Поле | Тип | Описание |
|---|---|---|
| `type` &#x0d;&#x0a;*обязательное* | `array[string]` | Массив доступов. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `phone` — номер телефона пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `email` — электронный адрес пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `address` — физический адрес пользователя. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetPersonalCardResult` и `VKWebAppGetPersonalCardFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.
* `User denied`, если пользователь запретил доступ к данным.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `phone` | `string` | Номер телефона пользователя. |
| `email` | `string` | Электронный адрес пользователя. |
| `address` | `object` | Информация об адресе пользователя. Поля объекта:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `city` (`object`) —  город пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `country` (`object`) — страна пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `specified_address` (`string`) — точный адрес, указанный пользователем.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `postal_code` (`string`) — почтовый индекс.&#x0d;&#x0a;&#x0d;&#x0a; Поля объекта `country`:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `id` (`integer`) — идентификатор страны.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `title` (`string`) — название страны.&#x0d;&#x0a;&#x0d;&#x0a; Поля объекта `city`:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `id` (`integer`) — идентификатор города.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `title` (`string`) — название города. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppGetPersonalCardResult`

Сигнализирует, что данные получены. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetPersonalCardResult",
    data: {
      phone: "79111234567",
      email: "persik_ryzhiy@mail.ru"
      address: {
        country: {
          id: 1,
          name: "Россия"
        },
        city: {
          id: 2,
          name: "Санкт-Петербург"
        },
        specified_address: "Невский пр., д. 28"
        postal_code: "191186"
      }
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetPersonalCardFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | Пользователи | VKWebAppGetPersonalCard

# VKWebAppGetPhoneNumber

`VKWebAppGetPhoneNumber` показывает окно с запросом доступа к номеру телефона пользователя.

> **Совет.** Если вам требуется запросить не только номер телефона, но и адрес электронной почты, используйте вызов [карточки контактов](bridge/VKWebAppGetPersonalCard).

## Пример

```JavaScript
bridge.send('VKWebAppGetPhoneNumber')
  .then((data) => { 
    if (data.phone_number) {
      // Номер телефона получен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Web

## Параметры

—

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetPhoneNumberResult` и `VKWebAppGetPhoneNumberFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.
* `User denied`, если пользователь запретил доступ к номеру телефона.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `phone_number` | `string` | Номер телефона пользователя. |
| `sign` | `string` | Подпись полученных данных. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppGetPhoneNumberResult`

Сигнализирует, что номер телефона получен. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppGetPhoneNumberResult",
    data: {
      sign: "YdUTMy8uAmFXUqzMsAUjYFTZ1cUfhRJBpTjmqgZBCtg",
      phone_number: "79111234567" 
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetPhoneNumberFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Вычисление подписи

Для подписи последовательно объединяются значения:

* Идентификатор мини-приложения `app_id`.
* [Защищённый ключ](mini-apps/management/settings#Защищённый%20ключ) `api_secret`.
* Идентификатор пользователя `user_id`.
* Пара `$field_name.$field_value`, вернувшаяся в событии.

От полученной после объединения строки вычисляется криптографический хеш SHA256 в байтовом представлении, затем хеш кодируется с помощью алгоритма Base64 Encode.

Пример формирования подписи события на PHP, где `app_id = 7770000`, `api_secret = W7kVvxVxZ4`, `user_id = 162447`, `field_name = phone_number`, `field_value = 70000000000`:

```PHP
$sign = rtrim(strtr(base64_encode(hash('sha256', '7770000W7kVvxVxZ4162447phone_number70000000000', true)), '+/', '-_'), '=');
```

## Песочница

[VKWebAppGetPhoneNumber](https://vk.cc/bZfjAn)


VK Bridge | Пользователи | VKWebAppGetPhoneNumber

# VKWebAppGetUserInfo

`VKWebAppGetUserInfo` получает данные о профиле пользователя, который запустил мини-приложение.

## Пример

```JavaScript
bridge.send('VKWebAppGetUserInfo', {
  user_id: 743784474
  })
  .then((data) => { 
    if (data.id) {
      // Данные пользователя получены
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `user_id`  &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор пользователя. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppGetUserInfoResult` и `VKWebAppGetUserFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `id` | `integer` | Идентификатор пользователя. |
| `bdate` | `string` | Дата рождения пользователя. Например 10.4.1990 или 10.4 (если год рождения скрыт). Если дата рождения скрыта целиком, поле в ответе отсутствует. |
| `bdate_visibility` | `integer` | Информация о том, отображается ли дата рождения пользователя. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `1` — дата рождения открыта целиком.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `2` — открыты только день и месяц даты рождения.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `0` — дата рождения скрыта. |
| `city` | `object` | Информация о городе пользователя. Объект, который содержит поля:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `id` (`integer`) — идентификатор города.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `title` (`string`) — название города. |
| `country` | `object` | Информация о стране пользователя. Объект, который содержит поля:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `id` (`integer`) — идентификатор страны.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `title` (`string`) — название страны. |
| `photo_200` | `string` | URL квадратной фотографии пользователя с шириной 200 пикселей. Если у пользователя отсутствует фотография, возвращается `https://vk.com/images/camera_200.png`. |
| `photo_max_orig` | `string` | URL фотографии максимального размера. Может быть возвращена фотография, имеющая ширину как 400, так и 200 пикселей. Если у пользователя отсутствует фотография, возвращается `https://vk.com/images/camera_400.png`. |
| `sex` | `integer` | Пол пользователя. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `1` — женский.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `2` — мужской.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `0` — пол не указан. |
| `photo_100` | `string` | URL квадратной фотографии пользователя с шириной 100 пикселей. Если у пользователя отсутствует фотография, возвращается `https://vk.com/images/camera_100.png`. |
| `first_name` | `string` | Имя пользователя. |
| `last_name` | `string` | Фамилия пользователя. |
| `can_access_closed` | `boolean` | Информация о том, может ли пользователь, который открыл мини-приложение, видеть закрытый профиль пользователя. |
| `is_closed` | `boolean` | Информация о том, закрыт ли профиль пользователя. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### `VKWebAppGetUserInfoResult`

Сигнализирует, что данные пользователя получены. В обработчик события на стороне пользователя передаются следующие данные:

```JavaScript
{
  detail: {
    type: "VKWebAppGetUserInfoResult",
    data: {
      id: 743784474,
      bdate: "21.12.2000",
      bdate_visibility: 1,
      city: {
        id: 2,
        title: "Санкт-Петербург"
      },
      country: {
        id: 1,
        title: "Россия"
      },
      photo_200: "https://sun1-91.userapi.com/s/v1/ig2/Dcf-SWu7nVYDDldq9oQegiC06VqsSa43-HpDxzPjrvFCUUk9nSevY2Uf9xzm0bxvLfgsTOH6XiiW-zeLcDhPDj_w.jpg?size=200x200&quality=96&crop=26,26,204,204&ava=1",
      photo_max_orig: "https://sun1-91.userapi.com/s/v1/ig2/trHNebJQhG4BmLxC8h4hOpDU6bKRy6uJi586wcyFcCj5fzrwYk7AtoNab-RSil0Bp9b569VQyGK_skG9e6oK7Ap7.jpg?size=256x256&quality=96&crop=0,0,256,256&ava=1",
      sex": 2,
      photo_100: "https://sun1-91.userapi.com/s/v1/ig2/M4vtl7tcmeP6ANUgE0vU7JZWuJszbHaN5QcCcK2xD66EIc6SeSA1NyFVLTSOt2iLOkFhJSJ4DawEJGOjzKtszMpR.jpg?size=100x100&quality=96&crop=26,26,204,204&ava=1",
      first_name: "Персик",
      last_name: "Рыжий",
      can_access_closed: true,
      is_closed: false
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppGetUserInfoFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppGetUserInfo](https://vk.cc/bZfhUc)


VK Bridge | Пользователи | VKWebAppGetUserInfo

# VKWebAppInit

`VKWebAppInit` — первое событие, которое ваше приложение должно отправить приложению ВКонтакте для начала работы с VK Bridge. Если это событие не вызвать, ваше мини-приложение или игра не будет работать в мобильных приложениях для iOS и Android, а также в мобильной и десктопной версиях ВКонтакте.

## Пример

```JavaScript
bridge.send('VKWebAppInit')
  .then((data) => { 
    if (data.result) {
      // Приложение инициализировано
    } else {
      // Ошибка
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

—

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppInitResult` и `VKWebAppInitFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если вызов к платформе прошёл успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если приложение инициализировано.&#x0d;&#x0a;`false` — в ином случае. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### `VKWebAppInitResult`

Сигнализирует, что приложение инициализировано. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppInitResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppInitFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

VK Bridge | Инициализация | VKWebAppInit

# VKWebAppOpenApp

`VKWebAppOpenApp` открывает другое приложение (мини-приложение или игру) из текущего приложения (мини-приложения или игры).

## Пример

```JavaScript
bridge.send('VKWebAppOpenApp', {
  app_id: 6909581,
  location: 'test'
  })
  .then((data) => { 
    if (data.result) {
      // Приложение открыто
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `app_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор приложения, которое нужно открыть. |
| `location` &#x0d;&#x0a;*необязательное* | `string` | Хеш — строка после символа `#` в URL вида `vk.com/app6909581#`. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppOpenAppResult` и `VKWebAppOpenAppFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение или игра запущены в фоновом режиме.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если приложение открыто. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppOpenAppResult`

Сигнализирует, что приложение открыто. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppOpenAppResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppOpenAppFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppOpenApp](https://vk.cc/bZftvr)


VK Bridge | Общие события | VKWebAppOpenApp

# VKWebAppOpenPayForm

`VKWebAppOpenPayForm` показывает экран [VK Pay](pay/getting-started) для совершения платежа.

:::note
**Примечание.** Если пользователь ещё не завёл аккаунт VK Pay, при первом вызове ему будет предложено ввести данные для регистрации.
:::

## Пример

```JavaScript
bridge.send('VKWebAppOpenPayForm', {
    app_id: 6909581,
    action: 'pay-to-user',
    params: {
      user_id: 743784474
    }})
  .then((data) => {
    if (data.status) {
      // Экран VK Pay показан
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `app_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор мини-приложения. |
| `action` &#x0d;&#x0a;*обязательное* | `string` | Тип перевода внутри VK Pay. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `pay-to-service` — перевод денежных средств сервису. Доступно только организациям, подключённым через [форму для юридических лиц](https://vk.cc/9CJwZW). Прочтите также документацию, описывающую [расширенный набор параметров](pay/getting-started).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `pay-to-user` — перевод фиксированных денежных средств пользователю.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `pay-to-group` — перевод фиксированных денежных средств сообществу. Денежные средства будут переведены на баланс получателя, указанного в управлении сообществом.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `transfer-to-group` — перевод произвольных денежных средств сообществу.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `transfer-to-user` — перевод произвольных денежных средств пользователю. |
| `params` &#x0d;&#x0a;*обязательное* | `object` | Параметры платёжной формы VK Pay. Формат и параметры зависят от [типа перевода](pay/getting-started). |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppOpenPayFormResult` и `VKWebAppOpenPayFormFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение или игра запущены в фоновом режиме.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `status` | `boolean` | Информация о том, успешно ли выполнен платёж. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `true` — платёж выполнен успешно.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `false` — произошла ошибка. |
| `transaction_id` | `string` | Идентификатор транзакции в платёжной системе. Поле возвращается, если поле `status` имеет значение `true`. |
| `amount` | `string` | Сумма платежа. |
| `extra` | `string` | Дополнительные данные о продавце. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppOpenPayFormResult`

Сигнализирует, что экран VK Pay показан. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppOpenPayFormResult",
    data: {
      status: true,
      transaction_id: "1234ABCD-EEEE-5678-90FG-ABCDEF123456",
      amount: "120.5",
      extra: "{\"currency\":\"RUB\",\"merchant_data\":\"some_merchant_data\",\"merchant_sign\":\"some_sign\",\"order_id\":\"some_order_id\",\"ts\":1641999488}\""
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppOpenPayFormFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

# Песочница

[VKWebAppOpenPayForm](https://vk.cc/bZfweB)


VK Bridge | Платежи | VKWebAppOpenPayForm

# VKWebAppOpenWallPost

`VKWebAppOpenWallPost` открывает в отдельном окне (поверх мини-приложения или игры) запись, опубликованную на стене пользователя или сообщества.

## Пример

```JavaScript
bridge.send('VKWebAppOpenWallPost', {
  owner_id: -166562603,
  post_id: 4604
  })
  .then((data) => { 
    if (data.result) {
      // Окно с записью открыто
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `owner_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор сообщества (отрицательное число) или пользователя (положительное число), на стене которого опубликована запись. |
| `post_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор записи на стене (положительное число). |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppOpenWallPosttResult` и `VKWebAppOpenWallPostFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если окно с записью открыто. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.


### События

#### `VKWebAppOpenWallPostResult`

Сигнализирует, что окно с записью открыто. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppOpenWallPostResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppOpenWallPostFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppOpenWallPost](https://vk.cc/bZftTD)


VK Bridge | Общие события | VKWebAppOpenWallPost

# VKWebAppShowNativeAds

`VKWebAppShowNativeAds` показывает [рекламу](games/monetization/ad/overview) пользователям в играх и мини-приложениях. Параметры вызова задают [вид желаемой рекламы](games/monetization/ad/overview#Виды%20рекламы%20в%20играх).

Если на стороне пользователя нет рекламных материалов желаемого типа, то [VK&nbsp;Bridge](bridge/overview) запрашивает материалы у платформы ВКонтакте и показывает рекламу после её получения.

## Пример

```JavaScript
bridge.send('VKWebAppShowNativeAds', {
  ad_format: 'interstitial' /* Тип рекламы */
  })
  .then( (data) => { 
    if (data.result) {
      // Реклама была показана
    } else {
      // Ошибка
    }
  })
  .catch((error) => { console.log(error); });
```

#### Другие примеры

* [Реклама за вознаграждение](games/monetization/ad/implementation#Пример%20показа%20рекламы%20за%20вознаграждение)

* [Реклама между экранами](games/monetization/ad/implementation#Пример%20показа%20рекламы%20между%20экранами)

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

В качестве параметров события `VKWebAppShowNativeAds` передайте в [`bridge.send(...)`](bridge/getting-started#Вызов%20события%20VK%20Bridge) объект со следующими полями:

| Параметр | Тип | Описание |
| --- | --- | --- |
| `ad_format` | `string` | [Вид](games/monetization/ad/overview#Виды%20рекламы%20в%20играх) рекламы для показа. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `reward` — [реклама за вознаграждение](games/monetization/ad/overview#Реклама%20за%20вознаграждение).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `interstitial` — [реклама между экранами](games/monetization/ad/overview#Реклама%20между%20экранами). |
| `use_waterfall` | `boolean` | Применим только при `ad_format: 'reward'`. Сообщает ВКонтакте, можно ли использовать рекламные материалы вида `interstitial` в случае отсутствия материалов вида `reward`.&#x0d;&#x0a;Значение по умолчанию: `true`. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppShowNativeAdsResult` и `VKWebAppShowNativeAdsFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, то управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если реклама была показана, или `false` в ином случае. |

Если при обращении к платформе произошла ошибка, то управление передаётся в метод `catch`. Это происходит, например, если было задано некорректное значение в параметре `ad_format`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20результата), общий для всех методов VK Bridge.

### События

#### `VKWebAppShowNativeAdsResult`

Сигнализирует, что параметры вызова были корректны и что библиотека VK Bridge пытается отобразить рекламу пользователю.

В обработчик события на стороне пользователя передаются следующие данные:

```JavaScript
{
  detail: 
  {
    type: "VKWebAppShowNativeAdsResult",
    data:{
      result : true,
      request_id: 5 
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppShowNativeAdsFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой, например при использовании некорректных значений параметров запроса. В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20результата), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Примечания

* Перед показом рекламы VK Brdige проверяет, есть ли предзагруженные рекламные материалы указанного типа. Если такие материалы есть, VK Bridge показывает их. Если предзагруженных материалов нет, то библиотека отправляет запрос на их загрузку и показывает полученный контент.

  В общем случае это может приводить к задержке при показе. Чтобы избежать её, используйте [предзагрузку рекламных материалов](games/monetization/ad/implementation).
  
  Запрос не гарантирует, что материалы будут загружены. Сбои в сети или проблемы на стороне рекламной платформы могут привести к тому, что контент не будет получен.

* Сразу после успешного показа рекламы VK Bridge отправляет запрос на предзагрузку следующей порции рекламных материалов.

## Песочница

* Игры: [VKWebAppShowNativeAds](https://vk.cc/bZfCRH)

* Мини-приложения: [VKWebAppShowNativeAds](https://vk.com/app6909581#VktXZWJBcHBTaG93TmF0aXZlQWRzQCU3QiUyMmFkX2Zvcm1hdCUyMiUzQSUyMnByZWxvYWRlciUyMiU3RA)

## Материалы по теме

* [Подробнее о работе с VK Bridge](bridge/getting-started)

* [Реклама в играх](games/monetization/ad/overview)

* [Реклама в мини-приложениях](mini-apps/monetization/ads)

* [VKWebAppCheckNativeAds](bridge/VKWebAppCheckNativeAds)


VK Bridge | Реклама | VKWebAppShowNativeAds

# VKWebAppShowStoryBox

`VKWebAppShowStoryBox` открывает редактор историй.

## Пример

```JavaScript
bridge.send("VKWebAppShowStoryBox", { 
  "background_type" : "image", 
  "url" : "https://sun9-65.userapi.com/c850136/v850136098/1b77eb/0YK6suXkY24.jpg"
});

```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

* `background_type` (`string`, обязательный)
Тип истории. Возможные значения: 
`image` (платформы: iOS, Android, Web, Mobile Web);
`video` (платформы: iOS, Android);
`none` (для случая передачи стикера непосредственно на камеру, платформы: iOS, Android). 
* `url` (`string`)
Ссылка на изображение или видео (нужно указать прямую ссылку на MP4).
* `blob` (`string`)
Base64-строка с BLOB (поддерживается только для `image`). Перед строкой необходимо добавить следующий префикс: `data:image/png;base64,<blob-base64>` или `data:image/jpeg;base64,<blob-base64>` в зависимости от типа изображения. 
* `locked` (`bool`)
Можно ли перемещать фотографию. 
* `attachment` (`attachment`) 
Описание [объекта, присоединённого к истории.](#Объект%20attachment) 
* `stickers` (`sticker_container []`)
Массив [объектов `sticker_container`](#Объект%20sticker_container). 

## Результат

После начала загрузки истории возвращается событие `VKWebAppShowStoryBoxResult`.

```JSON
{
  "type": "VKWebAppShowStoryBoxResult",
  "data": {
    "result": true
  }
}
```

После успешной загрузки истории возвращается событие `VKWebAppShowStoryBoxLoadFinish`.

```JSON
{
  "type": "VKWebAppShowStoryBoxLoadFinish",
  "data": {
    "story_owner_id": 212424,
    "story_id": 123322,
  }
}
```

`VKWebAppShowStoryBoxLoadFinish` будет работать только при наличии `request_id`.

В случае неудачи возвращается событие `VKWebAppShowStoryBoxFailed`.

```JSON
{ 
  "type": "VKWebAppShowStoryBoxFailed", 
  "data": {
     "error_type": "..."
     "error_data": {
        ...
     }
  }
}
```

## Объект `sticker_container`

* `sticker_type` (`string`, обязательный)
Тип стикера. Возможные значения:
`native`,
`renderable`. 
* `sticker` (`renderable_sticker` или `native_sticker`, обязательный) 
Объект cтикера. См. [`renderable_sticker`](#Объект%20renderable_sticker).

## Объект `service_info`

* `mask_id` (`string`)
Полный ID маски в формате ${owner_id}_${mask_id}. Например: 148038958_18424.
* `effect_id` (`string`)
Полный ID эффекта в формате ${owner_id}_${effect_id}.
* `user_id_birthday` (`int`)
ID пользователя, у которого день рождение.
* `open_text_editor` (`boolean`)
Открытие текстового редактора при переходе в камеру (с готовой историей, background != none), по умолчанию `false`.
* `situational_suggest_id` (`int`)
ID события от пользователя.


## Объект `native_sticker`

* `action_type` (`string`, обязательный)
Тип стикера. Возможные значения:
`text`, 
`hashtag`, 
`mention`, 
`time`, 
`place`, 
`question`, 
`emoji`, 
`sticker`, 
`market_item`. 
* `action` (`action_*`, обязательный)
Данные для стикера.
* `transform` (`transform`)
Описание объекта трансформации объекта.
* `can_delete` (`boolean`)
Может ли стикер быть удален с экрана, по умолчанию `true`.

## Объект `attachment`

* `text` (`string`, обязательный) 
Ключ для текста кнопки (см. `link_text` в [`stories.getVideoUploadServer`](method/stories.getVideoUploadServer))
* `type` (`string`, обязательный)
Тип объекта. Возможные значения: 
`url`, 
`audio`,
`video`, 
`photo`. 
* `url` (`string`) 
Ссылка на объект.
* `owner_id` (`int`)
Идентификатор владельца объекта. 
* `id` (`int`) 
Идентификатор объекта. 
* `access_key` (`string`) 
Ключ доступа для вложения. 

## Объект `renderable_sticker`

* `content_type` (`string`, обязательный)
Тип истории. Возможное значение: 
`image`,
`gif` (в формате webp),
`video` (не поддержан на клиентах).
* `url` (`string`)
Ссылка на контент. Обязательна, если не указано поле `blob`. 
* `blob` (`string`)
Base64-строка с BLOB. Обязательна, если не указано поле `url`. 
* `transform` (`transform`)
[Описание возможностей трансформации объекта.](#Объект%20transform) 
* `clickable_zones` (`clickable_zone []`)
[Массив областей контента, нажатие на которые может вызвать какое-либо действие.](#Объект%20clickable_zone) [См. объекты `action`](#Объекты%20action). 
* `can_delete` (`bool`)
Может ли стикер быть удалён с экрана, по умолчанию `true`. 

## Объект `clickable_zone`

* `action_type` (`string`, обязательный)
Описывает тип действия на нажатие. Возможные значения: 
`app`,
`hashtag`,
`mention`,
`link`,
`place`,
`question`,
`market_item`.
* `action` (`action`, обязательный)
[Необходимые данные для действия.](#Объекты%20action)
* `clickable_area` (`clickable_area_coordinate []`)
[Граница зоны стикера, на которую можно нажать.](#Объект%20clickable_area_coordinate) Точки должны располагаться по часовой стрелке, образуя замкнутый квадрат. 

## Объект `clickable_area_coordinate`

* `x` (`int`, обязательный)
Координата X (от 0 до ширины переданного контента). 
* `y` (`int`, обязательный)
Координата Y (от 0 до высоты переданного контента). 

## Объект `transform`

* `rotation` (`int`)
Градусы. От 0 до 359. Вращение против часовой стрелки. 
* `relation_width` (`float`) 
Желаемая ширина стикера относительно экрана — (`0`, `1`), высота будет рассчитана с учётом сохранения соотношения сторон контента. 
* `translation_x` (`float`) 
От -1 до 1. От ширины экрана. 
* `translation_y` (`float`)
 От -1 до 1. От высоты экрана. 
* `gravity` (`string`)
Расположение. По умолчанию: `center`. Возможные значения: 
 `left_top`,
 `left_center`, 
 `left_bottom`,
 `center_top`,
 `center`,
 `center_bottom`,
 `right_top, right_center`,
 `right_bottom`.

Для расчёта итоговой позиции:
x = начальная_позиция_x + `artboard_width` *  `translation_x`
y = начальная_позиция_y + `artboard_height` *  `translation_y`

## Объекты `action`

### Объект `action_link`

> В ближайшем будущем объект `action_link` перестанет поддерживаться. Вместо него рекомендуем использовать `action_app`.

 * `link` (`string`, обязательный)
Ссылка на объект. 
* `tooltip_text_key` (`string`)
Значение строки, которая будет отображаться на клиенте при нажатии на тултип. Возможные значения: 
`tooltip_open_post` — открыть запись, 
`tooltip_open_photo` — открыть фотографию, 
`tooltip_open_page` — открыть страницу, 
`tooltip_open_default` — перейти (по умолчанию). 

### Объект `action_app`

* `app_id` (`int`, обязательный)
Идентификатор приложения. 
* `app_context` (`string`)
Если приложение открывается из истории, то [в параметрах запуска](mini-apps/development/launch-params), в `vk_ref`, приходит значение `story{owner_id}_{story_id}_{access_key}_{sticker_id}_{context}`. `context` — Base64-строка, максимум — 500 символов.


### Объект `action_hashtag`

* `hashtag` (`string`, обязательный)
Текст хештега.
* `style` (`string`)
Стиль хештега. По умолчанию: `blue_gradient`. Возможные значения: 
`transparent`,
`blue_gradient`.


### Объект `action_mention`

* `mention` (`string`, обязательный)
Текст в формате меншена: для профилей людей "[id123|name]", для групп/сообществ/событий - "[club123|name]".
* `style` (`string`)
Стиль хештега. По умолчанию: `red_gradient`. Возможные значения: 
`transparent`,
`red_gradient`.

### Объект `action_place`

* `place_id` (`integer`, обязательный)
ID места.
* `title` (`string`, обязательный)
Название места.
* `category_id` (`integer`)
ID категории места.
* `style` (`string`)
Стиль. По умолчанию: `blue`. Возможные значения:
`transparent`,
`blue`,
`green`,
`white`.

### Объект `action_time`

* `style` (`string`)
Стиль стикера времени. По умолчанию: date. Возможные значения:
`black`,
`white`,
`green`,
`text`,
`date`.
* `timestamp_ms` (`long`)
Unix timestamp в миллисекундах.
* `date` (`string`)
Дата (альтернатива timestamp_ms) в формате yyyy:MM:dd HH:mm:ss (такой формат выбран для унификации даты из exif полей).
* `title` (`string`)
Верхний тайтл стикера, значим только для стиля `date`.

### Объект `action_question`

* `place_id` (`integer`, обязательный)
ID места.
* `title` (`string`, обязательный)
Название места.
* `category_id` (`integer`)
ID категории места.
* `style` (`string`)
Стиль. По умолчанию: `blue`. Возможные значения:
`transparent`,
`blue`,
`green`,
`white`.

### Объект `action_text`

* `text` (`string`, обязательный)
Текст, может содержать меншены/хештеги в форматах указанных с соответствующих объектах.
* `style` (`string`)
Стиль текста. Возможные значения: 
`classic`,
`cursive`,
`marker`,
`italics`,
`typewriter`,
`poster`,
`retro`.
* `background_style` (`string`)
Стиль фона/обводки. По умолчанию: `none`. Применимость стиля фона зависит от исходного стиля текста. Возможные значения:
`none`,
`alpha`,
`solid`,
`sticker`,
`neon`.
* `alignment` (`string`)
Выравнивание. Возможные значения: 
`center`,
`left`,
`right`.
* `selection_color` (`string`)
Цвет в формате: #ff0000. Если `background_style` задан `none`, то значение будет определять цвет текста, иначе будет означать цвет, применяемый к стилю.

#### Поддерживаемые стили фона относительно стиля текста

| Имя `style` | Поддерживаемые `background_style` |
|---|---|
| classic | none, solid, alpha, sticker |
| cursive | none, solid |
| marker | none, neon |
| italics | none, solid |
| typewriter | none, solid |
| poster | none, solid |
| retro | none, solid |

### Объект `action_emoji`

* `emoji` (`string`, обязательный)
Символ emoji.

### Объект `action_sticker`

* `sticker_id` (`int`, обязательный)
ID стикера.
* `pack_id` (`int`, обязательный)
ID набора стикера.

### Объект `action_market_item`

* `title` (`string`, обязательный)
Текст для тайтла товара.
* `product_id` (`int`)
ID продукта для товаров ВКонтакте.
* `owner_id` (`int`)
ID владельца для товаров ВКонтакте.
* `link` (`string`)
Ссылка на товар aliexpress.

## Объект `poll`

* `poll_id` (`int`, обязательный)
ID опроса.
* `owner_id` (`int`)
ID владельца.
* `is_board` (`Boolean`)
Из обсуждений ли опрос.

## Пример объекта `story_box`

```JSON
{
  "background_type": "image",
  "url": "https://sun9-65.userapi.com/c850136/v850136098/1b77eb/0YK6suXkY24.jpg",
  "stickers": [
    {
      "sticker_type": "renderable",
      "sticker": {
        "can_delete": 0,
        "content_type": "image",
        "url": "https://upload.wikimedia.org/wikipedia/commons/c/c7/Dialog.png",
        "clickable_zones": [
          {
            "action_type": "link",
            "action": {
              "link": "https://vk.com/wall-166562603_1192",
              "tooltip_text_key": "tooltip_open_post"
            },
            "clickable_area": [
              {
                "x": 17,
                "y": 110
              },
              {
                "x": 97,
                "y": 110
              },
              {
                "x": 97,
                "y": 132
              },
              {
                "x": 17,
                "y": 132
              }
            ]
          }
        ]
      }
    }
  ]
}
```

## Песочница

[VKWebAppShowStoryBox](https://vk.cc/bZfCnr)

VK Bridge | Редактор историй | VKWebAppShowStoryBox

# VKWebAppShowWallPostBox

`VKWebAppShowWallPostBox` показывает окно с предложением разместить запись на стене пользователя.

## Пример

```JavaScript
bridge.send('VKWebAppShowWallPostBox', {
  message: 'Hello!',
  attachments: 'https://habr.com'
  })
  .then((data) => { 
    if (data.post_id) {
      // Запись размещена
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

Все параметры подробно описаны в документации метода [`wall.post`](method/wall.post).

:::note
**Примечание.** К записи можно добавить только одну ссылку. В URL ссылки необходимо указать протокол (HTTP или HTTPS).
:::

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppShowWallPostBoxResult` и `VKWebAppShowWallPostBoxFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `post_id` | `integer` | Идентификатор записи. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### `VKWebAppShowWallPostBoxResult`

Сигнализирует, что запись размещена. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppShowWallPostBoxResult",
    data: {
      post_id: 8982
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppShowWallPostBoxFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppShowWallPostBox](https://vk.cc/bZfuXA)


VK Bridge | Общие события | VKWebAppShowWallPostBox

# VKWebAppTapticNotificationOccurred

`VKWebAppTapticNotificationOccurred` передаёт генератору виброотклика информацию о том, что задача или действие:

* Успешно выполнено.
* Не выполнено.
* Выдало предупреждение.

В ответ генератор может воспроизводить соответствующие параметру тактильные отклики. В iOS `VKWebAppTapticNotificationOccurred` вызывает [`notificationOccurred`](https://developer.apple.com/documentation/uikit/uinotificationfeedbackgenerator/2369826-notificationoccurred) в Taptic Engine.

## Пример

```JavaScript
bridge.send('VKWebAppTapticNotificationOccurred', {
  type: 'error'
  })
  .then((data) => { 
    if (data.result) {
      // Информация передана генератору
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `type` &#x0d;&#x0a;*обязательное* | `string` | Тип информации. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `error` — ошибка.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `success` — успех.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `warning` — предупреждение. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppTapticNotificationOccurredResult` и `VKWebAppTapticNotificationOccurredFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение или игра запущены в фоновом режиме.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если информация передана генератору. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### `VKWebAppTapticNotificationOccurredResult`

Сигнализирует, что информация передана генератору. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppTapticNotificationOccurredResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppTapticNotificationOccurredFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | Виброотклик (Taptic Engine) | VKWebAppTapticNotificationOccurred

# VKWebAppTapticSelectionChanged

`VKWebAppTapticSelectionChanged` сообщает генератору виброотклика, что пользователь изменил выбор. В ответ генератор может воспроизвести соответствующие тактильные отклики.

В iOS `VKWebAppTapticSelectionChanged` вызывает [`selectionChanged`](https://developer.apple.com/documentation/uikit/uiselectionfeedbackgenerator/2374284-selectionchanged) в Taptic Engine.

:::note
**Предупреждение.** Не используйте этот тип обратной связи, если пользователь делает или подтверждает выбор. Используйте его только при изменении выбора.
:::

## Пример

```JavaScript
bridge.send('VKWebAppTapticSelectionChanged')
  .then((data) => { 
    if (data.result) {
      // Выбор пользователя изменён
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS

## Параметры

 — 
  
## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppTapticSelectionChangedResult` и `VKWebAppTapticSelectionChangedFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение или игра запущены в фоновом режиме.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если выбор пользователя изменён. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppTapticSelectionChangedResult`

Сигнализирует, что выбор пользователя изменён. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppTapticSelectionChangedResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppTapticSelectionChangedFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | Виброотклик (Taptic Engine) | VKWebAppTapticSelectionChanged

# Первые шаги

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

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

> Если ранее вы не работали с API ВКонтакте, рекомендуем прочитать раздел [Использование API](api/getting-started).
>
> Если ранее вы не работали с React, советуем ознакомиться с [документацией к библиотеке](https://ru.reactjs.org/tutorial/tutorial.html).
NPM: [`vk-bridge`](https://www.npmjs.com/package/@vkontakte/vk-bridge)

GitHub: [`vk-bridge`](https://github.com/VKCOM/vk-bridge)

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

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

1. Создайте проект мини-приложения.
1. [Подключите VK Bridge](#Подключение%20VK%20Bridge).
1. [Вызовите событие VK Bridge](#Вызов%20события%20VK%20Bridge).
1. Обработайте вернувшийся результат:
    * [Метод `bridge.send`](#Метод%20bridge.send).
    * [Метод `bridge.subscribe`](#Метод%20bridge.subscribe).

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

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

> Если вы используете [библиотеку для создания шаблона](mini-apps/getting-started#Создание%20мини-приложения), отдельно подключать библиотеку VK Bridge не нужно.

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

> **Обратите внимание!** В коде приложения обязательно нужно вызывать событие инициализации [`VKWebAppInit`](bridge/VKWebAppInit), иначе приложение не запустится.

### Через пакет NPM

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

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

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

    ```sh
    npm install @vkontakte/vk-bridge || yarn add @vkontakte/vk-bridge
    ```

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

    ```JavaScript
    import bridge from '@vkontakte/vk-bridge';

    // Отправляет событие инициализации нативному клиенту
    bridge.send("VKWebAppInit");      
    ```

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

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

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

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

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

1. В коде каждой 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/overview).

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

### Метод `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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)
>
> * [learn.javascript.ru/promise](http://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` | Тип ошибки. Возможные значения:&#x0d;&#x0a;&nbsp;&nbsp; &bullet; `client_error` — ошибки, возникающие на клиенте;&#x0d;&#x0a;&nbsp;&nbsp; &bullet; `api_error` — ошибки API;&#x0d;&#x0a;&nbsp;&nbsp; &bullet; `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"`

К этому типу относятся ошибки, перечисленные на странице [Возвращаемые ошибки](reference/errors) или в описании метода. Параметры объекта `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** позволяет приложениям использовать API ВКонтакте и API операционной системы, установленной на устройстве пользователя. В этом разделе содержится список всех событий VK Bridge.

## Как подключить и использовать

* [Руководство разработчика мини-приложений](bridge/getting-started)
* [Руководство разработчика игр](games/bridge)

## Инициализация

| Событие | Сценарий использования |
| --- | --- |
| [VKWebAppInit](bridge/VKWebAppInit) | Инициализировать VK Bridge. |

## Общие события

| Событие | Сценарий использования |
| --- | --- |
| [VKWebAppAddToFavorites](bridge/VKWebAppAddToFavorites) | Добавить приложение в избранное. |
| [VKWebAppAddToHomeScreen](bridge/VKWebAppAddToHomeScreen) | Добавить приложение на главный экран устройства. |
| [VKWebAppAddToHomeScreenInfo](bridge/VKWebAppAddToHomeScreenInfo) | Получить информацию о шорткате. |
| [VKWebAppAllowNotifications](bridge/VKWebAppAllowNotifications) | Запросить разрешение на отправку уведомлений. |
| [VKWebAppClose](bridge/VKWebAppClose) | Закрыть приложение. |
| [VKWebAppCopyText](bridge/VKWebAppCopyText) | Копировать текст в буфер обмена. |
| [VKWebAppDenyNotifications](bridge/VKWebAppDenyNotifications) | Отключить уведомления. |
| [VKWebAppDownloadFile](bridge/VKWebAppDownloadFile) | Скачать файл. |
| [VKWebAppGetClientVersion](bridge/VKWebAppGetClientVersion) | Получить номер версии приложения ВКонтакте. |
| [VKWebAppGetConfig](bridge/VKWebAppGetConfig) | Получить конфигурацию приложения. |
| [VKWebAppGetLaunchParams](bridge/VKWebAppGetLaunchParams) | Получить параметры запуска. |
| [VKWebAppOpenApp](bridge/VKWebAppOpenApp) | Открыть приложение. |
| [VKWebAppOpenCodeReader](bridge/VKWebAppOpenCodeReader) | Считать QR-код. |
| [VKWebAppOpenWallPost](bridge/VKWebAppOpenWallPost) | Открыть запись со стены в слое. |
| [VKWebAppSendToClient](bridge/VKWebAppSendToClient) | Отправить установочное уведомление на устройство. |
| [VKWebAppShare](bridge/VKWebAppShare) | Поделиться ссылкой. |
| [VKWebAppShowImages](bridge/VKWebAppShowImages) | Открыть нативный экран для просмотра изображений. |
| [VKWebAppShowWallPostBox](bridge/VKWebAppShowWallPostBox) | Опубликовать запись на стене. |
| [VKWebAppCreateHash](bridge/VKWebAppCreateHash) | Получить хеш. |
| [VKWebAppGetGrantedPermissions](bridge/VKWebAppGetGrantedPermissions) | Получить список разрешений. |
| [—](bridge/call) | Позвонить пользователю. |

## События жизненного цикла

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppChangeFragment](bridge/VKWebAppChangeFragment) | Открыть приложение по ссылке. |
 | [VKWebAppLocationChanged](bridge/VKWebAppLocationChanged) | Изменить хеш в адресной строке. |
 | [VKWebAppUpdateConfig](bridge/VKWebAppUpdateConfig) | Изменить конфигурацию приложения. |
 | [VKWebAppViewHide](bridge/VKWebAppViewHide) | Закрыть приложение. |
 | [VKWebAppViewRestore](bridge/VKWebAppViewRestore) | Восстановить приложение из кеша. |

## Пользователи

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppCallAPIMethod](bridge/VKWebAppCallAPIMethod) | Вызвать метод API ВКонтакте. |
 | [VKWebAppGetAuthToken](bridge/VKWebAppGetAuthToken) | Получить права доступа у пользователя. |
 | [VKWebAppGetEmail](bridge/VKWebAppGetEmail) | Получить адрес электронной почты. |
 | [VKWebAppGetFriends](bridge/VKWebAppGetFriends) | Показать список друзей пользователя. |
 | [VKWebAppGetGeodata](bridge/VKWebAppGetGeodata) | Получить данные о текущем местоположении пользователя. |
 | [VKWebAppGetPersonalCard](bridge/VKWebAppGetPersonalCard) | Вызвать карточку контактов. |
 | [VKWebAppGetPhoneNumber](bridge/VKWebAppGetPhoneNumber) | Получить номер телефона пользователя. |
 | [VKWebAppGetUserInfo](bridge/VKWebAppGetUserInfo) | Получить данные о профиле пользователя. |
 | [VKWebAppOpenContacts](bridge/VKWebAppOpenContacts) | Показать контакты из телефонной книги. |

## Сообщества 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppAddToCommunity](bridge/VKWebAppAddToCommunity) | Добавить приложение в сообщество.  |
 | [VKWebAppAllowMessagesFromGroup](bridge/VKWebAppAllowMessagesFromGroup) | Получить разрешение на отправку сообщений от имени сообщества. |
 | [VKWebAppGetCommunityToken](bridge/VKWebAppGetCommunityToken) | Получить права доступа. |
 | [VKWebAppGetGroupInfo](bridge/VKWebAppGetGroupInfo) | Получить информацию о сообществе. |
 | [VKWebAppJoinGroup](bridge/VKWebAppJoinGroup) | Предложить пользователю вступить в сообщество. |
 | [VKWebAppLeaveGroup](bridge/VKWebAppLeaveGroup) | Предложить пользователю выйти из сообщества. |
 | [VKWebAppSendPayload](bridge/VKWebAppSendPayload) | Отправить событие в сообщество. |
 | [VKWebAppShowCommunityWidgetPreviewBox](bridge/VKWebAppShowCommunityWidgetPreviewBox) | Показать виджет сообщества перед публикацией. |

## Платежи 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppShowOrderBox](bridge/VKWebAppShowOrderBox) | Открыть окно покупки товара. |
 | [VKWebAppOpenPayForm](bridge/VKWebAppOpenPayForm) | Показать платёжное окно VK Pay. |

## Кнопка в профиле пользователя 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppAddToProfile](bridge/VKWebAppAddToProfile) | Добавить в профиль кнопку вызова мини-приложения. |
 | [VKWebAppRemoveFromProfile](bridge/VKWebAppRemoveFromProfile) | Удалить из профиля кнопку вызова мини-приложения. |

## Рекомендации

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppRecommend](bridge/VKWebAppRecommend) | Порекомендовать мини-приложение друзьям. |

## Редактор историй

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppShowStoryBox](bridge/VKWebAppShowStoryBox) | Открыть редактор историй. |
 | [VKWebAppSubscribeStoryApp](bridge/VKWebAppSubscribeStoryApp) | Подписать пользователя на обновления истории. |

## Реклама

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppCheckNativeAds](bridge/VKWebAppCheckNativeAds) | Проверить наличие рекламы, доступной для показа. |
 | [VKWebAppGetAds](bridge/VKWebAppGetAds) | Получить данные для рекламного баннера. |
 | [VKWebAppShowNativeAds](bridge/VKWebAppShowNativeAds) | Показать рекламу. |

## Отслеживание пользователей

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppConversionHit](bridge/VKWebAppConversionHit) | Отслеживать конверсионные действия пользователей. |
 | [VKWebAppRetargetingPixel](bridge/VKWebAppRetargetingPixel) | Добавить пользователя в аудиторию ретаргетинга. |

## Интерфейс и навигация

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppResizeWindow](bridge/VKWebAppResizeWindow) | Изменить размер окна приложения. |
 | [VKWebAppScroll](bridge/VKWebAppScroll) | Прокрутить окно приложения.  |
 | [VKWebAppSetLocation](bridge/VKWebAppSetLocation) | Задать значение хеша в адресной строке. |
 | [VKWebAppSetSwipeSettings](bridge/VKWebAppSetSwipeSettings) | Включить свайп, как в браузере. |
 | [VKWebAppSetViewSettings](bridge/VKWebAppSetViewSettings) | Настроить вид статус- и экшен-бара. |

## Секция Storage

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppStorageGet](bridge/VKWebAppStorageGet) | Получить значение ключа. |
 | [VKWebAppStorageGetKeys](bridge/VKWebAppStorageGetKeys) | Получить названия всех переменных. |
 | [VKWebAppStorageSet](bridge/VKWebAppStorageSet) | Задать значение переменной. |

## Виброотклик (Taptic Engine)
 
 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppTapticImpactOccurred](bridge/VKWebAppTapticImpactOccurred) | Вызвать вибрацию при столкновении. |
 | [VKWebAppTapticNotificationOccurred](bridge/VKWebAppTapticNotificationOccurred) | Вызвать вибрацию после выполнения действия. |
 | [VKWebAppTapticSelectionChanged](bridge/VKWebAppTapticSelectionChanged) | Вызвать вибрацию при изменении выбора. |

## Управление фонариком

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppFlashGetInfo](bridge/VKWebAppFlashGetInfo) | Получить информацию о фонарике. |
 | [VKWebAppFlashSetLevel](bridge/VKWebAppFlashSetLevel) | Задать уровень яркости фонарика. |

## Данные датчиков 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppAccelerometerStart](bridge/VKWebAppAccelerometerStart) | Получать данные акселерометра. |
 | [VKWebAppAccelerometerStop](bridge/VKWebAppAccelerometerStop) | Не получать данные акселерометра. |
 | [VKWebAppDeviceMotionStart](bridge/VKWebAppDeviceMotionStart) | Получать данные о вращении устройства. |
 | [VKWebAppDeviceMotionStop](bridge/VKWebAppDeviceMotionStop) | Не получать данные о вращении устройства. |
 | [VKWebAppGyroscopeStart](bridge/VKWebAppGyroscopeStart) | Получать данные гироскопа. |
 | [VKWebAppGyroscopeStop](bridge/VKWebAppGyroscopeStop) | Не получать данные гироскопа. |

## Игры

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppCheckAllowedScopes](bridge/VKWebAppCheckAllowedScopes) | Проверить, есть ли доступ к данным. |
 | [VKWebAppShowInviteBox](bridge/VKWebAppShowInviteBox) | Пригласить друзей в игру. |
 | [VKWebAppShowLeaderBoardBox](bridge/VKWebAppShowLeaderBoardBox) | Показать таблицу результатов. |
 | [VKWebAppShowSubscriptionBox](bridge/VKWebAppShowSubscriptionBox) | Показать окно подписки. |
 | [VKWebAppShowRequestBox](bridge/VKWebAppShowRequestBox) | Отправить запрос пользователю. |

VK Bridge | Введение

## Актуальные события

* [Грантовая программа Fresh Code 2022](community/events/fresh-code-2022)

## Прошедшие события

* [Код Петербурга — 2022](community/events/code-of-petersburg)
* [Mini Design Award — 2022](community/events/mini-design-award)

Сообщество

# Правила размещения приложений в каталоге для сообществ

**Приложения для сообществ** — приложения, созданные на платформе [VK Mini Apps](mini-apps/getting-started), размещаемые в сообществах ВКонтакте и доступные в полной и мобильной версиях сайта, а также в мобильных клиентах. Каталог приложений для сообществ доступен по ссылке: https://vk.com/community_apps.

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

Установка приложения производится из каталога в разделе «Приложения» в настройках сообщества. Также пользователь может установить приложение не из каталога, но администратором которого он является.

**1.** Попасть в Каталог в разделе «Приложения» настроек сообщества может только одобренный сервис.

**2.** Приложения для сообществ, в отличие от обычных сервисов, проходят процедуру одобрения в особом порядке, описанном ниже. Кроме указанных ниже специальных условий, к приложениям для сообществ применимы Правила размещения приложений ВКонтакте.

**3.** Для подачи заявки на одобрение необходимо отправить заявку на модерацию из вкладки «Статус» созданного приложения с типом VK Mini Apps. В обращении должна быть пометка о желании попасть в каталог приложений для сообществ, а также должно содержаться описание функциональности приложения, ссылка на приложение и ссылка на сообщество, в котором оно установлено. В настройках приложения должно быть заполнено его описание, загружены иконка приложения и скриншоты.

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

**5.** Приложения, размещенные в Каталоге для сообществ, в качестве механизма уведомления и связи с пользователями должны использовать сообщения сообщества.

**6.** Приложения, размещенные в Каталоге для сообществ, не должны использовать авторизацию через сторонние сервисы. Наличие авторизации через сторонние сервисы согласуется с Администрацией сайта в индивидуальном порядке.

**7.** В размещении в Каталоге может быть отказано приложениям, которые дублируют функциональность сайта или уже находящихся в Каталоге приложений.

**8.** В Каталоге могут быть размещены только приложения, поддерживающие работу и корректно отображающиеся как в полной версии сайта vk.com, так и в мобильных приложениях.

**9.** В приложении, которое находится в Каталоге, запрещено размещение рекламы.

**10.** Приложения сообществ, в отличие от обычных приложений, могут реализовывать функциональность сбора и последующей обработки полученных персональных данных пользователей, например: ФИО, номера телефонов, адреса электронной почты. Обработка персональных данных разрешена только при условии ее соответствия действующему законодательству РФ, в т.ч. в сфере обработки персональных данных, и в тех случаях, когда это необходимо для корректной работы приложения при условии предварительного уведомления пользователя о цели сбора данных. У приложений для сообществ должна быть политика конфиденциальности. Если ее нет, используется типовая политика конфиденциальности ВКонтакте.

**11.** Приложения сообществ, в отличие от обычных приложений, могут реализовывать оплату услуг средствами, отличными от голосов ВКонтакте.

**12.** Приложения, находящиеся в каталоге, имеют возможность отправлять сообщения пользователям от имени сообществ, в которых они установлены. Запрещена рассылка рекламных сообщений, сообщений, содержание которых противоречит правилам сайта, и других сообщений, содержание которых прямо не связано с функциональностью приложения. В случае массовой рассылки одинаковых сообщений приложение может быть заблокировано.

**13.** В размещении в Каталоге может быть отказано приложениям, которые используют сторонний контент или перенаправляют пользователей на сторонние ресурсы.

Правила | Правила размещения приложений в каталоге для сообществ

# «Код Петербурга — 2022»

> Сроки проведения: с 1 июня по 30 сентября 2022 года.
> Подведение итогов: 14 октября 2022 года.
> [Итоги конкурса](https://vk.com/press/spb-code-2022)
> [Список победителей](https://vk.com/vkappsdev?w=wall-166562603_4652)

Вместе с [Комитетом по информатизации и связи](https://kis.gov.spb.ru/) и [Экосистемой городских сервисов «Цифровой Петербург»](https://about.petersburg.ru/) мы запускаем конкурс «Код Петербурга». Присоединяйтесь, если у вас есть готовый проект или идея [мини-приложения](mini-apps/getting-started), [чат-бота](api/bots/getting-started) или [навыка для умного помощника Маруси](marusia/getting-started).

Конкурс состоит из двух отдельных этапов и продлится четыре месяца. За это время новые проекты найдут свою аудиторию, а победители конкурса получат [вознаграждение](https://vk.com/@vkappsdev-polozhenie-o-publichnom-konkursee-kod-peterburga).

## Основная информация

Темы проектов должны быть связаны с Санкт-Петербургом: городской средой, туризмом, образованием, культурой.

Санкт-Петербургский информационно-аналитический центр даст вам доступ к API, с помощью которого вы сможете реализовать свои идеи. Узнайте больше о его возможностях на сайте [api.petersburg.ru](https://api.petersburg.ru/?role=0). Использовать другие открытые API тоже можно — но только в дополнение к уже предоставленным.

> Мы советуем вам ознакомиться со статьёй [Список API «Код Петербурга»](https://vk.com/@vkappsdev-spisok-api-kod-peterburga). В ней команда «Цифрового Петербурга» собрала список API по разным направлениям, которые помогут сделать ваши проекты оригинальнее и интереснее.

Лучшие авторы будут выбраны по итогам обоих этапов конкурса. На каждом этапе вы можете создать по одному проекту, но стать победителем сможете только на одном из этапов.

Сроки подачи заявки на конкурс:

* первый этап — с 1 июня по 31 июля 2022 года,
* второй этап — с 1 августа по 30 сентября 2022 года.

Экспертное жюри будет оценивать работы по нескольким критериям. Больше баллов получат проекты, которые:

* точно соответствуют заявленной тематике;
* основаны на оригинальной идее, которая ещё не реализована на платформе [VK Mini Apps](https://vk.com/services), в [каталоге навыков](https://marusia.mail.ru/) Маруси или в виде чат-бота для [сообщества](https://vk.com/groups);
* продуманы в плане UI и UX;
* могут масштабироваться с использованием технологий других платформ (например, [Одноклассников](https://apiok.ru/apps/rules));
* технически качественно реализованы, не содержат ошибок, запускаются в вебе и на мобильных устройствах;
* активно набирают аудиторию в течение первой недели после публикации.

## Как участвовать в конкурсе

### Шаг 1. Создайте оригинальный сервис

Создайте проект, который соответствует заявленной теме и не повторяет идеи, уже реализованные на платформе VK Mini Apps, в каталоге навыков Маруси или на платформе чат-ботов.

Следующие ресурсы помогут вам при подготовке проекта:

* Документация по созданию мини-приложений. Если вы новичок, начните с [первых шагов](mini-apps/getting-started).
* [Гайд на Хабре](https://habr.com/ru/company/vk/blog/521192/), в котором описан весь процесс разработки мини-приложения — от идеи до релиза.
* Публикации в [сообществе VK Mini Apps](https://vk.com/vkappsdev).
* [Библиотека VKUI](libraries/vkui), [макеты Figma](https://www.figma.com/@vk) и [стайлгайд](https://vkcom.github.io/VKUI/).
* Документация [Маруси](marusia/getting-started) и [чат-ботов](api/bots/getting-started).
* [Чат](https://vk.me/join/WI/WK4g2kUBnCAOXEkzOML64hEz_C/RA3Lc=) с участниками и организаторами конкурса.

### Шаг 2. Опубликуйте сервис ВКонтакте

#### Мини-приложения

Мини-приложение должно попасть в [каталог](https://vk.com/services), а перед этим пройти [модерацию](mini-apps/management/moderation) и тестирование. Здесь важно рассчитать время, чтобы уложиться в сроки программы. В среднем этот этап занимает около двух недель.

>**Важно!** На первом этапе отправить заявку на модерацию можно не позднее 31 июля. На втором этапе мы советуем отправлять мини-приложение на модерацию в середине сентября. Так больше шансов успеть пройти проверку и попасть в каталог, а значит — претендовать на приз.

После публикации в каталоге ваше мини-приложение будет доступно всем пользователям ВКонтакте. Они смогут найти его на вкладке **Сервисы** мобильного приложения, в пункте меню **Мини-приложения** в мобильной и десктопной версиях сайта, а также по ссылке [vk.com/services](https://vk.com/services).

#### Навыки для Маруси

Скилл Маруси также нужно опубликовать в [каталоге](https://marusia.mail.ru/). Модерация и тестирование занимают, как правило, 5–7 дней. Полезные советы и подробное описание процесса проверки вы найдёте [в документации Маруси](marusia/moderation).

>**Важно!** На первом этапе отправить заявку на модерацию можно не позднее 31 июля. На втором этапе мы советуем отправлять скилл на модерацию в середине сентября.

#### Чат-боты

Для создания чат-бота вам потребуется [сообщество](https://vk.com/groups) ВКонтакте. Как только вы добавите в него своего чат-бота, можно подать заявку на участие в конкурсе. Проходить модерацию не потребуется. Примеры реализации на разных языках программирования, руководство по работе с API ВКонтакте и многое другое мы собрали [в документации](api/bots/getting-started).

### Шаг 3. Участвуйте в брифингах с экспертами

На протяжении всего конкурса мы будем проводить питчинги с представителями Команды ВКонтакте. Вы научитесь презентовать свой проект и получите рекомендации по его улучшению. Следите за объявлениями в [сообществе VK Mini Apps](https://vk.com/vkappsdev).

### Шаг 4. Подайте заявку

Чтобы подать заявку, нужно заполнить [форму](https://vk.cc/ccy5y8) и указать в ней ссылку на готовое приложение.

Подать заявку могут только физические лица — авторы проектов. При этом неважно, создан проект независимым разработчиком или командой. Ждём участников от 14 лет и старше.

### Шаг 5. Дождитесь итогов

Эксперты оценят проекты и выберут лидеров в каждой теме. Авторы этих проектов получат денежные призы. Общий призовой фонд — 15 миллионов рублей.

Итоги конкурса по каждому из этапов будут подведены 14 октября 2022 года. Результаты будут опубликованы в [сообществе VK Mini Apps](https://vk.com/vkappsdev).

## Конкурс «Код Петербурга» это не только вознаграждения

### Новые идеи и механики для ваших проектов

В чате участников и на встречах с Командой ВКонтакте можно обсудить, какие технологии стоит интегрировать в свои проекты — сейчас или в будущем.

### Опыт питчингов и обратная связь от экспертов

У каждого участника будет возможность показать свой проект на питчингах. Все, кто готов представить идеи или прототипы своих мини-приложений, смогут выступить и получить рекомендации.

Конкурс «Код Петербурга» это не просто конкурс. Это шанс сделать удобный сервис для горожан и всех гостей Петербурга, а также проверить свои идеи на практике.

С вопросами о программе пишите в [сообщество VK Mini Apps](https://vk.com/vkappsdev).

Ждём ваших заявок!

## Полезные ссылки

[Публичное положение об участии в конкурсе](https://vk.com/@vkappsdev-polozhenie-o-publichnom-konkursee-kod-peterburga).
[Чат с участниками и организаторами](https://vk.me/join/WI/WK4g2kUBnCAOXEkzOML64hEz_C/RA3Lc=).

Сообщество | Архив | Код Петербурга — 2022

# Грантовая программа Fresh Code 2022 от VK Mini Apps

> Сроки проведения: с 7 октября по 2 декабря 2022 года.
> Подведение итогов: 5 декабря 2022 года.

Мы верим в технологии: видим, как удобные сервисы каждый день помогают миллионам пользователей ВКонтакте делать покупки, путешествовать, учиться, знакомиться. Поэтому развиваем платформу VK Mini Apps — вместе со всеми, кто хочет попробовать себя в разработке мини-приложений или уже создаёт их.

Если у вас есть идея или готовый проект, присоединяйтесь к грантовой программе VK Fresh Code. В этом году она длится два месяца: за это время новые мини-приложения найдут свою аудиторию, и уже в декабре создатели лучших 25 сервисов смогут получить гранты — по 180 000 рублей.

![](26b96330c778c2a0c6cabd5bf91c033e16900373954e0d9f7349f7c6 "1269910100372578947")

**Рассказываем по порядку:**

1. [Как присоединиться к программе и побороться за грант](#Как%20присоединиться%20к%20программе%20и%20побороться%20за%20грант) 
2. [Что даёт Fresh Code, помимо грантов](#Что%20даёт%20Fresh%20Code,%20помимо%20грантов)
3. [Почему мини-приложения в тренде](#Почему%20мини-приложения%20в%20тренде)

## Как присоединиться к программе и побороться за грант

### Шаг 1. Cоздайте оригинальное мини-приложение в тематиках программы

В грантовой программе VK Fresh Code 2022 десять тематик:

* Образ жизни
* Образование
* Мероприятия
* Транспорт
* Развлечения
* Путешествия
* Еда и напитки
* Красота и здоровье
* Бизнес
* Покупки

> Последний день приёма заявок – 2 декабря.
>
> Можно всё это время работать над одним проектом или успеть подготовить несколько мини-приложений в разных темах.

Мы прислушались к вашим пожеланиям и пересобрали конкурс. В этой статье вы найдёте традиционные условия и новинки программы. Например, теперь экспертное жюри будет оценивать приложения по нескольким новым критериям — постарайтесь учесть их уже при разработке или апгрейде своего проекта к конкурсу. Больше баллов получат проекты, которые:

* Точно соответствуют одной из тематик.
* Содержат оригинальную идею, которая ещё не встречалась на платформе VK Mini Apps.
* Классно продуманы в плане UX и UI — пользовательского опыта и интерфейса.
* Технически качественно реализованы, пролечены от багов, запускаются на вебе и мобильных платформах.
* Круто прошли питчинг — публичную защиту перед экспертами.
* Попали в каталог мини-приложений.

Полезные ресурсы при подготовке проекта:

* [Документация](mini-apps/getting-started) по разработке мини-приложений.
* [Библиотека VKUI](libraries/vkui) и [макеты Figma](https://www.figma.com/@vk).
* В [сообществе VK Mini Apps](https://vk.com/vkappsdev) вы найдёте много полезных материалов.
* На промежуточных питчингах и сессиях вопросов-ответов все участники смогут получить рекомендации от Команды ВКонтакте.
* Всё о процессе разработки мини-приложения от идеи до релиза вы найдёте в нашем [гайде на Хабре](https://habr.com/ru/company/vk/blog/521192/).

### Шаг 2. Опубликуйте мини-приложение ВКонтакте

Да, публикация мини-приложения в каталоге ВКонтакте не является обязательным условием участия в грантовом конкурсе VK Fresh Code 2022 и получения приза. Но для тех участников, кто всё же планирует получить дополнительные баллы за публикацию мини-приложения в каталоге, дадим пару советов. Стоит учесть, что прежде чем проект попадёт в каталог, он должен пройти [модерацию](mini-apps/catalog/getting-started) и тестирование командой [VK Testers](https://vk.com/testers). Здесь важно рассчитать время, чтобы уложиться в сроки программы: в среднем этот этап занимает около двух недель. Или больше, если в сервисе найдётся много багов.

> Отправить мини-приложение в тестирование лучше не позднее **18 ноября**. Так оно успеет пройти проверку, появиться в каталоге и сможет претендовать на баллы по этому критерию.

После публикации ваш сервис станет доступен всем пользователям ВКонтакте. Они смогут найти его на вкладке **Сервисы** в мобильном приложении, на [m.vk.com](https://m.vk.com) и в версии для компьютера, а также по ссылке [vk.com/services](https://vk.com/services).

> Для всех победителей конкурса, чьи мини-приложения окажутся в каталоге до&nbsp;**2&nbsp;декабря** включительно, мы подготовим специальное продвижение в рамках новогодних праздников. Это отличная возможность бодро набрать аудиторию для своих проектов.

### Шаг 3. Участвуйте в питчингах с экспертами

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

### Шаг 4. Подайте заявку на грант

Для этого до **23:59 2 декабря** нужно заполнить [форму](https://vk.com/app6013442_-166562603?form_id=33#form_id=33), которая также будет опубликована в [сообществе VK Mini Apps](https://vk.com/vkappsdev). Обязательно укажите в ней ссылку на готовое приложение.

Подать заявку на грант могут только физические лица — авторы мини-приложений, которым уже исполнилось 14 лет. При этом неважно, создан проект независимым разработчиком, командой энтузиастов или с поддержкой бизнеса.

### Шаг 5. Дождитесь итогов

Результаты объявим **5 декабря**. Эксперты выберут 25 лучших мини-приложений, авторы которых получат денежные призы — по 180 000 рублей.

## Что даёт Fresh Code, помимо грантов

* **Новые идеи и механики для ваших проектов**

    В чате участников и на встречах с Командой ВКонтакте можно обсудить, какие технологии стоит интегрировать в свои проекты — сейчас или в будущем.

* **Опыт питчингов и обратную связь от экспертов**

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

## Почему мини-приложения в тренде

Потому что это удобно: сервисы открываются внутри ВКонтакте и не забивают память телефона, а в каталоге можно найти инструменты на любой случай — купить билеты, записаться на стрижку, проверить курс валют. Поэтому и пользуются мини-приложениями всё чаще: **ежемесячная аудитория VK Mini Apps — более 45 миллионов человек**.

При этом платформа VK Mini Apps продолжает расширяться: к октябрю на ней уже более **50 000 мини-приложений**. Всё потому, что здесь рады разработчикам: документация и обучающие материалы в открытом доступе, образовательные и грантовые программы стали традицией. А в [сообществе](https://vk.com/vkappsdev) легко найти единомышленников, посоветоваться, собрать команду — словом, есть всё, чтобы вместе запускать проекты, которых ждут пользователи.

Fresh Code от VK Mini Apps меняется вместе с платформой: становится динамичнее и предлагает больше. В 2022 году это не только программа, где можно получить знания, создать своё мини-приложение и выиграть грант. Это шанс сделать крутой сервис для миллионов пользователей.
С вопросами о программе пишите в сообщество VK Mini Apps: [vk.me/vkappsdev](https://vk.me/vkappsdev).
Ждём ваши заявки — мы будем рядом на всех этапах. ВКонтакте.

> Актуальной информацией о конкурсе будем делиться в первую очередь в специальном [чате для участников](https://vk.cc/chUkvy), там же можно обсудить, какие технологии стоит интегрировать в свои проекты, и задать интересующие вопросы команде ВКонтакте. Присоединяйтесь: [vk.cc/chUkvy](https://vk.cc/chUkvy)

## Положение о конкурсе

* [Публичное положение об участии в конкурсе](community/events/fresh-code-2022-regulations) 


Сообщество | События | Грантовая программа Fresh Code 2022 от VK Mini Apps

Сообщество | События | Положение о публичном конкурсе «VK Fresh Code 2022»

# Mini Design Award — 2022

> Сроки проведения: с 1 по 15 июля 2022 года.

Чтобы принять участи в конкурсе Mini Design Award, с 1 по 15 июля отправьте нам уже готовый сервис через [специальную форму](https://vk.cc/mda2022) и узнайте, как хороший дизайн [мини-приложения](mini-apps/overview) влияет на его метрики.
Мы будем оценивать все работы по следующим критериям:

* Качество UX-дизайна.
* Качество UI-дизайна.
* Работоспособность мини-приложения.

Что получат участники конкурса: 

* 1-е место — набор продукции с символикой ВКонтакте и уникальной толстовкой и 10 000 рублей на рекламное продвижение ВКонтакте.
* 2-е место – набор продукции с символикой ВКонтакте с уникальной толстовкой и 5 000 рублей на рекламное продвижение.
* 3-е место – набор продукции с символикой ВКонтакте и 2 500 рублей на рекламное продвижение.

Кроме того, авторы работ, занявшие первые 10 мест, получат анимированную Lottie-иконку, а 3 последних места — полную разработку дизайна от нашей команды.

[Итоги конкурса](https://vk.com/wall-166562603_4442) смотрите в сообществе VK Mini Apps.

Сообщество | Архив | Mini Design Award — 2022

# Требования для модерации приложений на игровой платформе

Создавая приложение ВКонтакте, вы получаете доступ к многомиллионной аудитории. Важнее всего для нас — не обмануть доверие и ожидания этих людей, поэтому мы хотим предлагать им только надежные и проработанные приложения. Более того, мы чувствуем ответственность перед серьёзными разработчиками, которые уже вложили душу в свой продукт и хотят, чтобы он был окружен приложениями, соответствующими по качеству. 

В процессе модерации мы придерживаемся общего свода правил. Однако, некоторые пункты имеют смысл только для одной платформы. Так, под «приложением, размещенным на vk.com» следует понимать приложение, доступное пользователям в основной версии сайта ВКонтакте. «Приложение, размещенное в мобильном html5-каталоге Direct Games» — приложение, доступное пользователям из игрового раздела мобильной версии ВКонтакте m.vk.com и официальных мобильных приложений ВКонтакте.

## До подачи заявки

Перед подачей заявки на модерацию убедитесь, что вы:
*  перевели приложение в режим «Включено и видно всем» в настройках;
*  проверили приложение и убедились, оно работает без ошибок, не ломается, не зависает при загрузке, не содержит очевидных багов в логике работы или интерфейсе;
*  перевели бэкенд приложения в боевой режим работы, так что внешние пользователи (в частности, редакторы каталога) могут полноценно использовать приложение;  
*  заполнили информацию о приложении, ввели лаконичное и ёмкое название, исключив из него жанры, теги и прочие описательные особенности, выбрали соответствующую категорию и загрузили медиа-файлы: обложки, скриншоты, видео;
*  проверили игру, которую планируете запустить на платформе Direct Games на iOS, на соответствие [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/).

## 1. Безопасность, контент внутри приложений

**1.1** Контент в приложении не должен быть оскорбительным, клеветническим, подлым, предназначенным для того, чтоб вызывать чувство отвращения или создавать опасность для конкретных людей или групп людей;
**1.2** В приложении запрещена любая дискриминация по полу, религии, расе, вероисповеданию, принадлежности к социальным группам и так далее;
**1.3** В приложении запрещается использовать натуралистичные изображения насилия над людьми или животными, эротику, порнографические материалы, оскорбительные материалы, нецензурную брань, бранные слова и выражения;
**1.4** Приложение не должно быть посвящено эротической или эзотерической тематике, включая гадания;
**1.5** Приложение может быть отклонено, если его назначение противоречит общепризнанным этическим нормам или принципам морали;
**1.6** Приложение должно быть уникальным. Если в каталоге уже есть аналогичные приложения с той же тематикой и функциональностью (чаты, радио, кинотеатры, простейшие тесты и т.д.), приложение может быть отклонено;
**1.7** Приложение не может предназначаться для узких групп пользователей или представлять собой сборник текстов или изображений без существенной дополнительной функциональности.

## 2. Покупки, подписки, работа с голосами

**2.1** Оплата всех виртуальных товаров и услуг в приложениях, размещенных на vk.com и в мобильном html5-каталоге Direct Games, должна приниматься голосами ВКонтакте. В приложениях запрещается принимать оплату другими способами, в том числе на сторонних сайтах.
Размер оплаты за предоставление виртуальных товаров и услуг должен выражаться исключительно в голосах ВКонтакте (в том числе в интерфейсе приложения).
**2.2** В приложениях, размещенных на vk.com и в мобильном html5-каталоге, запрещается переводить голоса ВКонтакте пользователям и дарить подарки ВКонтакте. При нарушении этого правила приложение навсегда лишится нашего доверия, возможности принимать голоса от пользователей и перспективы размещаться в каталоге на vk.com. Единственный допустимый случай — возврат пользователю ранее внесенных голосов. 
**2.3** Запрещается блокировать основную функциональность и геймплей приложения пользователям, которые не соглашаются на совершение платежей. Если игра работает по модели доступа по подписке, игроку должен предоставляться триальный период для ознакомления. 

## 3. Функциональность и дизайн

**3.1** Приложение должно быть полностью переведено на русский язык;
**3.2** Приложение должно содержать правила и режим обучения, чтобы игроки могли разобраться в деталях функционирования приложения. Некоторые простейшие игры (например, проекты в жанре hypercasual) могут не содержать режима обучения, однако в этом случае управление должно быть нативно понятным.
**3.3** Приложение не должно быть «заглушкой», не несущей в себе функциональной нагрузки;
**3.4** Приложение должно быть визуально привлекательным, все элементы должны быть выполнены в едином стиле. Приложение может быть отклонено, если его интерфейс слишком сложный, недостаточно проработанный и спроектирован без внимания к деталям. При оформлении иконок запрещается использовать дополнительные элементы для привлечения внимания, например, в виде значка уведомления, цифр, рамок, галочек, лент.
**3.5** Все типы загружаемых обложек приложения должны выглядеть одинаково или отличаться только небольшими деталями;
**3.6** Доступ к функциональности приложений должен предоставляться без необходимости перехода за пределы сайта или приложения ВКонтакте;
**3.7** Запрещается урезать функциональность приложения пользователям, которые не соглашаются на дополнительные действия, например, рассылку приглашений, публикацию записей на стене, получение оповещений, вступление в группу игры и так далее; 
**3.8** Блокираторы прогресса игрока, такие как жизни, энергия и их аналоги, должны самостоятельно восстанавливаться за определенные промежутки времени по таймеру, если пользователь истратил их. После первой установки приложения у пользователя должен быть полный баланс жизней или энергии, необходимый для старта игры.
**3.9** Запрещается побуждать пользователей привлекать внимание к игре активными спам-действия: массовой рассылкой сообщений, упоминанием друзей в записях на стенах и так далее;
**3.10** В приложениях, размещенных на vk.com и в мобильном html5-каталоге Direct Games, не должно быть отдельной регистрации или авторизации через сторонние сети. Запрещается запрашивать у пользователя такие данные, как email, пароли, номера телефонов, паспортные данные и другую личную информацию. 
**3.11** Приложение, размещенное на vk.com, должно корректно работать в режиме безопасного (HTTPS) соединения во всех основных браузерах: Chrome, Firefox, Opera, Yandex.Browser. Приложение в мобильном html5-каталоге Direct Games должно корректно работать на платформах iOS 10.3 и выше, Android 5.1 и выше. 
**3.12** Приложение, планирующее разместиться на vk.com, должно запускаться без установки пользователями дополнительных плагинов, таких как, например, Flash Player или Unity Web Player.
**3.13** Приложение не должно содержать элементы оформления, дизайна, логотипы и упоминания социальных сетей и других платформ размещения приложений, отличных от ВКонтакте.
**3.14** В Приложении запрещается осуществлять действия (в том числе посредством размещения информации и/или рекламы, ссылок на сторонние сервисы и платформы), направленные на перевод аудитории Приложения на платформе ВКонтакте в версии Приложения, размещенные вне социальной сети ВКонтакте.

## 4. Интеграция, социальные механики

**4.1** В приложении должны содержаться социальные функции для взаимодействия пользователей;
**4.2** Приложение может повышать уровень пользователя, начислять очки и считать миссии выполненными только за активные действия игрока (прохождение игрового этапа, создание элемента в игре и др.), а не за полученные бонусы, подарки, действия друзей и тому подобное.

## 5. Конфиденциальность, связь с разработчиком

**5.1** У приложений, размещенных на vk.com и в мобильном html5-каталоге, должна быть политика конфиденциальности. Если ее нет, используется типовая политика конфиденциальности ВКонтакте. 
**5.2** Разработчик приложения обязан обеспечивать поддержку игроков и предоставить простой способ связи для обращений пользователей по всем возникающим в процессе использования приложения вопросам в сообществе игры, на своем сайте или в разделе «Помощь». 

## 6. Рекламные приложения

**6.1** Рекламные приложения проходят модерацию в особом порядке, для размещения такого приложения требуется заключить договор.

Правила | Требования для модерации приложений на игровой платформе

Договор о размещении приложений в мобильных клиентах ВКонтакте

# Доступ к игре

## Настройки видимости

Игра может быть доступна всем пользователям ВКонтакте или только администраторам игры. Чтобы изменить её видимость, установите нужное **Состояние** в настройках игры:

1. Откройте страницу [Мои приложения](https://vk.com/apps?act=manage). Найдите свою игру в списке приложений и нажмите **Редактировать**.

2. В меню слева выберите **Настройки**. **Состояние** будет в начале раздела:

    ![alt=Настройки игры, Состояние;title=Настройки игры &rarr; Состояние](2f8a33c9b8f209d7aba910eb17222210097f698930c01c6a9dbfa022 "-5581042562764304518")

## Состояние: Приложение отключено

Сразу после создания игры **Состояние** будет **Приложение отключено**. При этом значении игра доступна только её администраторам. Изначально в их число входит только создатель игры, то есть тот, кто зарегистрировал её ВКонтакте. Он может [добавить](#Как%20добавить%20администраторов) других пользователей в число администраторов.

Администраторы могут запускать игру всеми возможными способами:

* со страницы [Мои приложения](https://vk.com/apps?act=manage);

* по [прямой ссылке](#Как%20запустить%20игру%20по%20прямой%20ссылке);

* из каталога игр (после публикации в каталоге).

## Состояние: Приложение включено и видно всем

Чтобы сделать игру доступной всем пользователям ВКонтакте, измените **Состояние** на **Приложение включено и доступно всем**.

Пользователи смогут запускать игру:

* по [прямой ссылке](#Как%20запустить%20игру%20по%20прямой%20ссылке);

* из каталога игр (после публикации в каталоге).

## Публикация в каталоге

[Публикация в каталоге](games/catalog/overview) не влияет на доступность игры пользователям. Когда игра опубликована, пользователи могут найти и запустить её через интерфейс ВКонтакте. Без публикации они могут пользоваться только прямой ссылкой на игру.  

## Сводная таблица

Следующая таблица показывает доступность игры пользователям в зависимости от настроек:

| Настройки | Доступность игры пользователям | Доступность администраторам игры |
| ----- | ----- | ----- |
| **Состояние:&nbsp;Приложение&nbsp;отключено&nbsp;&nbsp;&nbsp;&nbsp;** | Игра недоступна | **&check;** |
| **Состояние: Приложение включено** | **&check;** (По&nbsp;[прямой&nbsp;ссылке](#Как%20запустить%20игру%20по%20прямой%20ссылке)) | **&check;** |
| **Игра опубликована в каталоге** | **&check;** (По [прямой ссылке](#Как%20запустить%20игру%20по%20прямой%20ссылке) и через UI ВКонтакте) | **&check;** |

## Частые вопросы

### Как запустить игру по прямой ссылке

Прямая ссылка — это ссылка, содержащая идентификатор игры, например:

* `vk.com/app1234567` — для десктопной версии браузера;

* `m.vk.com/app1234567` — для мобильной версии браузера.

Идентификатор игры (цифры после `/app`) вы можете найти в настройках игры:

![alt=Информация и настройки игры;title=Информация и настройки игры](7cde95124a986b263d3f11641dbaa419a9397bf85c01a2b51fd17e05  "3157924796716398464")

### Как сделать игру видимой другу

Воспользуйтесь одним из следующих способов:

* Добавьте друга в [администраторы игры](#Как%20добавить%20администраторов).

    — или —

* Переключите **Состояние** в **Приложение включено и видно всем** и дайте другу прямую ссылку на игру (`vk.com/app{game-id}`).

### Как добавить администраторов

Ваши коллеги или знакомые, которых вы хотите сделать администраторами игры, должны иметь аккаунт ВКонтакте.

1. Откройте страницу [Мои приложения](https://vk.com/apps?act=manage). Найдите свою игру в списке приложений и нажмите **Редактировать**.

1. В меню слева переключитесь в раздел **Руководство**, затем нажмите **Добавить администратора**.

1. В открывшемся диалоговом окне укажите ссылку на страницу пользователя. Подойдёт как обычная ссылка `vk.com/id1`, так и короткий адрес, например `vk.com/name`.

1. Выберите **Полный доступ** или **Частичный доступ**.

1. Если у администратора будет частичный доступ, то выберите подконтрольные ему разделы и режимы работы:

    ![alt=Внешний вид окна добавления администратора;title=Внешний вид окна добавления администратора](b3b127446d90936b50582a685b43fe5988f28fed975432586518f268 "-1980249844862961318")

1. Нажмите **Добавить администратора**.

1. Подтвердите действие с помощью устройства, привязанного к вашему профилю. После этого новый администратор появится в списке руководителей игры и получит push-уведомление с приглашением стать администратором.

    Обратите внимание, что пользователь станет администратором, только после того как примет приглашение.

Если вы видите **Сохранить изменения** вместо **Добавить администратора**, это означает, что выбранный пользователь уже является администратором игры.

> **Важно!** Мы рекомендуем [включить подтверждение входа (двухфакторную аутентификацию, 2FA)](https://vk.com/page-59800369_53735144) всем администраторам игры. Это в значительной степени обезопасит их аккаунты и повысит безопасность игры.&#x0d;&#x0a;&#x0d;&#x0a;Включить этот режим можно в [настройках ВКонтакте](https://id.vk.com/account/#/security). При подключении убедитесь, что у вас есть доступ к привязанной к аккаунту электронной почте и номеру телефона, а также что в вашем профиле размещены фотографии, на которых хорошо видно ваше лицо.

### Как скрыть игру

Переключите **Состояние** в значение **Приложение отключено**. Игра станет доступна только её администраторам.

Игры | Доступ к игре

# Библиотека VK Bridge

Платформа HTML5 игр Direct Games, платформа игр на vk.com и платформа мини-приложений VK Mini Apps используют для взаимодействия с ВКонтакте библиотеку VK Bridge.

**NPM-пакет:** [`https://www.npmjs.com/package/@vkontakte/vk-bridge`](https://www.npmjs.com/package/@vkontakte/vk-bridge).

## Подключение VK Bridge в игре 

Чтобы подключить библиотеку VK Bridge:

Шаг 1. Установите пакет @vkontakte/vk-bridge
   
   * с помощью `npm`:

```sh
npm install @vkontakte/vk-bridge
```

   * или с помощью `yarn`:

```sh
yarn add @vkontakte/vk-bridge
```

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

```JavaScript
 import bridge from '@vkontakte/vk-bridge';
```

Шаг 3. Отправьте событие инициализации `VKWebAppInit`:

```JavaScript
 bridge.send("VKWebAppInit", {});
```

После этого вы можете использовать объект `bridge` для отправки и получения событий.

## Использование VK Bridge

 Метод клиентского API вызывается функцией

```JavaScript
bridge.send(METHOD_NAME, METHOD_PARAMS);
```

**Параметры**

| Параметр | Описание |
|---|---|
|`METHOD_NAME` `string` | Имя метода. |
|`METHOD_PARAMS` `object` | Объект с параметрами вызова метода. Структура объекта зависит от метода. |

Метод API генерирует событие-результат. Добавление обработчика события-результата возможно с помощью метода `subscribe`. 

**Пример.** Вызов метода открытия окна покупки предмета внутри игры.

```JavaScript
// Отправка события 
 bridge.send("VKWebAppShowOrderBox", {type:"item", item:"item_id_123"});
// Подписка на событие-результат
 bridge.subscribe((e) = {
 if(e.type == ‘VKWebAppShowOrderBoxResult’) {
console.log(e.data.status);
 }});
```

Тип результирующего события равен исходному с суффиксом `Result`. Например, для события `VKWebAppShowRequestBox` результат имеет тип `VKWebAppShowRequestBoxResult`.

## Список событий

[Полный список событий VK Bridge](bridge/getting-started).

Обратите особое внимание на методы VK Bridge, позволяющие реализовать дополнительные социальные механики в играх:

* [`VKWebAppShowStoryBox`](bridge/VKWebAppShowStoryBox) – открытие редактора историй;
* [`VKWebAppGetUserInfo`](bridge/VKWebAppGetUserInfo) – получение данных профиля пользователя;
* [`VKWebAppShare`](bridge/VKWebAppShare) – вызов диалогового окна «Поделиться»;
* [`VKWebAppShowWallPostBox`](bridge/VKWebAppShowWallPostBox) – публикация записи на стене;
* [`VKWebAppAllowNotifications`](bridge/VKWebAppAllowNotifications) – включение уведомлений от игры;
* [`VKWebAppDenyNotifications`](bridge/VKWebAppDenyNotifications) – выключение уведомлений;
* [`VKWebAppSetLocation`](bridge/VKWebAppSetLocation) – установка хеша для навигации в приложении;
* [`VKWebAppAllowMessagesFromGroup`](bridge/VKWebAppAllowMessagesFromGroup) – подписка на сообщения сообщества;
* [`VKWebAppJoinGroup`](bridge/VKWebAppJoinGroup) – вступление в сообщество;
* [`VKWebAppAddToFavorites`](bridge/VKWebAppAddToFavorites) – добавление в избранное.

Методы, доступные только в играх:

* [`VKWebAppCheckAllowedScopes`](bridge/VKWebAppCheckAllowedScopes) – проверить, есть ли доступ к данным;
* [`VKWebAppShowOrderBox`](bridge/VKWebAppShowOrderBox) – вызов окна покупки в игре;
* [`VKWebAppCheckNativeAds`](bridge/VKWebAppCheckNativeAds) – проверка наличия рекламы для пользователя на Android или iOS;
* [`VKWebAppShowNativeAds`](bridge/VKWebAppShowNativeAds) – показ рекламы в игре на Android или iOS;
* [`VKWebAppShowInviteBox`](bridge/VKWebAppShowInviteBox) – вызов окна приглашения друзей в игру;
* [`VKWebAppShowRequestBox`](bridge/VKWebAppShowRequestBox) – вызов окна отправки запроса другому пользователю;
* [`VKWebAppShowLeaderBoardBox`](bridge/VKWebAppShowLeaderBoardBox) – открытие таблицы результатов игры.

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

Игра, использующая методы VK Bridge: https://github.com/VKCOM/vk-direct-games-example

Игры | Библиотека VK Bridge

#  Как попасть в каталог

Чтобы попасть в каталог, игра должна пройти модерацию. Для этого нужно подать заявку и исправить недочёты, на которые укажет модератор. Если всё хорошо, игра будет добавлена в каталог.

Выполните следующие шаги:

1. [Подготовьте игру к модерации](#Шаг%201.%20Подготовьте%20игру%20к%20модерации)
1. [Отправьте заявку на модерацию](#Шаг%202.%20Отправьте%20заявку%20на%20модерацию)
1. [Следите за статусом модерации](#Шаг%203.%20Следите%20за%20статусом%20модерации)

## Шаг 1. Подготовьте игру к модерации

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

1. Игра не нарушает:

    * [Правила платформы](rules)
    * [Политику конфиденциальности](privacy-policy)
    * [Требования для публикации в каталоге](games-catalog-rules)
    * [Правила размещения рекламы в игровых приложениях](ad-rules)

1. Игра работает без ошибок на всех выбранных для публикации [платформах](games/getting-started#Direct%20Games%20и%20Web-игры).
1. Если игра претендует на размещение в каталоге в приложении для iOS:

    * Игра не продаёт виртуальные ценности. Мы обязаны выполнять [правила размещения приложений в App Store](https://developer.apple.com/app-store/review/guidelines/) (пункты [3.1.3(b)](https://vk.cc/cgqBZv) и [3.2.1 (vi)](https://vk.cc/cgqC5o)). Монетизировать игру можно с помощью рекламы после размещения в каталоге. 
    * В настройках заполнены поля [Apple Developer Team ID](https://developer.apple.com/programs/enroll/) и **Apple Developer Team Name**. Это обязательное требование к играм в приложениях для App Store.
    * Игра использует технологию ODR для загрузки ресурсов. Для прохождения модерации в настройках игры нужно загрузить архив с ресурсами и протестировать его работу. Подробности в разделе [Работа с ресурсами для iOS](games/direct-games/on-demand-resources).

1. В игре есть возможность отключить звук.
1. В игре есть канал связи с технической поддержкой. Это может быть ссылка на сообщество, страница внутри игры, адрес электронной почты или личная страница автора.
1. Игра запрашивает у пользователей разрешение на публикацию личных данных: записей, фотографий. Пользователь должен понимать, как игра работает с такой информацией.
1. У пользователя должна быть возможность отказаться от публикации личных данных.
1. У вас нет похожей игры в каталоге. Новая будет одобрена только при наличии существенных различий. Вы можете использовать элементы старой игры, но в таком случае игровые механики должны значительно отличаться.

    > **Обратите внимание!** Мы не отклоняем игры из-за внешнего сходства с игрой, разработанной другим разработчиком (за исключением полного копирования). Если вы считаете, что другие разработчики нарушают ваши права, обратитесь к ним напрямую.

1. Основной язык игры — русский.
1. Графика игры качественно проработана.
1. В игре есть режим обучения с подсказками для новых игроков.
1. Купить игровую валюту можно только за голоса. 

    > **Важно!** В версии игры для iOS купить игровую валюту и другие виртуальные ценности нельзя.

1. В игре используются механики социального взаимодействия, например добавлена кнопка **Рассказать друзьям**.

Посмотрите на примеры игр, которые успешно прошли модерацию и попали в каталог:

:::carousel

![alt=Игра из каталога;title=Игра из каталога](7d4ba20604405928d693650a0c580baf001b369e452cb206aacf861e "-575441788945359711")
![alt=Ещё одна игра из каталога;title=Ещё одна игра из каталога](cd40ca4cc9797035ed8db8116cf07950e107d3a206f75ec89f429b6a "-2572540176541241675")
:::

## Шаг 2. Отправьте заявку на модерацию

Чтобы отправить заявку на добавление игры в каталог:

1. Откройте [Мои приложения](https://vk.com/apps?act=manage)&nbsp;&rarr;&nbsp;**Редактировать**&nbsp;&rarr;&nbsp;**Модерация**.

2. В блоке **Публикация в каталоге игр** нажмите **Отправить заявку на публикацию в каталоге**.

    ![alt=Отправка заявку на модерацию;title=Отправка заявку на модерацию;](3c31d125e3f813e0059d69ee8b16b120514dd5c4b74f90fc1760de41 "1215592287818649302")

    Если вы отправляете заявку для игры вида Direct Games, выберите платформы, на которых вы хотите её разместить (Android, iOS, мобильная версия сайта ВКонтакте). 

    ![alt=Выбор платформ;title=Выбор платформ;](997dc3d9adac929c2076235224c41bc58599ccf2b9b47f4ea650a9b5 "-6960402888854691202")

> Игра, размещённая в приложении ВКонтакте для iOS, появится и в каталоге для iPadOS.

## Шаг 3. Следите за статусом модерации

Проверка обычно занимает от 2 до 7 рабочих дней. После изменения статуса заявки её отправитель получит SMS-сообщение и уведомление в десктопной версии сайта в разделе **Модерация**.

Если модератор отклонит заявку, то укажет причину в ответе и попросит доработать игру. После исправления недочётов вы можете отправить игру на проверку ещё раз.

Задавайте вопросы модератору в заявке на модерацию или [используйте специальную форму](https://vk.com/support?act=new_app&from=sg), чтобы напрямую отправить запрос модератору.

![alt=Статус заявки;title=Статус заявки;](4ebf52fbce8f69123f8471584fccf95436dbe4dc0177d262a9ccabf8 "-6347055476794925580")

Если у модератора нет вопросов к вашей игре и она готова к размещению в каталоге, он обновит статус заявки и разместит игру в каталоге. На этом всё, поздравляем!

Теперь игру можно найти поиском по каталогу, а на иконке игры в зависимости от платформы появится бейдж **Новое** или **New**.

:::carousel
![alt=Новая игра в каталоге;title=Новая игра в каталоге;](b69e722c89c07f29ca8aa342a6cea6b72177664f5cf2a9149b9b0c0a "-3608911507285017423")
![alt=Новая игра в каталоге;title=Новая игра в каталоге;](33070df69bcaa5d5a2e1c681f84d562fb6781079b5cd7e8ccb6538e4 "6196702774876698020")
:::

## Что дальше

### Продвижение игры

Продумайте сценарий продвижения вашей игры, используйте указанные ниже инструменты и подавайте [заявки](https://vk.com/support?act=new_app&from=sg) на размещение в подборках.

После того как игра попала в каталог, для продвижения игры вы можете:

* Создать [миссии](games/promotion/game-mechanics#Миссии), настроить автоматические [уведомления](games/promotion/game-mechanics#Автоматические%20уведомления) и [массовые рассылки](games/promotion/game-mechanics#Массовые%20рассылки).
* Подать заявку на публикацию в разделе **Новые** в десктопной версии сайта ВКонтакте.
* Запустить [рекламу](games/promotion/ad) и добавить возможность [приглашать друзей](games/promotion/game-mechanics#Приглашения).

### Удаление из каталога

Если по какой-либо причине вы хотите удалить игру из каталога, напишите об этом модератору в разделе [Помощь](games/support) в настройках игры.

Модератор может удалить игру из каталога без запроса разработчика по следующим причинам:

* Игра отключена или не работает.
* Разработчик не исправляет критические проблемы и уязвимости.
* В игру внесены изменения, которые нарушают [требования](#Шаг%201.%20Подготовьте%20игру%20к%20модерации). 
* Разработчик не отвечает на сообщения пользователей и вопросы модератора.
> Предварительно модератор напишет разработчику игры о нарушении и попросит исправить его.

Чтобы сразу задать вопрос непосредственно модератору и оперативно получить ответ, [используйте специальную форму](https://vk.com/support?act=new_app&from=sg).

Игры | Каталоги | Как попасть в каталог

# Работа с ресурсами для iOS

Если вы планируете разместить игру в каталоге для iOS, вам нужно выполнить приведённые ниже инструкции. Если вы не собираетесь публиковать игру в каталоге или создаёте её только для Android или версии для компьютера, пропустите этот раздел.

## Разработка

При первом запуске игры клиент ВКонтакте сохраняет все её ресурсы на устройстве пользователя. Например: файлы `.css`, `.js`, шрифты и графику. Это позволит в следующий раз запустить игру гораздо быстрее.

Для организации ресурсов используется технология [ODR](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/On_Demand_Resources_Guide/index.html) (On-Demand Resources), разработанная компанией Apple. Её должны применять не только игры и мини-приложения ВКонтакте, но и любые другие приложения, представленные в App Store и содержащие встроенные сервисы. Но разработчику игр не нужно самостоятельно в этом разбираться, достаточно отправить нам ресурсы, а всю остальную работу берёт на себя ВКонтакте.

### Шаг 1. Подготовка файлов

Чтобы подготовить файлы ресурсов:
1. В файлах с кодом игры `.html` укажите относительные пути ко всем файлам ресурсов, которые нужны вашей игре. Например: `.css`, `.js`, файлы шрифтов и графические файлы.
1. Убедитесь, что вы указываете путь к текущему каталогу, а не к корневому. Правильно: `"./main.js"`, неправильно: `"/main.js"`. Чтобы проверить, корректно ли указаны пути к ресурсам, откройте файл `.html` в браузере и убедитесь, что все они доступны.
1. Создайте ZIP-архив со всеми файлами, подготовленными на предыдущем шаге. Убедитесь, что размер архива не превышает 20 МБ.
> Если вы используете для хранения графических файлов внешний хостинг, их необязательно добавлять в архив.
 
> Если файлы со ссылками на ресурсы (например, `.php`) генерируются на сервере только в момент запуска игры, их нельзя передать в архиве. Для запуска на iOS необходимо создать статическую версию проекта, которая будет содержать `.html`.

### Шаг 2. Загрузка архива

1. Откройте [Мои приложения](https://vk.com/apps?act=manage) → **Редактировать** → **Настройки**.
2. В разделе **Загрузка архива для ODR** нажмите на кнопку **Загрузить архив**.
3. В открывшемся окне введите версию архива и загрузите его.
4. Нажмите на кнопку **Отправить на модерацию**, чтобы подать заявку на проверку архива.

![](9e944695a9c4e389a2073ad926e8b89bd54a051f4b69d90dda76a201 "-7539556657217409274")
![](3d4b5f41dfb5b9c029786b6020f173ff40ecd8d079364408c07b0a51 "5196219893734301789")

После отправки вы можете отслеживать статус модерации и заменить файл при необходимости.
В этом разделе вы также сможете проверить историю изменений и выбрать администраторов, которые могут загружать архив.

**Важно!**
*  Формат файла — ZIP-архив с расширением `.zip`.
*  Максимальный размер архива — **20 МБ**.
*  Максимальный размер распакованного архива — **40 МБ**.
*  В разделе «Название архива» на этапе загрузки необходимо указывать именно версию вида v0.0.1 и обновлять данные, когда загружаете новый архив.

## CORS-ошибки

Все игры, которые запускаются в iOS-клиенте версии 6.46 и выше, используют технологию ODR. При этом файлы приложения (в том числе `index.html`) запускаются локально на устройстве пользователя. 

Так как игра запускается из файла, сохраненного локально, при сетевых запросах, необходимых для взаимодействия с сервером, в HTTP-заголовке `Origin` передаётся значение `null`. 

Если на вашем сервере настроены политики работы с [CORS](https://developer.mozilla.org/ru/docs/Web/HTTP/CORS)-заголовками, то в ответе на запросы без адреса источника вместо данных будет возвращаться CORS-ошибка. 

#### Пример текста CORS-ошибки

```
[CORS header ‘Origin’ cannot be added](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSOriginHeaderNotAdded)
```

## URL-схема vkcors

Чтобы получать данные с сервера, используйте в запросах адрес с URL-схемой `vkcors`. Это означает, что во всех HTTPS-запросах нужно заменять название протокола с `https` на `vkcors`. 

Например, если для Android-клиента (где **не** используется технология ODR) URL в сетевом запросе выглядит: 

```
let response = await fetch('https://server.io/api/endpoint');
```

То для iOS-клиента (с технологией ODR) URL должен выглядеть так: 

```
let response = await fetch('vkcors://server.io/api/endpoint'); 
```

В результате будет выполнен HTTPS-запрос, в котором заголовок `Origin` будет содержать адрес хоста из URL приложения ([Мои приложения](https://vk.com/apps?act=manage) → **Настройки** → **Версия для мобильных клиентов**). 

> **Важно!** URL-схема `vkcors` работает в iOS-клиенте версии 6.47 и выше.

##  Отладка работоспособности ODR-режима 

Протестируйте загруженный архив в [ODR-режиме](games/direct-games/on-demand-resources), чтобы отладить его работу. Сделать это можно в iOS-клиенте, начиная с версии 6.48.

#### Шаг 1

Разместите тестовую сборку в настройках игры:

![](6cf1ab4dcc625d9edb68d0fcfffc0ff5df6e0b8dabd3976ec1125b6e "-7350911190793064709")

#### Шаг 2

Вы можете управлять администраторами игры, для которых будет доступна опция тестирования ODR-архива. Для этого нажмите на кнопку **Тестирование ODR**:

![](bb1ebabbbc9a6646ca60438a4d31109340078fffd24c9fccc072dffb "6020910357886245279")

В списке администраторов игры выберите пользователей, для которых необходимо включить тестовый режим ODR, затем нажмите на кнопку **Сохранить**:

![](f0cf459e54674f356739a20f875b19cb7551afd3b984e3a392601e73 "2324552160813925357")

#### Шаг 3

Теперь игру можно открыть на клиенте — при этом оно загрузится в режиме тестирования архива ODR. Это означает, что будут использованы файлы из последнего загруженного вами архива.

Как проверить и удостовериться, что игра запущена именно в режиме тестирования архива ODR? Нажмите на три точки в правом верхнем углу экрана игры. В верхней части action menu будет видна пометка **В режиме теста ODR**:

![](649b4a40796e5cee91ae5113ede728866178ec0b83e0a86f5c372d98 "6631700604518269076")

## FAQ

### Что такое ODR?

Для организации ресурсов игр используется технология [ODR](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/On_Demand_Resources_Guide/index.html) (On-Demand Resources), разработанная компанией Apple. Суть её в том, что при первом запуске файл `index.html` с кодом игры и файлы ресурсов сохраняются на устройстве пользователя. То есть после первого запуска игра будет запускаться из файла, сохраненного локально. 

### Каким должен быть архив для ODR?

Создавая версию игры по ODR, обратите внимание на следующие моменты:
1. Важно, чтобы в консоли разработчика отображался только локальный путь, то есть в архив надо спрятать всё, что интерпретируется как код (CSS, HTML, JS). Исключением могут быть только аналитические сервисы.
2. Медиа и данные не обязательно размещать в архиве (грузить `json` и интерпретировать их как код не нужно). Рекомендуем размещать в архиве только те материалы, которые нужны для первого запуска.
3. Максимальный размер архива — 20 МБ, после распаковки — 40 МБ. Если архив тяжелее, вынесите из него данные или медиа.
4. В консоли разработчика не должны отображаться ошибки CORS. Проверьте, чтобы во всех HTTPS-запросах было заменено название протокола с `https` на `vkcors`.

###  Как понять, что игра использует для запуска технологию ODR?

Технология ODR используется во всех версиях iOS-приложения ВКонтакте версии 6.46 и выше. 
Также в [параметрах запуска](mini-apps/development/launch-params) будет передаваться: `odr_enabled=1`.  

```
https://prod-app.com/index.html?vk_access_token_settings=&vk_app_id=6909581& ... &odr_enabled=1
```

### Что такое CORS?

Cross-Origin Resource Sharing – это механизм, который позволяет безопасно выполнять кроссдоменные запросы, то есть обращаться к ресурсам на другом домене.

### Как пройти модерацию?

После того как вы подготовили архив и проверили, что он работает, загрузите его в управлении приложением (раздел **Настройки** → **Загрузка архива для ODR iOS**). После загрузки отправьте архив на модерацию. Обратите внимание, что вы не сможете загрузить новый файл, пока модерация не завершится.
![](ac226dc43ab85de4ebac5aa3cf6ad19f53bb79f4991520afd0165a12 "-1607163739561000137")
Если модерация пройдена, появится такое уведомление:
![](43c407415ea91a08868a375ff1022e5186000a30c1f9a23fea62abf8 "-5779715356892325524")
После выхода новой версии приложения вы увидите уведомление о том, что ваша игра доступна в приложении.
![](41d3a0053152fc62c5ed034c3ec39a5e18804ddde8bc9584a98337a4 "-3644968790750542785")
В случае отказа вы получите комментарий модератора.
![](f13058416e2953b953f9fc954924ea080fd5f1ccc3b69864ac9dc05a "-7750181643914557940")

### Сколько времени занимает прохождение модерации?

В зависимости от сроков выхода новой версии приложения ВКонтакте в AppStore модерация корректно работающего архива занимает около двух недель.

###  Как обновлять приложение после прохождения модерации?

Если вам необходимо обновить архив, вы загружаете новую версию в раздел **Загрузка архива для ODR iOS**.

Обратите внимание:
*  Архив обновится в приложении только после обновления приложения ВКонтакте в AppStore. Это происходит примерно раз в неделю.
*  Если новый архив будет некорректным, игра будет удалена из каталога на iOS.

Если ваша игра останавливается на экране загрузки, скорее всего, не вызывается `VKWebAppInit` и [необходимо проверить работу CORS](games/direct-games/on-demand-resources#CORS-ошибки).

### Можно ли просто отвечать на запросы с любых доменов?

Можно использовать HTTP-заголовок ответа Access-Control-Allow-Origin — только если вы полностью осознаете последствия. Мы не рекомендуем этот подход, так как в этом случае доступ к ресурсам открыт для любого источника. 

### Как проверить версию клиентского приложения ВКонтакте?

Вызовите событие [`VKWebAppGetClientVersion`](bridge/VKWebAppGetClientVersion). Пример: 

```JavaScript
const checkVersion = (a, b) => {

 const [majorA, minorA] = String(a).split('.').map(v => Number.parseInt(v));
 const [majorB, minorB] = String(b).split('.').map(v => Number.parseInt(v));

 if (majorA !== majorB) {
  return majorA > majorB;
 }

 return minorA > minorB;

};

const params = new URLSearchParams(location.href);
const {
 version
} = await bridge.send('VKWebAppGetClientVersion');
let scheme = 'https';

if (params.get('odr_enabled') === "1" && checkVersion(version, '6.46')) {
 scheme = 'vkcors';
}

let response = await fetch(`${scheme}://server.io/api/endpoint`);
if (response.ok) {
 let json = await response.json();
} else {
 alert('Ошибка: ' + response.status);
}
```

Игры | Direct Games | Работа с ресурсами для iOS

# Права доступа

Игре могут потребоваться разрешения на доступ к данным пользователя. Например, чтобы получить список друзей или отправлять уведомления. Разрешения можно запросить при первом запуске или во время игры.

![](260c42caf5f0ca0c2d6fe47d11337eacc4441a7af23b04903693e80f "-5045488956225453333")

## Для кого этот раздел

Инструкции в этом разделе касаются только Direct Games и работы с ключом доступа. Если вы отправляете запрос к API с сервера и используете для этого сервисный ключ доступа (см.  [Мои приложения](https://vk.com/apps?act=manage) → **Редактировать** → **Настройки**), то вам не потребуется информация из этого раздела. 

## Режимы запроса прав

*   **При запуске игры** — если вы хотите получать какие-либо права на информацию пользователя при первом запуске игры.
*  **По мере необходимости** — если вы хотите запрашивать права доступа во время игры.  Этот режим используется во всех играх по умолчанию.
*  **По мере необходимости (тестовый режим)**. Если вы хотите, чтобы режим **По мере необходимости** работал только для пользователей, добавленных в список тестировщиков, то используйте этот режим. В нём у всех пользователей, кроме тестировщиков, права будут запрашиваться в режиме **При запуске игры**.

Чтобы увидеть окно запроса прав в разных режимах, откройте приложение https://vk.com/app7851579 (**По мере необходимости**) и https://vk.com/app7170524 (**При запуске игры**). 

> **Совет.** Обратите внимание на различия в режимах, а также на то, как отличаются запросы к API. Для этого перейдите на вкладку **Запросы API** и попробуйте отправить какой-нибудь запрос из списка.

## Выбор прав, выдаваемых игре при первом запуске

Если игра использует для веб-версии или Direct Games запрос прав **При запуске игры**, то возможно выбрать права, которые будут запрашиваться при первом входе пользователя в игру. При выборе режима **По мере необходимости** их выбор невозможен.

Чтобы выбрать, какие данные будет запрашивать игра при первом запуске:
1. Откройте [Мои приложения](https://vk.com/apps?act=manage) → **Редактировать** → **Настройки**.
2. В разделе **Запрос прав** в поле **Права доступа при запуске** выберите, какие именно данные будет использовать игра.

В разделе **Запрос прав** в поле **Первый запрос к API** вы можете указать запрос. Убедитесь, что на момент выполнения кода игра имеет необходимые доступы.
Например, метод [`users.get`](users.get) будет успешно выполнен в первом запросе к API, так как он не требует дополнительных прав. Но метод [`friends.getAppUsers`](friends.getAppUsers) будет успешно выполнен только после получения игрой права доступа `friends`.

## Запрос прав для игр, использующих VK Bridge

При запуске игры вы получаете ключ доступа ко всем ранее выданным правам.
Если необходимо получить новые доступы в дополнение к уже имеющимся, то:
1. Перед тем как использовать метод, который требует доступа к данным пользователя, стоит проверить, есть ли у игры нужное разрешение. Чтобы получить список прав, вызовите событие [`VKWebAppCheckAllowedScopes`](bridge/VKWebAppCheckAllowedScopes).
2. Если нужного права нет, покажите пользователю диалоговое окно с запросом доступа. Для этого вызовите событие [`VKWebAppGetAuthToken`](bridge/VKWebAppGetAuthToken).

Если пользователь нажал на кнопку:
1. **Разрешить**. В ответе на событие вернётся ключ доступа, который будет содержать в себе все разрешённые права (право доступа, которое пользователь дал в диалоговом окне, будет добавлено к остальным). Теперь с этим ключом доступа можно выполнять запросы к API. 
2. **Запретить**. Отправить запрос к API не получится. Мы рекомендуем запрашивать только те права, которые действительно необходимы. Также не стоит запрашивать их слишком часто — раздражённые пользователи закрывают не только окно с запросом прав доступа, но и саму игру.

## Пример кода для игр, использующих VK Bridge

### Пример функции RequestApiHelper

```JavaScript
const requestApiHelper = new RequestApiHelper(appId, accessToken, allowedScopes);

requestApiHelper.trySendRequest(apiMethodName, scope, paramsMethod).then(
      //Обработка данных пользователя, полученных в ответе на запрос к API.
    ).catch(
      //Обработка ошибки, полученной в ответе на запрос к API. 
    )
```

### Входные параметры функции RequestApiHelper

*  `appId` — идентификатор приложения, который передаётся при запуске игры. 
*  `accessToken` — ключ доступа пользователя, который передаётся при запуске игры. 
*  `allowedScopes` — права, выданные игре в момент запуска. В переменной `allowedScopes` данные хранятся в объекте `Map()`. Формат элементов: `Map.set(scope, true|false)`.
*  `apiMethodName` — имя метода API ВКонтакте.
*  `scope` — права доступа, которые необходимы методу API ВКонтакте.
*  `paramsMethod`  — параметры запроса к API ВКонтакте.

### Тело функции RequestApiHelper

```JavaScript
import bridge from "@vkontakte/vk-bridge";

const VK_BRIDGE_CHECK_SCOPE_METHOD = 'VKWebAppCheckAllowedScopes';

export default class RequestApiHelper {

   constructor(appId, accessToken, allowedScopes) {
     this.appId = appId;
     this.accessToken = accessToken;
     this.scopes = allowedScopes;
   }

   async trySendRequest(method, scope, params) {
     const sendApiRequest = (method, params) => {
       return bridge.send('VKWebAppCallAPIMethod', {"method": method, "request_id": "1234", "params": 
 params});
     }

     if (bridge.supports(VK_BRIDGE_CHECK_SCOPE_METHOD) && !this.scopes.has(scope)) {
       try {
         const allowedScopes = await bridge.send(VK_BRIDGE_CHECK_SCOPE_METHOD, {
           "app_id": this.appId,
           "scopes": scope
         });
         this.scopes.set(scope, allowedScopes.some((item) => {
           return item.scope === scope && item.allowed;
         }));
       } catch (e) {
         console.error(e);
       }
     }

     if (!this.scopes.get(scope)) {
       try {
         const authTokenData = await bridge.send('VKWebAppGetAuthToken', {
           "app_id": this.appId,
           "scope": scope
         });
 
         this.accessToken = authTokenData.access_token;
         this.scopes.set(scope, true);
       } catch (e) {
         console.error(e);
       }
 
       params['access_token'] = this.accessToken;
       return sendApiRequest(method, params);
     } else {
       return sendApiRequest(method, params);
     }
   }
 }
```

## Запрос прав для игр, использующих Client API

Если игра запущена на веб-платформе и использует Client API ([JavaScript SDK](sdk/javascript)):
*  Перед тем как использовать метод, который требует доступа к данным пользователя, стоит проверить, есть ли у игры нужное разрешение. Это можно сделать двумя способами:
   * Запустите игру. Список прав, которые пользователь выдал игре, закодирован в [битовой маске](reference/access-rights) прав, которая передается вместе с другими [параметрам запуска](api/app-run-parameters), в поле `api_settings`.
   * Отправьте запрос к API: [`account.getAppPermissions`](account.getAppPermissions). 
*  Запросите права. Для этого методу [`showSettingsBox`](sdk/javascript#showSettingsBox) передайте [битовую маску](reference/access-rights) запрашиваемых прав доступа.

## FAQ

### Как узнать, какие права есть у игры в момент запуска?

Названия прав передаются в параметре `access_token_settings` при запуске игры. 

###  Когда лучше запрашивать доступ к данным?

Мы рекомендуем запрашивать доступ к данным непосредственно перед тем, как их использовать. Если запрашивать все разрешения на экране установки, который показывается при первом запуске, игра теряет больше аудитории, чем при запросах в процессе.

###  Как узнать, какие права нужны методу?

Эта информация есть в [справочнике](method), на странице метода.

![](42bb2d57df5c6af8e123202c862d890f2ad32ebd849f28ef064c1faf "8318987506215515805")

### Что такое первый запрос к API?

Первый запрос к API отправляется при запуске игры, обычно, чтобы получить какие-то пользовательские данные и затем отобразить их в интерфейсе. Например, можно получить информацию о пользователе (имя, аватар), список друзей в игре и их очки.

### Что делать, если событие VKWebAppCheckAllowedScopes не возвращает данные?

Обновите Android-приложение ВКонтакте до последней версии. Также, возможно, версия библиотеки VK Bridge, которую вы используете, не поддерживает событие. Чтобы это проверить, используйте метод:

```JavaScript
bridge.supports(‘VKWebAppCheckAllowedScopes’)
```

Чтобы обновить версию пакета, выполните команду:

```Shell
npm update @vkontakte/vk-bridge

```

Игры | Direct Games | Права доступа


# Частые вопросы

## С чего начать?

Попробуйте начать с разработки простой игры и добавьте её на платформу ВКонтакте. [Посмотрите пошаговые инструкции](games/getting-started).

## Кто может размещать игры на платформе?

Любой пользователь ВКонтакте. Регистрировать юридическое лицо для этого не обязательно. 

Для получения выплат и вывода средств надо заключить договор с ВКонтакте или с нашим партнёром AppsCentrum.  В настоящее время ВКонтакте заключает договоры только с юридическими лицами (ИП, ООО, ОАО).

## Как запустить игру на платформе?

1. Создайте игру локально и убедитесь, что она работает. Посмотрите [Первые шаги](games/getting-started).

2. Добавьте игру в список [Мои приложения](https://vk.com/editapp?act=create).

3. Отправьте заявку, чтобы опубликовать игру в каталоге. Это необходимый шаг, чтобы все пользователи увидели вашу игру. Подробнее см. [Публикация в каталоге](games/catalog/moderation).

Используйте бесплатные способы [продвижения](games/promotion/featured), чтобы привлечь игроков. Прочтите о различных возможностях [внутриигровых покупок](games/monetization/digital-goods) и [показа рекламы в играх](games/monetization/ad/overview) и реализуйте их.

## Каковы правила размещения игр?

Перед добавлением игры в каталог она должна пройти модерацию. Наши сотрудники проверят, соответствует ли игра  требованиям к играм, правилам размещения ВКонтакте и законодательству России. Подробнее о подаче заявки и последующих шагах см. [Публикация в каталоге](games/catalog/moderation).

## Какие возможности продвижения предлагает платформа?

* Фичеринг, то есть включение игры в различные подборки: жанровые, тематические, приуроченные к праздникам или дням распродажи, рекомендации и прочие. По нашему опыту, подборки &mdash; хороший способ привлечения пользователей. ВКонтакте предлагает подборки, составленные редакторами или сформированные автоматически. Большая часть подборок бесплатны для авторов игр, но есть и платные подборки. Полная информация &mdash; в разделе [Подборки](games/promotion/featured). 

* [Реклама](games/promotion/ad) игры.

* Прямые сообщения от игры пользователям, сообщения в ленту активности и другие методы. См. [рекомендации по игровой механике](games/promotion/game-mechanics) и [лучшим практикам продвижения](games/promotion/best-practices).

## Как монетизировать игру?

Игру можно монетизировать за счёт [игровых покупок](games/monetization/digital-goods), а также показа [рекламы](games/monetization/ad/overview) на игровых экранах или при переходе между ними.

## Как работают внутриигровые покупки?

За приобретение виртуальных ценностей пользователи расплачиваются [голосами ВКонтакте](mini-apps/glossary#Голос) (по умолчанию не более 2&nbsp;000 в день). Платежи могут быть разовыми или регулярными. Чтобы принимать платежи, вам необходимо [подключить Платёжный API](api/payments/getting-started) к игре. Подробнее о покупках и выводе средств &mdash; в разделе [Игровые покупки](games/monetization/digital-goods).

## Как показывать рекламу в игре?

Для показа рекламы необходимо заключить договор с нашим партнёром AppsCentrum. Реклама должна соответствовать:

* [правилам размещения рекламы в играх](ad-rules); 
* [правилам пользования сайтом ВКонтакте](https://vk.com/terms);
* законодательству России, в частности [федеральному закону «О рекламе» от 13.03.2006 № 38-ФЗ](http://www.consultant.ru/document/cons_doc_LAW_58968/).

Полная информация и рекомендации о включении рекламы в игру, а также о выводе средств &mdash; в разделе [Реклама в играх](games/monetization/ad/overview).

## Можно ли создать игру и для мобильного приложения, и для версии ВКонтакте для компьютера?

Да. Начните с создания игры для мобильного приложения ВКонтакте (создаётся с помощью Direct Games). Потом код игры можно модифицировать так, чтобы размер её окна соответствовал размеру экрана используемого устройства.

## Как сделать работу игры корректной на обоих доменах ВКонтакте, vk.com и vk.ru?

Поскольку некоторые разработчики валидируют входящие запросы и указывают в конфигурации игры адреса надёжных сайтов, не забудьте добавить домен vk.ru в white-list. Это нужно, чтобы ваша игра работала корректно у пользователей, которые запустили ее на домене vk.ru.

Если в своих играх при отправке ответов с сервера вы используете заголовок [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options), то рекомендуем внести правки по поддержке новых значений: vk.ru и m.vk.ru.

## Куда обращаться с вопросами?

Если вам необходима помощь с интеграцией игры ВКонтакте или возникли другие вопросы, [обратитесь в нашу службу Поддержки](games/support). Вы также можете поискать решение или попросить помощи в [сообществах разработчиков](games/support#Сообщества%20разработчиков).
  
## Где почитать больше о создании игр ВКонтакте?

Обратитесь к [документации игровой платформы](games/overview).


Игры | Частые вопросы

Игры | Первые шаги


Информация о показах рекламы в играх ВКонтакте переехала.
Новый адрес:

[dev.vk.com/games/monetization/ad/overview](https://dev.vk.com/games/monetization/ad/overview)

Игры | Монетизация | Реклама в играх

# Реклама в играх

## О рекламе

Когда мы говорим о рекламе в играх, то имеем в виду показ рекламных объявлений или видео в игре. Это один из способов монетизации игры и заработка на ней. Разработчики игры получают вознаграждение за показы рекламы.

## Получение рекламных материалов для показа

Игры получают рекламные материалы от рекламной сети ВКонтакте. Для получения и отображения используйте наши библиотеки: VK Bridge, VKUI, icons. Все подробности — в разделе [Как добавить рекламу в игру](games/monetization/ad/implementation).

Интегрироваться с другими рекламными сетями, а также использовать сторонний код для показа нельзя. Из этого правила есть исключение: допускается самостоятельная реклама игр и мини-приложений, которые были созданы вами и которые были опубликованы в каталогах ВКонтакте.

ВКонтакте использует специальные алгоритмы, чтобы показывать таргетированную рекламу. Другими словами, предоставляемые рекламные объявления и ролики зависят от интересов конкретного пользователя: один может видеть рекламу авиабилетов, другой — косметических средств. Библиотеки не предусматривают возможности выбора роликов и объявлений для показа.

## Требования к рекламным материалам

Рекламные материалы, размещаемые в играх, должны соответствовать:

* [Правилам размещения рекламы в играх и мини-приложениях](ad-rules).

* [Правилам пользования сайтом ВКонтакте](https://vk.com/terms).

* Законодательству РФ, в частности [Федеральному закону от 13.03.2006 № 38-ФЗ «О рекламе»](https://www.consultant.ru/document/cons_doc_LAW_58968/).

Материалы, которые ваша игра получает от ВКонтакте, уже прошли проверку. Размещая их, вы не нарушите правила.

Упомянутые выше требования описывают не только содержимое рекламных материалов, но и [правила их показа](ad-rules#В%20приложениях%20и%20сервисах%20запрещается:). Например, нельзя неожиданно прерывать игровой процесс рекламным объявлением или показывать ролик сразу после старта игры. Этим правилам должны следовать все игры вне зависимости от того, как они получают рекламный контент.

## Виды рекламы в играх

В играх можно использовать:

* [Рекламу за вознаграждение](#Реклама%20за%20вознаграждение)

* [Рекламу между экранами](#Реклама%20между%20экранами)

* [Рекламные баннеры](#Рекламные%20баннеры)

### Реклама за вознаграждение

**Реклама за вознаграждение** (rewarded ads) — видеоролик, после просмотра которого пользователь должен получить вознаграждение, не выходящее за рамки взаимодействия с игрой, например улучшение навыков главного героя или дополнительные ходы.

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

![alt=Пример рекламы за вознаграждение;title=Пример рекламы за вознаграждение](6c280410066fd2ef19a1cc20e89925f21fc360e9ce1e1afa21cd438a "-8574700508162107948")

:::note
**Важно!** Иногда вместо видеоролика при запросе рекламы за вознаграждение может появиться статичное изображение с меньшим временем показа. Это корректное поведение. Так происходит лишь в тех случаях, когда для конкретного пользователя, который запросил рекламу за вознаграждение, не было найдено подходящих объявлений.
:::

Длительность рекламы за вознаграждение — до 30 секунд.

### Реклама между экранами

**Реклама между экранами** (interstitial) — статичное изображение или короткий видеоролик, который можно отображать без подтверждения со стороны пользователя, но только в момент перехода от одного экрана приложения к другому. Например, при переходах между уровнями игры.

Длительность рекламы между экранами — до 5 секунд. Визуально она не отличается от рекламы за вознаграждение.

### Рекламные баннеры

**Рекламные баннеры** — это статичные рекламные блоки, которые можно показывать в мобильном приложении ВКонтакте. Каждый баннер может содержать текст, кнопку и одно изображение.

![alt=Пример рекламного баннера;title=Пример рекламного баннера](b0693bafd64a0020147168a9fba2b4fcbce24cb453a1e19bc0fadea4 "6670196928109031007")

В одной игре можно разместить не больше трёх блоков с рекламными баннерами.

## Как добавить рекламу в игру

Для показа рекламы, получаемой от ВКонтакте, используйте наши библиотеки: [VK Bridge](games/bridge), [VKUI](libraries/vkui) и [icons](https://github.com/VKCOM/icons). Все подробности — в разделе [Как добавить рекламу в игру](games/monetization/ad/implementation).

> После добавления рекламы в игру вам может потребоваться [подключить игру к AppsCentrum](games/monetization/ad/implementation#Подключение%20игры%20к%20AppsCentrum).

## Вывод средств

ВКонтакте ведёт статистику показов рекламы и начислений авторам. Отслеживать эти данные и выводить средства можно либо в настройках игры ВКонтакте, либо в личном кабинете компании-партнёра AppsCentrum, в зависимости от того, работаете вы по прямому договору с ВКонтакте или через нашего партнёра. Все подробности — в разделе [Вывод средств](games/monetization/withdrawal/overview).

## Материалы по теме

* [Правила размещения рекламы в играх и мини-приложениях](ad-rules)

* [Оферта на оказание услуг по размещению рекламы](apps-offer-ad)


Игры | Монетизация | Реклама в играх | Обзор

 Игры | Монетизация | Лучшие практики

# Вывод средств зарубежными разработчиками

ВКонтакте работает с зарубежными авторами игр и мини-приложений. Ниже — информация о том, как можно получить средства за показ рекламы. Вывод средств возможен на банковский счёт или электронный кошелёк.

## Требования

* Вы должны быть иностранным юридическим лицом. В настоящее время ВКонтакте не работает с индивидуальными разработчиками за рубежом.

* Для вывода средств необходимо подключиться к нашему партнёру — компании [AppsCentrum](https://appscentrum.com/).

## Вход в личный кабинет AppsCentrum

1. Откройте страницу [appscentrum.com](https://appscentrum.com/) в браузере и нажмите на кнопку **Войти через ВКонтакте**.

2. Войдите с использованием аккаунта главного администратора вашей игры.

    Подтвердите доступ к данным вашего аккаунта ВКонтакте.

Личный кабинет AppsCentrum выглядит так:


![alt=Личный кабинет AppsCentrum;title=Личный кабинет AppsCentrum](ee7e5c38ca38132f414795f60314e7bcc4bf6d1b4fcd5b2382c83963 "7499577937995034609")

| Раздел | Описание |
| --- | --- |
| **Голоса** |  Информация о начислениях за [покупки и подписки](games/monetization/digital-goods). |
| **Трансляции** | Информация о показах и начислениях за трансляции. |
| **Медиареклама** | Информация о показах и начислениях за [рекламу](games/monetization/ad/overview). |
| **Мои реквизиты** | Информация об электронных кошельках и банковских реквизитах, которые будут использованы для вывода. |
| **Служба поддержки** | Форма для связи со службой поддержки AppsCentrum. |
| **Тарифы и лимиты** | Информация о комиссионных отчислениях и ограничениях, применяемых AppsCentrum. |
| **Реклама в играх** и&#x0d;&#x0a;**Реклама в мини-приложениях** | Ссылки на документацию ВКонтакте. |

## Подключение игры

Для получения выплат необходимо подключить игру к вашему аккаунту в AppsCentrum.

1. В личном кабинете перейдите в раздел **Медиареклама**.

2. Найдите вашу игру в списке и нажмите на кнопку **Подключить**.

> Подключение игры важно. Без этого AppsCentrum не сможет показывать начисления за показ рекламы и игровые покупки.

## Просмотр статистики

1. В личном кабинете AppsCentrum перейдите на вкладку **Медиареклама** и затем нажмите на кнопку **Статистика**.

2. Выберите желаемый период, приложение и критерии разбивки данных. Нажмите на кнопку **Показать статистику**.

    Вы увидите информацию о показах рекламы и ваш заработок.  

## Вывод средств из AppsCentrum

Заработанные деньги поступят на ваш аккаунт AppsCentrum в течение 70 дней после окончания отчётного периода (месяца), во время которого они были начислены.

После того как деньги появятся на аккаунте, вы сможете получить выплату любым удобным способом: на банковскую карту, электронный кошелёк или банковский счёт. Следуйте этим шагам.

### Шаг 1. Укажите платёжные реквизиты

Для вывода средств укажите данные своего электронного кошелька или банковской карты.

1. В личном кабинете AppsCentrum перейдите в раздел [Мои реквизиты](https://appscentrum.com/user).

    В этом разделе, в блоке **Кошельки**, вы можете видеть способы вывода средств, которые поддерживает AppsCentrum.

    
    ![alt=Пример страницы «Мои реквизиты»;title=Пример страницы «Мои реквизиты»](d02704bc725089234f533de6cbe8f0014a43886d2453bd035f0aaafe "-5851390484158581116")

1. Нажмите на ссылку **подключить** для нужного вам пункта в списке и на следующем экране укажите реквизиты для перевода средств.

Вы можете указать данные нескольких электронных кошельков или банковских карт и выводить средства на разные счета.

### Шаг 2. Запросите вывод средств

1. Дождитесь, когда на вашем счету будет достаточно средств.

    Существует минимальный порог вывода. Он указан на главной странице личного кабинета AppsCentrum, а также на странице [Тарифы и лимиты](https://appscentrum.com/limits). Если начисления не достигли минимального порога, то необходимо дождаться, когда они его превысят.

1. Когда на вашем счёте будет достаточно средств, на главной странице личного кабинета появится кнопка **Запросить выплату**. Нажмите на неё.

1. На следующем экране:

    * В выпадающем списке **Способ вывода** выберите банковскую карту или электронный кошелёк, данные которых вы указали на предыдущем шаге.

        Если вы этого ещё не сделали, нажмите на ссылку **Добавить способ вывода** и укажите реквизиты.

    * В поле **Сумма** укажите желаемую сумму для перевода. Она не может быть меньше порога вывода.

    * После заполнения всех полей в конце страницы появится кнопка **Запросить выплату**. Нажмите на неё.

### Как узнать, в какие страны возможен вывод

Если в разделе [Мои реквизиты](https://appscentrum.com/user) личного кабинета AppsCentrum выбрать **Иностранная карта**, то личный кабинет покажет экран, где нужно ввести данные вашей банковской карты. В поле **Страна банка-эмитента карты** вы можете видеть страны, в которые возможен перевод.


![alt=Список стран, в которые возможен перевод средств из AppsCentrum;title=Список стран, в которые возможен перевод средств из AppsCentrum](d3ba26a2b1722a3373aaf38c08b850f3b0194b0136f7a3182cc96f61 "-1583969661206517456")

## Поддержка AppsCentrum

Вопросы о выплатах можно задать службе поддержки AppsCentrum на русском или английском языках:

* В личном кабинете, в разделе [Служба поддержки](https://appscentrum.com/support/new).

    — либо —

* По электронной почте: [info@appscentrum.com](mailto:info@appscentrum.com).

Игры | Монетизация | Вывод средств | Зарубежные авторы

# Вывод средств для физических лиц — налоговых резидентов России

Для вывода средств физические лица — налоговые резиденты Российской Федерации — должны подключиться к нашему партнёру — компании [AppsCentrum](https://appscentrum.com/).

> В настоящее время мы не работаем с физическими лицами, которые не являются налоговыми резидентами России.

## Вход в личный кабинет AppsCentrum

1. Откройте страницу [appscentrum.com](https://appscentrum.com/) в браузере и нажмите на кнопку **Войти через ВКонтакте**.

2. Войдите с использованием аккаунта главного администратора вашей игры.

    Подтвердите доступ к данным вашего аккаунта ВКонтакте.

Личный кабинет AppsCentrum выглядит так:

![alt=Личный кабинет AppsCentrum;title=Личный кабинет AppsCentrum](ee7e5c38ca38132f414795f60314e7bcc4bf6d1b4fcd5b2382c83963 "7499577937995034609")



| Раздел | Описание |
| --- | --- |
| **Голоса** |  Информация о начислениях за [игровые покупки](games/monetization/digital-goods). |
| **Трансляции** | Информация о показах и начислениях за трансляции. |
| **Медиареклама** | Информация о показах и начислениях за [рекламу](games/monetization/ad/overview). |
| **Мои реквизиты** | Информация об электронных кошельках и банковских реквизитах, которые будут использованы для вывода. |
| **Служба поддержки** | Форма для связи со службой поддержки AppsCentrum. |
| **Тарифы и лимиты** | Информация о комиссионных отчислениях и ограничениях, применяемых AppsCentrum. |
| **Реклама в играх** и&#x0d;&#x0a;**Реклама в мини-приложениях** | Ссылки на документацию ВКонтакте. |

## Подключение игры

Для получения выплат необходимо подключить игру к вашему аккаунту в AppsCentrum.

1. В личном кабинете перейдите в раздел **Медиареклама**.

2. Нажмите на кнопку **Подключить** для вашей игры.

## Просмотр статистики

1. В личном кабинете AppsCentrum перейдите на вкладку **Медиареклама** и затем нажмите на кнопку **Статистика**.

2. Выберите желаемый период, приложение и критерии разбивки данных. Нажмите на кнопку **Показать статистику**.

Вы увидите информацию о показах рекламы и ваш заработок.  

## Вывод средств из AppsCentrum

Заработанные деньги поступят на ваш аккаунт AppsCentrum в течение 70 дней после окончания отчётного периода (месяца), во время которого они были начислены.

После того как деньги появятся на аккаунте, вы сможете получить выплату любым удобным способом: на банковскую карту, электронный кошелёк или банковский счёт. Следуйте этим шагам.

### Шаг 1. Укажите платёжные реквизиты

Для вывода средств укажите данные своего электронного кошелька или банковской карты:

1. В личном кабинете AppsCentrum перейдите в раздел [Мои реквизиты](https://appscentrum.com/user).

    В этом разделе, в блоке **Кошельки**, вы можете видеть способы вывода средств, которые поддерживает AppsCentrum.

    
    ![alt=Пример страницы «Мои реквизиты»;title=Пример страницы «Мои реквизиты»](d02704bc725089234f533de6cbe8f0014a43886d2453bd035f0aaafe "-5851390484158581116")

1. Нажмите на ссылку **подключить** для нужного вам пункта в списке и на следующем экране укажите реквизиты для перевода средств.

Вы можете указать данные нескольких электронных кошельков или банковских карт и выводить средства на разные счета.

### Шаг 2. Запросите вывод средств

1. Дождитесь, когда на вашем счёте будет достаточно средств.

    Существует минимальный порог вывода. Он указан на главной странице личного кабинета AppsCentrum, а также на странице [Тарифы и лимиты](https://appscentrum.com/limits). Если начисления не достигли минимального порога, то необходимо дождаться, когда они его превысят.

1. Когда на вашем счёте будет достаточно средств, на главной странице личного кабинета появится кнопка **Запросить выплату**. Нажмите на неё.

1. На следующем экране:

    * В выпадающем списке **Способ вывода** выберите банковскую карту или электронный кошелёк, данные которых вы указали на предыдущем шаге.

        Если вы этого ещё не сделали, нажмите на ссылку **Добавить способ вывода** и укажите реквизиты.

    * В поле **Сумма** укажите желаемую сумму для перевода. Она не может быть меньше порога вывода.

    * После заполнения всех полей в конце страницы появится кнопка **Запросить выплату**. Нажмите на неё.



## Поддержка AppsCentrum

Вопросы о выплатах можно задать службе поддержки AppsCentrum:

* В личном кабинете, в разделе [Служба поддержки](https://appscentrum.com/support/new).

    — либо —

* По электронной почте: [info@appscentrum.com](mailto:info@appscentrum.com).

Игры Монетизация Вывод средств Физические лица (Россия)

# Игровая платформа

**Игры ВКонтакте** &mdash; игровая платформа для пользователей ВКонтакте. Пользователи могут легко запустить игру из интерфейса &mdash; никаких скачиваний, установок и регистрации.

Создайте и разместите игру ВКонтакте и используйте бесплатные методы продвижения для привлечения пользователей.

## Преимущества для разработчиков и издателей

* 10+ миллионов активных игроков ежемесячно.
* 500+ операций API ВКонтакте для интеграции.
* Бесплатные методы продвижения.
* Рекомендации и лучшие практики от платформы.

[Узнайте больше](games/benefits)

## Первые шаги

Игры ВКонтакте &mdash; это HTML5-приложения для мобильных устройств и компьютеров. Начните с создания простой игры и добавьте её на платформу ВКонтакте. [Посмотрите пошаговые инструкции](games/getting-started).

## Продвижение и монетизация

* [Публикация в каталоге игр](games/catalog/moderation)
* [Продвижение](games/promotion/featured)
* [Игровые покупки](games/monetization/digital-goods)
* [Реклама в играх](games/monetization/ad/overview)

## Поддержка и помощь

* [Частые вопросы](games/faq)
* [Как написать в Поддержку](games/support)
* [Сообщества разработчиков](games/support#Сообщества%20разработчиков)
  
## Полезные ссылки

* [Библиотека VK Bridge](games/bridge)
* [API ВКонтакте](https://dev.vk.com/reference)
* [Лучшие практики продвижения](games/promotion/best-practices)
* [Лучшие практики монетизации](games/monetization/best-practices)


Игры | Игровая платформа

Игры | Продвижение | Рекламные методы

# Подборки в каталоге

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

Чтобы разместить игру в каталоге, нужно [отправить её на проверку модераторам](games/catalog/moderation). 

## Подборки Direct Games и Web-игр

### Тематические подборки

В каталогах Web-игр и Direct Games формируются подборки, приуроченные к праздникам или сезонным событиям. В них редакторы каталога собирают игры, которые подготовили к этим датам крупные обновления. 

![alt=Тематическая подборка Web-игр;title=Тематическая подборка Web-игр](5a3ea79dbfa6eaa98334ce38c2b5773da46c3902ab43c879157ecc7e "-7308095302473339717")

Подборки 2022 года:
* День святого Валентина: 12–15 февраля
* День защитника Отечества: 21–24 февраля
* Международный женский день: 7–9 марта
* 9 Мая: 7–10 мая
* Летняя подборка: 13–19 июня
* Хеллоуин: 29 октября — 1 ноября
* Чёрная пятница: 26–27 ноября
* Новый год: 25–31 декабря
* Подборка на праздники: 1–10 января, 2023 год

Для участия в праздничной подборке:
1. Создайте вопрос в [Поддержку](https://vk.com/support?act=new_app) (или перейдите в **Управление игрой** → **Помощь**).
2. Укажите тему «Фичеринг в подборке: (название праздника)».
3. Опишите, какие события и праздничные акции вы подготовили в игре. 

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

Условия размещения в подборках с квадратными обложками:
* Количество активных пользователей (DAU) — не менее 3 000.
* Показатель удержания (retention rate) второго дня — 10%.
* Среднемесячная выручка на одного пользователя (ARPU) — 0,05 [голоса](mini-apps/glossary#Голос). 

Условия размещения в карусели баннеров:
* Количество активных пользователей (DAU) — не менее 7 000.
* Показатель удержания (retention rate) второго дня — 15%, а седьмого дня — 7%.
* Среднемесячная выручка на одного пользователя (ARPU) — 0,2 голоса. Если ARPU больше 2 голосов, то DAU может быть ниже.
* Среднемесячный процент платящих — не ниже 0,2%.
* Средняя выручка на одного платящего пользователя (ARPPU) — не ниже 10 голосов.

Предпочтение будет отдаваться играм, ранее не участвовавшим в подборках. В размещении может быть отказано, если мы уже получили достаточное количество заявок. 

### Sale Day

Это распродажа в каталогах Web-игр и Direct Games. Точные даты проведения мы заранее сообщаем в [сообществе для разработчиков игр](https://vk.com/gamedev). Во время распродажи игры, которые принимают в ней участие, предлагают игрокам скидки на внутриигровые товары, а ВКонтакте широко освещает распродажу внутри каталога и игровых сообществ, а также разыгрывает голоса между всеми пользователями, которые совершат покупки в играх в эти дни.

![alt=Распродажа в каталоге Web-игр;title=Распродажа в каталоге Web-игр](52a0ad864a81a31bf9367399a47ab39692d5d4e787149ac0d2e836a2 "-3140751153251183170")

Подробнее об условиях участия и правилах подачи заявки вы можете прочитать в [статье Sale Day](https://vk.com/@gamedev-sale-day).

### Жанровые категории

Категории объединяют игры одного жанра. 

![alt=Жанровые подборки Web-игр;title=Жанровые подборки Web-игр](5298700a8ff68b181f495b6c476de3acb761d2e060c1a131a64558a6 "635856732267769070")

## Подборки Direct Games

Для игр Direct Games существует три независимых каталога:

* Каталог в приложении для Android.
* Каталог в приложении для iOS.
* Каталог в мобильной версии ВКонтакте ([m.vk.com/apps](https://m.vk.com/apps)).

На iOS отсутствуют какие-либо методы продвижения из-за [политики размещения приложений в AppStore](https://developer.apple.com/app-store/review/guidelines/). В iOS-играх не должно быть игровых покупок. 

### Выбор редакции

![alt=Карусель баннеров «Выбор редакции»;title=Карусель баннеров «Выбор редакции»](bfdb02d5193a606d60ade9ebb97ab61f5bfa5c5a58ad7dee2b384bfa "-1487859937436978738")

Выбор редакции — это карусель баннеров, располагающаяся в верхней части каталога. В карусели размещаются игры вне зависимости от даты их создания. 

Чтобы подать заявку на размещение в подборке, обратитесь в Поддержку (**Управление игрой** → **Помощь**). В вопросе укажите тему «Выбор редакции».

Для первого размещения показатели статистики не учитываются, а для повторного необходимо соблюсти два условия:
* Доход не менее 500 [голосов](mini-apps/glossary#Голос) в сутки.
* Среднее количество зарабатываемых голосов в день выше, чем в момент согласования первого размещения.

### Рекомендации

Игра занимает место в подборке в соответствии с позицией в рейтинге, составленном нашими алгоритмами. 

![alt=Подборка «Рекомендации»;title=Подборка «Рекомендации»](cb5ecb585b25d4b8be0699e9ff1517e136b9ea0f7756c8817b954540 "265654660979845649")

## Подборки Web-игр

Подборки доступны в десктопной версии сайта ВКонтакте.

### Выбор редакции

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

![alt=Карусель баннеров «Выбор редакции»;title=Карусель баннеров «Выбор редакции»](0c8d96936193b393c22aac3dce704bc60eefb3aa4d4ca493cb4ae2e2 "-6009081466497654030")

Чтобы подать заявку, обратитесь в Поддержку (**Управление игрой** → **Помощь**). В вопросе укажите тему: «Выбор редакции». 

Условия размещения в подборке:
* Игра находится в каталоге не менее месяца.
* Игра ранее была размещена в подборке **Новые**.
* Показатель удержания (retention rate) второго дня — 15%, а седьмого дня — 7%.
* Среднемесячная выручка на одного пользователя (ARPU)  — от 1 голоса (для казуальных игр может быть ниже).
* На баннере обязательно указано название игры.

Подборка **Выбор редакции** приносит игре в среднем до 50 000 установок в течение недели.

Также игру можно разместить в карусели баннеров на [платной основе](#Платные%20подборки). 

### Новые

При добавлении в подборку игра появляется на первом месте и находится там, пока не будет добавлена следующая. Всего игра находится в подборке в течение 7 дней.

![alt=Подборка «Новые»;title=Подборка «Новые»](4ad90b6617e577a93306bf1ce6195cc2c7871d795169e2e654220905 "3579861364971289211")

Подать заявку можно в разделе **Модерация** в настройках. Если заявка отклонена, внесите изменения в игру и отправьте заявку повторно. 

Условия размещения в подборке:

* Игра прошла [модерацию](games/catalog/overview) менее 6 месяцев назад.
* Среднемесячный показатель удержания (retention rate) второго дня — более 4%.
* Визуальная часть игры соответствует необходимым критериям на 2022 год (критерии определяют модераторы). 

Размещение в подборке **Новые** в среднем приносит игре до 10 000 установок в течение недели.

### Игра недели

Игра выбирается редакторами с учётом общих метрик приложения. 

![alt=Блок «Игра недели»;title=Блок «Игра недели»](43221a4174d57f9d9fb49452cfd42a0b5bb1baf784762c069c6827bc "-4394584950682992445")

Вы также можете подать заявку на размещение в этом блоке. Для этого обратитесь в Поддержку (**Управление игрой** → **Помощь**). Если игра понравится нашим редакторам, она может попасть в блок.

### Коллекции

Подборки, сформированные редакторами из лучших игр определённой тематики. Если вы считаете, что ваша игра подойдёт к тематической коллекции, то вы можете обратиться с просьбой о размещении в Поддержку (**Управление игрой** → **Помощь**).

![alt=Тематические коллекции;title=Тематические коллекции](f06faa03f02be7ed59e573a948a63b7b1c5992699305af29a73e1b3a "2860707546684307851")

### Продолжить играть

В этом блоке пользователю предлагается вновь запустить игры, в которые он уже играл.

![alt=Подборка «Продолжить играть»;title=Подборка «Продолжить играть»](98d3a8450b542ab3475947e15f31ebfc7283960eec0dcaf207d4fe69 "-7934091109506170221")

### Для вас

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

![alt=Подборка «Для вас»;title=Подборка «Для вас»](3674f60e2c2e67dbfa30850bc0a1ced020e6f3cb0c8e1e9c8d9f0865 "2493874143549167141")

### Популярные

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

![alt=Подборка «Популярные»;title=Подборка «Популярные»](b4584d2936729ac801b909acec983b1879600f898994831be8e5e5bd "551025918898673778")

### Друзья играют

В подборку попадают игры, в которых друзья пользователя зарабатывают достижения.

![alt=Подборка «Друзья играют»;title=Подборка «Друзья играют»](f5765110795ee1d7251d4db739bec0c3b66fa10209ea27980f4eb5d8 "168146094385106628")

## Платные подборки

Вы можете платно [разместить свою игру](games/promotion/ad#%D0%A4%D0%BE%D1%80%D0%BC%D0%B0%D1%82%D1%8B,%20%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%BD%D1%8B%D0%B5%20%D1%82%D0%BE%D0%BB%D1%8C%D0%BA%D0%BE%20%D0%B2%20%D0%B2%D0%B5%D1%80%D1%81%D0%B8%D0%B8%20%D0%B4%D0%BB%D1%8F%20%D0%BA%D0%BE%D0%BC%D0%BF%D1%8C%D1%8E%D1%82%D0%B5%D1%80%D0%B0) в рекламной подборке **Рекомендуемые игры** и в карусели баннеров. У этих рекламных объявлений существует лимит до 100 показов на одного пользователя. Запустить рекламу и настроить размещение можно в [рекламном кабинете ВКонтакте](https://vk.com/adscreate).

![alt=Рекламная подборка «Рекомендуемые игры»;title=Рекламная подборка «Рекомендуемые игры»](8d61aabad2d4eef56f9fc79eaeebd13b74f4c6261eaaa861c3689b35 "-3084504572777801193")


Игры | Продвижение | Подборки в каталоге

Игры | Продвижение | Игровые механики

# Техническая поддержка

Если вы столкнулись с проблемой, у вас возникли вопросы или появились предложения, обратитесь к нашей службе Поддержки. 

## Обращение в Поддержку

Отправить сообщение можно одним из следующих способов.

### Способ 1

Этот способ предполагает, что игра находится в списке  [Мои приложения](https://vk.com/apps?act=manage). Идентификатор игры будет автоматически добавлен в сообщение. Переписка со службой Поддержки будет доступна всем администраторам игры.

1. Откройте [Мои приложения](https://vk.com/apps?act=manage), найдите свою игру в списке приложений и нажмите **Редактировать**.

2. В меню слева выберите **Помощь** и задайте вопрос.

![alt=Переход к пункту меню Помощь;title=Переход к пункту меню Помощь](128b99f4ce6269e3233cbb6654c602f9748643752eb4999842290c0d "-4043668175900645610")

### Способ 2

Этот способ позволяет задавать вопросы, даже если игра ещё не добавлена в список [Мои приложения](https://vk.com/apps?act=manage). Переписка со службой Поддержки будет доступна только пользователю, отправившему вопрос. 

Если игра уже зарегистрирована, то укажите в своём сообщении идентификатор игры. Он создаётся автоматически при регистрации. Найти ID можно на [странице настроек игры](#Как%20узнать%20ID%20игры).   

Чтобы задать вопрос:

1. Откройте [Мои приложения](https://vk.com/apps?act=manage), в верхнем меню нажмите **Поддержка**.

2. В разделе **Обратная связь** выберите **Задать вопрос по играм** и на следующей странице введите свое сообщение.

![alt=Второй способ обращения в Поддержку;title=Второй способ обращения в Поддержку](c6210c1f877dddeea6bd6553c9bfda94e100baa676f8faca90bd0677 "-3465865249566262329")

#### Как узнать ID игры

Перейдите в [Мои приложения](https://vk.com/apps?act=manage) &rarr; **Редактировать** &rarr; **Настройки**. ID будет показан в поле **ID приложения**.

![alt=ID приложения;title=ID приложения](21951a1c9791cf2835ee686cb55b812e5b3d42d49e9ae801f9443cd2 "5421135135765762891")

## Сообщества разработчиков

Вы также можете поискать ответы, поделиться опытом или подсказать решения другим в наших сообществах:

* [VK Gamedev](https://vk.com/gamedev) &mdash; официальный клуб разработчиков игр ВКонтакте;
* [Direct Games: Клуб разработчиков](https://vk.com/directgames) &mdash; сообщество разработчиков игр для мобильных платформ.

## Другие ресурсы

* [Ответы на часто задаваемые вопросы](games/faq)
* [Игровая платформа](games/overview)

Игры | Техническая поддержка

# Документация

## Создание приложений

### [Мини-приложения](mini-apps/overview)
Создавайте полезные сервисы на каждый день с помощью кросс-платформенных приложений на базе веб-технологий: HTML, JavaScript, CSS.

### [Игры](games/overview)
Увлекайте миллионы игроков своими идеями. Ни паролей, ни скачиваний — игры мгновенно запускаются прямо из интерфейса ВКонтакте. 

### [VK Bridge](bridge/overview)
Используйте API ВКонтакте и API операционной системы, установленной на устройстве пользователя, с помощью одной библиотеки.

### [Маруся](marusia/getting-started)
Создавайте голосовой интерфейс своего продукта с помощью Маруси.

## Бизнес-инструменты

### [VK Pay](pay/getting-started)
Принимайте оплату за товары и услуги — прямо в чатах, сообществах и мини-приложениях, с баланса VK Pay или привязанных к нему карт.

### [VK Donut](api/donut/getting-started)
Управляйте платной подпиской и разнообразными программами лояльности в сообществе.

### [Рекламный API](api/ads/getting-started)
Автоматически запускайте объявления и целые рекламные кампании, обновляйте аудитории ретаргетинга и получайте статистику.

## Интеграция контента

### [Виджеты для сайтов](widgets/overview)
Предоставьте посетителям сайта возможность авторизовываться через ВКонтакте, добавлять комментарии и плейлисты, общаться в сообщениях.

### [Публикации ВКонтакте](api/posts)
Предложите пользователям делиться ВКонтакте статьями или комментариями с вашего сайта или из приложения.

### [Маски](masks/overview)
Создавайте маски — развивайте персональный бренд, заявляйте о себе и привлекайте подписчиков на личную страницу или в сообщество.

### [Чат-боты](api/bots/getting-started)
Автоматизируйте рутинные и похожие задачи с помощью чат-бота ВКонтакте.

Документация

# VK Tunnel

**VK Tunnel** — это утилита, которая позволит отобразить в интернете веб-сервер, работающий на вашем локальном компьютере.

Очень часто в веб-разработке требуется показать своё приложение другим пользователям. Если во время разработки вы пользуетесь локальным сервером, то показать промежуточные результаты на нём — нетривиальная задача. Ещё сложнее становится, когда вам нужно проверить взаимодействие приложения с внешними инструментами, например с VK Bridge, внутри мобильных приложений ВКонтакте.

После запуска VK Tunnel вы можете отслеживать в терминале информацию о состоянии и показателях соединений, установленных через ваш туннель.

> NPM: [`vk-tunnel`](https://www.npmjs.com/package/@vkontakte/vk-tunnel).

## Использование

Вы можете настроить работу через VK Tunnel для любого сервера. Ниже мы приведём пример запуска при создании VK Mini Apps из шаблона. В иных случаях внимательно изучите используемые [параметры](#Переменные%20окружения%20и%20параметры) и их значения.

### Проект мини-приложения из шаблона

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

    ```sh
    npm install @vkontakte/vk-tunnel -g
    ```

1. [Создайте мини-приложение из шаблона](mini-apps/getting-started#Создание%20мини-приложения).
1. Перейдите к папке проекта мини-приложения:

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

1. В командной строке проекта запустите его:

    ```sh
    npm start
    ```

1. Откройте новую командную строку. Вызовите VK Tunnel:
    * Через переменные окружения:

        ```sh
        cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 PROXY_HTTP_PROTO=https PROXY_WS_PROTO=wss PROXY_HOST=0.0.0.0 PROXY_PORT=10888 vk-tunnel 
        ```

    * Через параметры:

        ```sh
        vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888
        ```

1. Или добавьте в файл `package.json` скрипт `tunnel`, после чего сохраните файл:

    ```sh
    "tunnel": "vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888 app_id=8174360 endpoints=[web]"
    ```

    И вызовите VK Tunnel:

    ```sh
    npm run tunnel
    ```

1. В командной строке будет предложено перейти по адресу в формате [`https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa`](https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa) для авторизации. Откройте ссылку в браузере, вернитесь в терминал и нажмите **Enter**.
    
    После успешной авторизации в командной строке появится ссылка вида [`https://user12345-jv7zlzzz.wormhole.vk-apps.com`](https://user12345-jv7zlzzz.wormhole.vk-apps.com).
    
    Укажите её в поле **URL** в [Настройках](mini-apps/management/settings) для дальнейшей работы. Если приложение ещё не создано, воспользуйтесь разделом [Регистрация мини-приложения ВКонтакте](mini-apps/getting-started#Регистрация%20мини-приложения%20ВКонтакте).

### Проект мини-приложения на Node.js

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

    ```sh
    npm install @vkontakte/vk-tunnel -g
    ```

1. Перейдите к папке проекта мини-приложения:

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

1. Установите библиотеку `react-scripts`:

    ```sh
    npm i react-scripts
    ```

1. Создайте папку `public` и переместите в неё файл `index.html`.
1. Создайте папку `src` и переместите в неё оставшиеся статические файлы.

    > **Обратите внимание!** Каталог `src` должен иметь файл `index.js`.
    Структура каталога проекта мини-приложения:
    ```
    .
    └── mini-app
        ├── public
            └── index.html
        ├── src
            ├── cactus.png
            ├── dinosaur.png
            ├── index.js
            └── style.css
        ├── package-lock.json
        ├── package.json
        └── README.md
    ```


1. В командной строке проекта запустите его:

    ```sh
    env PORT=10888 HTTPS=true react-scripts start
    ```

1. Или добавьте в файл `package.json` скрипт `start`, после чего сохраните файл:

    ```sh
    "start": "cross-env PORT=10888 HTTPS=true react-scripts start",
    ```

    И запустите проект:

    ```sh
    npm start
    ```

1. Откройте новую командную строку. Вызовите VK Tunnel:
    * Через переменные окружения:

        ```sh
        env NODE_TLS_REJECT_UNAUTHORIZED=0 PROXY_HTTP_PROTO=https PROXY_WS_PROTO=wss PROXY_HOST=0.0.0.0 PROXY_PORT=10888 vk-tunnel 
        ```

    * Через параметры:

        ```sh
        vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888
        ```

1. Или добавьте в файл `package.json` скрипт `tunnel`, после чего сохраните файл:

    ```sh
    "tunnel": "vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888 app_id=8174360 endpoints=[web]"
    ```

    И вызовите VK Tunnel:

    ```sh
    npm run tunnel
    ```

1. В командной строке будет предложено перейти по адресу в формате [`https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa`](https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa) для авторизации. Откройте ссылку в браузере, вернитесь в терминал и нажмите **Enter**.
    
    После успешной авторизации в командной строке появится ссылка вида [`https://user12345-jv7zlzzz.wormhole.vk-apps.com`](https://user12345-jv7zlzzz.wormhole.vk-apps.com).
    
    Укажите её в поле **URL** в [Настройках](mini-apps/management/settings) для дальнейшей работы. Если приложение ещё не создано, воспользуйтесь разделом [Регистрация мини-приложения ВКонтакте](mini-apps/getting-started#Регистрация%20мини-приложения%20ВКонтакте).

## Переменные окружения и параметры

Вы можете настроить работу библиотеки при помощи переменных окружения или параметров.

### `NODE_TLS_REJECT_UNAUTHORIZED`

Флаг, который позволяет пропустить проверку самоподписанных сертификатов. Возможные значения:

* `0` — пропустить проверку;
* `1` — проверить сертификат.

Аналогом переменной окружения является параметр `--insecure`. Возможные значения:

* `0` — проверить сертификат;
* `1` — пропустить проверку.

### `PROXY_HTTP_PROTO`

Схема для протокола HTTP. Возможные значения:

* `http` — нешифрованное соединение (значение по умолчанию);
* `https` — шифрованное соединение.

Аналогом переменной окружения является параметр `--http-protocol`. Возможные значения совпадают.

### `PROXY_WS_PROTO`

Схема для WebSocket-протокола. Возможные значения:

* `ws` — нешифрованное соединение (значение по умолчанию);
* `wss` — шифрованное соединение.

Аналогом переменной окружения является параметр `--ws-protocol`. Возможные значения совпадают.

### `PROXY_HOST`

Хост, на котором запущен проект. Значение по умолчанию: `localhost`.

Аналогом переменной окружения является параметр `--host`.

### `PROXY_PORT`

Порт, на котором запущен ваш проект. Значение по умолчанию: `10888`.

Аналогом переменной окружения является параметр `--port`.

### `PROXY_TIMEOUT`

Тайм-аут запросов к вашему приложению. Значение по умолчанию: `5000` (5 секунд). Увеличьте тайм-аут, если мини-приложение получает ответ с ошибкой `Bad gateway` и вы видите в логах сообщение `Error: timeout of 5000ms exceeded`.

Аналогом переменной окружения является параметр `--timeout`.

## Файл `vk-tunnel-config.json`

Для удобства настройки утилиты в проекте мини-приложения создайте файл `vk-tunnel-config.json`, в котором укажите идентификатор мини-приложения и платформы.

Пример файла:

```JSON
{
  "app_id": "8174360",
  "endpoints": ["mobile", "mvk", "web"]
}
```

### `app_id`

Идентификатор мини-приложения.

### `endpoints`

Массив платформ, для которых нужно автоматически заменить адрес в [Настройках](mini-apps/management/settings). Возможные значения:

* `mobile` — мобильное приложение;
* `mvk` — мобильная версия сайта;
* `web` — десктопная версия сайта.

## Ошибки

### Получаю ошибку `Error: Пользователь не является создателем приложения`. Что делать?

Если при запуске утилиты вы видите ошибку `ERROR: Пользователь не является создателем приложения`, обновите токен утилиты:

```sh
rm ~/.config/configstore/@vkontakte/vk-tunnel.json
```

> **Обратите внимание!** Если ошибка сохраняется, убедитесь, что вас добавили в [администраторы](mini-apps/management/admin) мини-приложения.

### Получаю ошибку `Error: connect ECONNREFUSED 127.0.0.1:10888`. Что делать?

Убедитесь, что вы запустили проект:

```sh
npm start
```

Библиотеки | Утилита VK Tunnel

# Правила размещения приложений-магазинов

**1.** Продаваемые услуги и товары должны соответствовать [Правилам пользования сайтом Вконтакте](https://vk.com/terms) и законодательству РФ, в частности Правилам продажи товаров дистанционным способом и Закону РФ от 07.02.1992 № 2300-1 «О защите прав потребителей».
**2.** Доставка товаров должна осуществляться по всей России (или по всей территории основной страны магазина).
**3.** В приложении должна быть указана информация о правилах оплаты, доставки и процедуре возврата товаров. Если продается услуга, в приложении должна присутствовать информация о правилах оказания услуги. 
**4.** В приложении должны быть указаны контактные данные организации/продавца (телефон/email поддержки). Юридическим лицам необходимо указать свой адрес. 
**5.** Чтобы обеспечить максимальную безопасность пользователей, оплата через SMS-платежи и подписки не допускается. Прием остальных платежей возможен только через одобренные способы оплаты. С полным списком можно ознакомиться здесь: 
[Одобренные способы оплаты](authorized-payments).

**6.** Через приложения-магазины ВКонтакте запрещается распространять: 
* **6.1.** Услуги, связанные с деятельностью, запрещенной администрацией ВКонтакте. Взлом страниц, раскрутка групп и мероприятий, повышение счетчиков «Мне нравится», спам-рассылки, продажа голосов  и проч. Любые программы, автоматизированные скрипты для сбора информации на Сайте и/или взаимодействия с Сайтом.
* **6.2.** Любые лекарственные средства, медицинские товары и технику, изделия медицинского назначения, медицинские услуги и услуги оздоровительного характера. 
* **6.3.** Любые услуги астрологов, экстрасенсов, целителей, ясновидящих, предсказателей, «черных» и «белых» магов.
* **6.4.** Любую алкогольную **[1]** (в т.ч. пиво) и табачную продукцию **[2]**, курительные принадлежности (в т.ч. электронные сигареты) **[3]**, услуги компаний, занимающихся производством такой продукции. 
* **6.5.** Товары для взрослых (интим-товары, средства для повышения потенции, презервативы и т.д.), а также интимные тренинги, стриптиз-клубы, эротический массаж, эскорт-услуги и проч.
* **6.6.** Анаболические стероиды, иные препараты, специализированные пищевые продукты, воздействующие на рост мышц, действие которых аналогично действию стероидов, а также БАДы и спортивное питание.
* **6.7.** Оружие (военное и гражданское), в том числе оружие самообороны, спортивное, охотничье и сигнальное оружие. 
* **6.8.** Драгоценные камни, драгоценные металлы и изделия из них (все ювелирные украшения).
* **6.9.** Порнографические материалы. 
* **6.10.** «Цифровые наркотики» и курительные смеси, соли, попперсы, веселящие газы и любые психотропные вещества. 
* **6.11.** Услуги вебкам-студий и другие услуги, связанные с предоставлением видеообщения.
* **6.12.** Скидки и купоны.

**7.** В одобрении может быть отказано в случае, если приложение-магазин не соответствует политике, взглядам и убеждениям администрации. **[4]**

## Примечания
**[1]** — питьевой этиловый спирт, спиртные напитки (в т.ч. водка), вино (в т.ч. натуральное вино); пиво и напитки, изготавливаемые на его основе. 

**[2]** — табак, сырье для производства табачных изделий, табачные изделия в целом, а также различные виды табачных изделий, как курительные – сигареты, сигары, сигариллы (сигариты), папиросы, табак для кальяна, табак курительный, в т.ч. тонкорезаный, махорка – крупка курительная, табак трубочный, биди, кретек, так и некурительные – табак сосательный (снюс), табак жевательный, табак нюхательный, насвай; другие табачные изделия, различные ингредиенты табачных изделий. 

**[3]** — курительные принадлежности, в том числе электронные сигареты, трубки, кальяны, зажигалки и другие подобные товары; нетабачные материалы, придающие табачному изделию установленные изготовителем характеристики, особенности и форму – папиросная, сигаретная, ободковая и мундштучная бумага, оберточная бумага для фильтров (фицелла), фильтрующий материал, клеи, чернила, оберточный материал для порции табака сосательного (снюса). 

**[4]** — в числе прочего: в случаях, если предлагаются непроверенные, сомнительные товары, работы или услуги; товары и услуги, которые по личному мнению администрации потенциально могут нарушать права, причинить вред или угрожать безопасности пользователей или третьих лиц.

Правила | Правила размещения приложений-магазинов

#  Условия публикации скиллов Маруси 

## 1. Общие требования

**1.1.** Скилл должен представлять ценность для пользователей, помогать решать какие-либо задачи или же носить развлекательный характер.
**1.2.** Используемая в скилле информация должна соответствовать названию и функциональности скилла.
**1.3.**  Не допускается размещение бессмысленных скиллов или скиллов, вводящих в заблуждение, сообщающих пользователю заведомо ложную информацию.
**1.4.**  Запрещено выдавать скилл за официальный продукт другого приложения или бренда.
**1.5.**  Не допускается нарушение прав и интересов третьих лиц. Если в скилле используются чьи-либо торговые марки, объекты авторского права, персонажи, стороннее API и любой иной контент, исключительные права на который принадлежат третьим лицам, это необходимо согласовать с правообладателями — чтобы по нашему запросу автор скилла мог предоставить разрешение на использование этих материалов.  
**1.6.** Используемая информация не должна нарушать общепринятые нормы морали.
* **1.6.1.** Навык не должен содержать ненормативную лексику и непристойные выражения.
**1.7.** Не допускаются прямые или косвенные оскорбления в чей-либо адрес.
**1.8.**  Не следует порочить чью-либо честь, достоинство или деловую репутацию.
**1.9.**  Не допускается размещение информации, нарушающей законодательство РФ.
В частности запрещено использование информации, которая:
* **1.9.1.** содержит описания средств и способов суицида, любые подстрекательства к его совершению;
* **1.9.2.** пропагандирует и/или способствует разжиганию расовой, религиозной, этнической ненависти или вражды, пропагандирует фашизм или идеологию расового превосходства;
* **1.9.3.** содержит экстремистские материалы;
* **1.9.4.** пропагандирует преступную деятельность или содержит советы, инструкции или руководства по совершению преступных действий;
* **1.9.5.** содержит информацию ограниченного доступа, включая, но не ограничиваясь, государственную и коммерческую тайну, информацию о частной жизни третьих лиц;
* **1.9.6.** содержит рекламу или описывает привлекательность употребления наркотических веществ, в том числе «цифровых наркотиков» (звуковых файлов, оказывающих воздействие на человека за счет бинауральных ритмов), информацию о распространении наркотиков, рецепты их изготовления и советы по употреблению;
* **1.9.7.** потенциально может привести к совершению противоправных действий путём введения пользователей в заблуждение или злоупотребления их доверием.
## 2. Технические требования

**2.1.** Скилл должен работать в соответствии с протоколом, описанным в [документации разработчика](marusia/getting-started).
**2.2.** Ответ скилла должен укладываться в 5 секунд.
**2.3.** Разработчик скилла самостоятельно несёт ответственность за обеспечение стабильности работы бэкенда скилла, его доступности, скорости работы и безопасности.
Мы оставляем за собой право отключить скилл, если бэкенд скилла отвечает нестабильно или медленно.
## 3. Требования к названию скилла

**Название скилла** — это фраза, которая идентифицирует скилл и отличает его от других скиллов.
Пользователь может вызвать скилл по названию: «Маруся, включи скилл <название скилла>».
Название должно соответствовать следующим требованиям:
**3.1.** быть уникальным;
**3.2.** отражать суть скилла и соответствовать его содержанию;
**3.3.** если это название бренда, то автор скилла должен быть способен подтвердить права на использование бренда;
**3.4.** не быть слишком общим, не состоять лишь из общеупотребимых слов;
**3.5.** не содержать названий сервисов и продуктов ВКонтакте, Mail.ru Group или иных третьих лиц, если для этого нет соответствующих правовых оснований.

**Название-триггер** — это сокращённая или расширенная форма названия скилла, например, аббревиатура основного названия или альтернативный способ произношения названия.
Название-триггер должно соответствовать тем же требованиям, что и название скилла.
## 4. Описание скилла

**Описание скилла** — это краткое описание его функциональности. Оно будет опубликовано в каталоге.
**4.1.** Описание должно соответствовать содержанию скилла.

Правила | Условия публикации скиллов Маруси

# Схема взаимодействия со скиллом

1. Пользователь произносит фразу для вызова скилла.
2. Получив и распознав выражение, сервер Маруси отправляет POST-запрос на Webhook URL, который вы указали в настройках.
3. Обработчик скилла должен ответить на полученный от сервера Маруси запрос. Тайм-аут ожидания ответа — 5 секунд, после чего сервер Маруси завершит сессию.

Фраза вызова скилла строится по следующей схеме:

`Слово «Маруся» + любая из дефолтных фраз вызова скилла + фраза активации`

Дефолтные фразы вызова скилла:
*  `хочу скилл/навык`;
*  `запусти скилл/навык`;
*  `включи скилл/навык`;
*  `открой скилл/навык`.

Примеры фраз, которые пользователь произносит, чтобы вызвать скилл:

`Маруся, запусти навык «Шутка дня»!` 

`Маруся, включи скилл «Шутка дня»!`

## Тестирование скилла

При создании скилла по умолчанию доступ к нему имеют только его администраторы.
Чтобы проверить скилл, авторизуйтесь в приложении «Маруся» для [Android](https://trk.mail.ru/c/d3eh07) или [iOS](https://trk.mail.ru/c/d5k4a7) через VK Connect, используя номер телефона, привязанный к учётной записи ВКонтакте. 

Запустить скилл можно как голосовой командой, так и при помощи чата в приложении.

Протестировать и исправить ошибки можно в [отладчике скиллов](https://skill-debugger.marusia.mail.ru).

## Формат POST-запроса на Webhook URL

> Обратите внимание: разработчики Маруси оставляют за собой право добавлять любые новые поля в JSON, внешний скилл не должен из-за этого ломаться.

Запрос содержит четыре поля:

### Структура запроса

| Поле | Тип | Описание |
| --- | --- | --- |
| `meta` | [`meta`](#meta) | Информация об устройстве, с помощью которого пользователь общается с Марусей. |
| `request` | [`request`](#request) | Данные, полученные от пользователя. |
| `session` | [`session`](#session) | Данные о сессии. |
| `version` | `string` | Версия протокола. Текущая — `1.0`. |

### `meta`

| Поле | Тип | Описание |
| --- | --- | --- |
| `locale` | `string` | Язык в POSIX-формате, максимум 64 символа. |
| `timezone` | `string` | Название часового пояса, включая алиасы, максимум 64 символа. |
| `interfaces` | `array` | Интерфейсы, доступные на устройстве пользователя. Сейчас всегда присылается `screen` — пользователь может видеть ответ скилла на экране и открывать ссылки в браузере. |

### `session`

| Поле | Тип | Описание |
| --- | --- | --- |
| `session_id` | `string` | Уникальный идентификатор сессии, максимум 64 символа. |
| `user_id`&#x0d;&#x0a;(deprecated) | `string` | Идентификатор экземпляра приложения, в котором пользователь общается с Марусей, максимум 64 символа.&#x0d;&#x0a;&#x0d;&#x0a;**Важно!** Это поле устарело, вместо него стоит использовать `session.application.application_id` (см. ниже). |
| `skill_id` | `string` | Идентификатор вызываемого скилла, присвоенный при создании. Соответствует полю «Маруся ID» в настройках скилла. |
| `new` | `boolean` | Признак новой сессии:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; ` true` — пользователь начинает новый разговор с вызова навыка, &#x0d;&#x0a; &nbsp;&nbsp; &bullet; `false` — запрос отправлен в рамках уже начатого разговора. |
| `message_id` | `integer` | Идентификатор сообщения в рамках сессии, максимум 8 символов. Инкрементируется с каждым следующим запросом. |
| `user` | [`user`](#user) | Данные о пользователе. Передаётся, только если пользователь авторизован. (см. ниже). |
| `application` | [`application`](#application) | Данные об экземпляре приложения (см. ниже). |
| `auth_token ` | `object` | Авторизационный токен Маруси. |

### `user`

| Поле | Тип | Описание |
| --- | --- | --- |
| `user_id` | `string` | Идентификатор аккаунта пользователя (максимум 64 символа). Уникален в разрезе: «скилл + аккаунт». |

### `application`

| Поле | Тип | Описание |
| --- | --- | --- |
| `application_id` | `string` | Идентификатор экземпляра приложения, в котором пользователь общается с Марусей (максимум 64 символа). Уникален в разрезе: «скилл + приложение (устройство)». |
| `application_type` | `string` | Тип приложения (устройства). Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `mobile`;&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `speaker`;&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `VK`;&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `other`.

### `request`

| Поле | Тип | Описание |
| --- | --- | --- |
| `command` | `string` | Пользовательский текст, очищенный от слов, не влияющих на смысл предложения. В ходе преобразования текст, в частности, очищается от знаков препинания, удаляются обращения к Марусе и слова, выражающие просьбу, например «пожалуйста», «слушай» и т. д., числительные преобразуются в числа.&#x0d;&#x0a;&#x0d;&#x0a;При завершении скилла (по команде «стоп», «выход» и так далее) в него будет передана команда `on_interrupt`, чтобы у скилла была возможность попрощаться с пользователем. |
| `original_utterance` | `string` | Полный текст пользовательского запроса, максимум 1024 символа. |
| `type` | `string` | Тип ввода, обязательное свойство. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `SimpleUtterance` — голосовой ввод;&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `ButtonPressed` — нажатие кнопки. |
| `payload` | `object` | JSON, полученный с нажатой кнопкой от обработчика скилла (в ответе на предыдущий запрос), максимум 4 096 байт. Передаётся, только если была нажата кнопка с payload.|
| `nlu` | `object` | Объект, содержащий слова и именованные сущности, которые Маруся извлекла из запроса пользователя, в поле `tokens` (`array`).|

### Пример запроса

```JSON
{
  "meta": {
    "client_id": "MailRu-VC/1.0",
    "locale": "ru_RU",
    "timezone": "Europe/Moscow",
    "interfaces": {
      "screen": {}
    }
  },
  "request": {
    "command": "какая очередь в столовой",
    "original_utterance": "какая очередь в столовой",
    "type": "SimpleUtterance",
    "payload": {},
    "nlu": {
      "tokens": [
        "какая",
        "очередь",
        "в",
        "столовой"
      ]
    }
  },
  "session": {
    "session_id": "01bfd28fe3a326-c-2-fea35db06d4-a8930",
    "user_id": "f63bc4d9e9c89abe10fbe874b5400b67c0df41f86143ec22629b00be606a1dac",
    "skill_id": "5b23aa28b9cbd41ad25-21-2-60c7-121d4b",
    "new": false,
    "message_id": 1,
    "user": {
      "user_id": "c825511e862f23f3728a58cd3b15896cd243c7460237c651944b7499c7c9a425"
    },
    "application": {
      "application_id": "f63bc4d9e9c89abe10fbe874b5400b67c0df41f86143ec22629b00be606a1dac",
      "application_type": "mobile"
    }
  },
  "version": "1.0"
}
```

## Формат ответа обработчика скилла Марусе

### Структура ответа

| Поле | Тип | Описание |
| --- | --- | --- |
| `response` | [`response`](#response) | *Обязательное*. Данные для ответа пользователю. |
| `session` | [`session`](#session) | *Обязательное*. Данные о сессии. |
| `version` | `string` | *Обязательное*. Версия протокола. Текущая — `1.0`. |

### `response`

| Поле | Тип | Описание |
| --- | --- | --- |
| `text` | `string` или `array` | *Обязательное*. Текст, который следует показать и сказать пользователю, максимум 1 024 символа. Не должен быть пустым. В тексте ответа можно указать переводы строк последовательностью `\n`. Если передать массив строк, то сообщения разобьются на баблы. |
| `tts` | `object` | Ответ в [формате TTS](marusia/tts) (text-to-speech), максимум 1 024 символа. Поддерживается расстановка ударений с помощью '+'. |
| `buttons` | `array` | Кнопки (suggest), которые следует показать пользователю. Кнопки можно использовать как релевантные ответу ссылки или подсказки для продолжения разговора. |
| `end_session` | `boolean` | *Обязательное*. Признак конца разговора:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `true` — сессию следует завершить,&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `false` — сессию следует продолжить. |
| `card` | [`card`](marusia/cards) | Описание карточки — сообщения с различным контентом. Подробнее о типах карточек и описание структур в [специальном разделе](marusia/cards). |
| `commands` | `array` | Команды. Поле позволяет передать несколько сообщений в нужном порядке. На данный момент поддерживаются только [карточки](marusia/cards). |

### `buttons`

| Поле | Тип | Описание |
| --- | --- | --- |
| `title` | `string` | *Обязательное*. Текст кнопки, максимум 64 символа. |
| `url` | `string` | URL, который откроется при нажатии на кнопку, максимум 1 024 байта. Если свойство URL не указано, по нажатию на кнопку навыку будет отправлен текст кнопки. Пока кнопки с URL не поддерживаются в приложении VK. |
| `payload` | `object` | Любой JSON, который нужно отправить скиллу, если эта кнопка будет нажата, максимум 4 096 байт. |

### `session`

| Поле | Тип | Описание |
| --- | --- | --- |
| `session_id` | `string`  | *Обязательное*. Уникальный идентификатор сессии, максимум 64 символа. |
| `user_id` | `string` | *Обязательное*. Идентификатор экземпляра приложения, в котором пользователь общается с Марусей, максимум 64 символа. |
| `message_id` | `string` | *Обязательное*. Идентификатор сообщения в рамках сессии, максимум 8 символов. Инкрементируется с каждым следующим запросом. |

### Пример ответа
```JSON
{
  "response": {
    "text": "Сейчас очередь в столовой 5 человек.",
    "tts": "Сейчас очередь в столовой пять человек.",
    "buttons": [
      {
        "title": "Надпись на кнопке",
        "payload": {},
        "url": "https://example.com/"
      }
    ],
    "end_session": true
  },
  "session": {
    "session_id": "01bfd28fe3a326-c-2-fea35db06d4-a8930",
    "user_id": "f63bc4d9e9c89abe10fbe874b5400b67c0df41f86143ec22629b00be606a1dac",
    "skill_id": "5b23aa28b9cbd41ad25-21-2-60c7-121d4b",
    "new": false,
    "message_id": 1,
    "user": {
      "user_id": "c825511e862f23f3728a58cd3b15896cd243c7460237c651944b7499c7c9a425"
    },
    "application": {
      "application_id": "f63bc4d9e9c89abe10fbe874b5400b67c0df41f86143ec22629b00be606a1dac",
      "application_type": "mobile"
    }
  },
  "version": "1.0"
}
```

Маруся | Схема взаимодействия со скиллом

# Вставка карточек

С помощью карточек скилл может отвечать различными аудиовизуальными элементами, помимо текста и речи.

Чтобы вставить карточку, добавьте объект `card` (структура описана ниже) в `response`.

## Изображения

В ответ из внешнего скилла можно вставлять картинки. Чтобы использовать своё изображение, загрузите его в специальную форму на странице редактирования информации о скилле. После этого оно отобразится рядом с формой загрузки вместе со своим идентификатором. Идентификатор изображения необходимо указывать в ответе внешнего скилла в поле `image_id`.

Обратите внимание: если вы тестируете навык через [отладчик скиллов](https://skill-debugger.marusia.mail.ru/), для работы с изображениями необходимо указать ID навыка в Webhook URL. 

## Одно изображение

### Структура объекта card для одной картинки

| Поле | Тип | Описание |
| --- | --- | --- |
| `type` | `string` | *Обязательное*. Тип карточки. Значение должно быть `"BigImage"`. |
| `image_id` | `integer` | *Обязательное*. ID изображения из раздела Медиафайлы в настройках скилла. |

### Пример ответа с одной картинкой (`BigImage`)

```JSON
{
   "response":{
       "text":"Возвращаю картинку.",
       "tts":"Возвращаю картинку.",
       "card":{
          "type":"BigImage",
          "image_id":239017
       },
      "end_session":true
   },
   "session":{
      "session_id":"574d41e0-a41e-4028-a73a-6f5b5bfed299",
      "message_id":0,
      "user_id":"6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee"
   },
   "version":"1.0"
}
```

## Набор изображений

### Структура объекта card для набора картинок

| Поле | Тип | Описание |
| --- | --- | --- |
| `type` | `string` | *Обязательное*. Тип карточки. Значение должно быть `"ItemsList"`. |
| `items` | `array` | *Обязательное*. Список изображений, каждый элемент которого является объектом с обязательным полем `image_id`. |

### Пример ответа с набором картинок (`ItemsList`)
```JSON
{
   "response":{
       "text":"Возвращаю набор картинок.",
       "tts":"Возвращаю набор картинок.",
       "card":{
           "type": "ItemsList",
           "items": [
               {"image_id": 4572392347},
               {"image_id": 4572342348}
           ]
      },
      "end_session":true
   },
   "session":{
      "session_id":"574d41e0-a41e-4028-a73a-6f5b5bfed299",
      "message_id":0,
      "user_id":"6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee"
   },
   "version":"1.0"
}
```

## Карточка мини-приложения

В скилле предусматривается ответ карточкой [мини-приложения](https://vk.com/miniapps). Для этого вам потребуется только его адрес, например: [`https://vk.com/taxi`](https://vk.com/taxi).

### Структура объекта card для мини-приложения

| Поле | Тип | Описание |
| --- | --- | --- |
| `type` | `string` | *Обязательное*. Тип карточки. Значение должно быть `"MiniApp"`. |
| `url` | `string` | *Обязательное*. Адрес мини-приложения. |

Адрес может содержать якоря и параметры, если ваша ссылка должна вести пользователя в конкретное место мини-приложения.

### Пример ответа с мини-приложением

```JSON
{
   "response":{
       "text":"Возвращаю карточку мини-приложения.",
       "tts":"Возвращаю карточку мини-приложения.",
       "card":{
            "type": "MiniApp",
            "url": "[https://vk.com/taxi"],
        },
      "end_session":true
   },
   "session":{
      "session_id":"574d41e0-a41e-4028-a73a-6f5b5bfed299",
      "message_id":0,
      "user_id":"6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee"
   },
   "version":"1.0"
}
```

## Стилизованная ссылка

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

### Структура объекта card для стилизованной ссылки

| Поле | Тип | Описание |
| --- | --- | --- |
| `type` | `string` | *Обязательное*. Тип карточки. Значение должно быть `"Link"`. |
| `url` | `string` | *Обязательное*. Непосредственно сама ссылка. |
| `title` | `string` | *Обязательное*. Заголовок ссылки. |
| `text` | `string` | *Обязательное*. Описание ссылки. |
| `image_id` | `integer` | *Обязательное*. ID изображения из раздела **Медиафайлы** в настройках скилла. |

### Пример ответа со стилизованной ссылкой (`Link`)
```JSON
{
   "response":{
       "text":"Возвращаю стилизованную ссылку.",
       "tts":"Возвращаю стилизованную ссылку.",
       "card":{
                "type": "Link",
                "url": "[https://vk.com/"],
                "title": "Заголовок",
                "text": "Описание",
                "image_id": 3572018
        },
      "end_session":true
   },
   "session":{
      "session_id":"574d41e0-a41e-4028-a73a-6f5b5bfed299",
      "message_id":0,
      "user_id":"6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee"
   },
   "version":"1.0"
}
```

## Вставка нескольких карточек

Чтобы последовательно показать несколько карточек, положите их в массив `commands` объекта `response` в нужном порядке.

#### Пример ответа с несколькими карточками
```JSON
   "response": {
       "text": "Возвращаю 2 карточки.",
       "tts": "Возвращаю 2 карточки.",
       "commands": [
           {
              "type": "BigImage",
              "image_id": 239017
           },
           {
                "type": "Link",
                "url": "[https://vk.com/"],
                "title": "Заголовок",
                "text": "Описание",
                "image_id": 3572018
           }
      ],
      "end_session":true
   },
   "session": {
      "session_id": "574d41e0-a41e-4028-a73a-6f5b5bfed299",
      "message_id": 0,
      "user_id": "6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee"
   },
   "version": "1.0"
}
```

Маруся | Вставка карточек

# Быстрый старт

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

**Скилл** — это приложение, которое работает сразу на всех платформах, где доступна Маруся. Создать его можно в этом разделе: [https://vk.com/editapp?act=create](https://vk.com/editapp?act=create). Главное, чтобы скилл соблюдал [протокол взаимодействия](marusia/api) с Марусей.

## Платформы

Сейчас Маруся работает на следующих платформах:
*  мобильное приложение ВКонтакте,
*  мобильное приложение Маруси на [iOS](https://apps.apple.com/ru/app/%D0%BC%D0%B0%D1%80%D1%83%D1%81%D1%8F-%D0%B3%D0%BE%D0%BB%D0%BE%D1%81%D0%BE%D0%B2%D0%BE%D0%B9-%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D0%BD%D0%B8%D0%BA/id1467719381) и [Android](https://play.google.com/store/apps/details?id=ru.mail.search.electroscope&hl=ru),
*  умная колонка [«Капсула»](https://capsula.mail.ru),
*  умная колонка «Капсула мини»,
*  умная колонка Prestigio Smartvoice,
*  приложение Почта Mail.ru для [iOS](https://apps.apple.com/ru/app/%D0%BF%D0%BE%D1%87%D1%82%D0%B0-mail-ru/id511310430) и [Android](https://play.google.com/store/apps/details?id=ru.mail.mailapp&hl=ru&gl=US). 

Платформа не ограничивает вас стандартным набором скиллов, который заложен в Марусе. Вы можете создавать их самостоятельно. 

Список всех скиллов Маруси можно изучить в [каталоге](https://marusia.mail.ru). 

## Создание скиллов

Создать скилл можно двумя способами:
1. Использовать конструктор [Aimylogic](https://aimylogic.com/ru), который позволяет собрать необходимый сценарий в визуальном редакторе, а затем получить готовый webhook. Его, в свою очередь, уже можно зарегистрировать в качестве скилла Маруси. 
2. Написать код самостоятельно. Для этого изучите документацию. В ней подробно описан [протокол](marusia/api), по которому Маруся взаимодействует с внешними навыками, а также порядок работы с [TTS](marusia/tts), со [звуками](marusia/sound) и [изображениями](marusia/cards). Код приложения может быть написан на любом удобном вам языке и размещён на любом сервере. Главное, чтобы webhook был доступен из интернета и воспроизводил протокол Маруси из документации. 

После того как вы создадите скилл, необходимо его зарегистрировать и отправить на модерацию. Для этого выполните следующие действия:
1. [Создайте приложение](https://vk.com/editapp?act=create) в разделе для разработчиков. 
2. Выберите **Скилл Маруси** в типах приложения. 
3. Добавьте название, которое будет совпадать с командой для активации скилла. 
4. Введите в поле **Webhook URL** адрес сервера, на котором будет размещён навык, например [`https://example.com/test-webhook`](https://example.com/test-webhook). 
5. Нажмите на кнопку **Создать скилл**. 

![](cec687cc653698c24cee3af05ceaf922b93ba80f4dade06cf9b6af77 "4940476498664586883")

Вы попадёте в интерфейс администрирования скилла. 
> Все изменения полей скилла становятся доступны на всех платформах, где работает Маруся, примерно через 1–2 минуты.

## Некоторые ограничения и советы

> В день можно добавлять не более 3 скиллов, за 5 дней — не более 10. 

Фразы для вызова должны быть специфичными и уникальными, чтобы мы могли использовать их для внешних скиллов. Например, фразу «Расскажи анекдот» мы добавить не сможем, так как она уже используется во внутренних скиллах Маруси. А вот фразу «Давай сделаем код-ревью» — пока свободна и подойдёт для внешнего скилла. 

> Обратите внимание: имя «Маруся» будет первым словом фразы и триггером для вызова скилла.
>
> Длина фразы активации не может превышать 64 символа.