# 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). 

Получить сервисный ключ доступа можно в [настройках вашего приложения](mini-apps/management/settings). Ключ не привязан к IP-адресу при использовании с открытыми методами, срок его действия не ограничен. Если ключ был скомпрометирован, вы можете сгенерировать новый ключ, при этом старый будет аннулирован.

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

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

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


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

# 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 для получения ключа доступа пользователя

# 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) используемого языка.

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

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

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

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

Установка виджетов доступна из приложений, которые поддержали у себя эту возможность. Например: «Рассылки», «Тесты», «Пожертвования», «Заявки», «Анкеты», «Магазин товаров» и «Цитаты» (Все они доступны в официальном каталоге приложений: [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` — для приложения. В этом случае во всех аналогичных полях виджета также должны использоваться главные фотографии (соответственно, пользователей, сообществ или приложений).

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

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

В этом руководстве вы найдете базовую информацию о принципах работы 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 для товаров

# Диалог авторизации 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

Условия размещения приложений на сайте VK.com

## Актуальные события

* [Грантовая программа Fresh Code 2022](community/events/fresh-code-2022)

## Прошедшие события

* [Код Петербурга — 2022](community/events/code-of-petersburg)
* [Mini Design Award — 2022](community/events/mini-design-award)

Сообщество

# Грантовая программа 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 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

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

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

*  `api_url` (`string`) — URL сервиса API, по которому необходимо осуществлять запросы.

*  `api_id` (`integer`) — идентификатор запущенного приложения. 

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

*  `api_result` (`string`) — результат первого запроса к API, который выполняется при загрузке приложения. 

*  `access_token` — ключ доступа для [вызова методов API](games/bridge#Использование%20VK%20Bridge). 

*  `auth_key` (`string`) — ключ, необходимый для авторизации пользователя на стороннем сервере.

*  `hash` (`string`) — хеш запроса (данные после символа # в строке адреса). 

*  `is_app_user` (`integer`, [`0`,`1`]) — если пользователь установил приложение – `1`, иначе — `0`. 

*  `is_secure` (`integer`, [`0`,`1`]) — если пользователем используется защищенное соединение – `1`, иначе — `0`. 

*  `is_play_machine `(`integer`, [`0`,`1`] — если приложение было запущено через Play Machine.

*  `language` (`integer`) — идентификатор языка пользователя, просматривающего приложение. 

*  `lc_name`, `ads_app_id` — служебные параметры. 

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

*  `platform` (`string`) — идентификатор платформы, на которой запускается игра. Содержит одно из значений:

    - `html5_ios` — мобильное приложение ВКонтакте для iOS;
    - `html5_android` — мобильное приложение ВКонтакте для Android;
    - `html5_mobile` — мобильная версия сайта ВКонтакте;
    - `web` — десктопная версия сайта ВКонтакте.

*  `referrer` (`string`) — обозначение места, откуда пользователь перешёл в приложение. 

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

*  `sign_keys` (`string`) – параметры, необходимые для генерации `sign`.

*  `timestamp` (`integer`) — время генерации [`sign`](#Параметр%20sign). 

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

*  `viewer_id` (`integer`) — идентификатор пользователя, который запустил приложение. 

*  `viewer_type` — тип пользователя, который просматривает приложение.

## Параметр `sign`

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

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

### Пример проверки подписи на 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);
```

## Параметр `auth_key`

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

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

`auth_key` вычисляется на сервере ВКонтакте следующим образом:

```JavaScript
auth_key = md5(api_id + '_' + viewer_id + '_' + api_secret)
```

Здесь 
* `api_id` — идентификатор вашего приложения,
* `viewer_id` — идентификатор пользователя,
* `api_secret` — защищённый ключ (вы можете узнать его в разделе редактировании приложения на вкладке **Редактирование** → **Настройки**, поле **Защищённый ключ**).

Чтобы не производить дополнительную авторизацию пользователя на своём сервере, всегда проверяйте ключ `auth_key` на правильность.

Игры | 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).


Игры | Частые вопросы

Игры | Первые шаги

# Реклама в играх

## О рекламе

Когда мы говорим о рекламе в играх, то имеем в виду показ рекламных объявлений или видео в игре. Это один из способов монетизации игры и заработка на ней. Разработчики игры получают вознаграждение за показы рекламы.

## Получение рекламных материалов для показа

Игры получают рекламные материалы от рекламной сети ВКонтакте. Для получения и отображения используйте наши библиотеки: 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)


Игры | Монетизация | Реклама в играх | Обзор

# Игровая платформа

**Игры ВКонтакте** &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/promotion/game-mechanics) помогут оптимизировать игровой опыт пользователей в проектах на платформе и повысить ключевые игровые показатели.

## Сообщения от игры

Узнайте, на что нужно обратить внимание при работе с [сообщениями от игры](https://dev.vk.com/games/promotion/game-mechanics#%D0%A1%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D1%8F%20%D0%BE%D1%82%20%D0%B8%D0%B3%D1%80%D1%8B), а также, что делать, чтобы пользователь не ушел из игры из-за надоедливых сообщений.
![](95f2ffae74a88fae572d649859fd5a1160b72c5f661ad3aa24ca9130 "-9016895608649483083")

## Общие рекомендации

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

### Предсказуемость

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

### Количество уведомлений

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

Помните, что сообщения — личный канал коммуникации, и постоянные напоминания лишь приведут к запрету на отправку сообщений.

## Что считается хорошим тоном

Ниже представлены механики и события, которые положительно влияют на возврат игроков. 
*  Сразу после выдачи разрешения отправить игроку приветственное сообщение и объяснить, какую выгоду он получит от сообщений и почему игра решила взаимодействовать с ним подобным образом. 
*  Связать все обновления с социальными механиками, сжатыми по времени событиями, наградами и обновлениями: настал ход игрока, друг обогнал в турнирной таблице, запустилась акция или скидка, открылся турнир/чемпионат, запустились новые уровни, которых игрок ждал и т.д.
*  Показывать игроку предложение разрешить отправку ему сообщений в контексте подходящего игрового момента (модальное окно «Разрешите отправлять вам сообщения и мы напомним, когда откроется сундук» в момент запуска обратного отсчета до открытия сундука). 

Не забывайте постоянно анализировать реакцию игроков на сообщения и выяснять, какие подходы, тексты и события вызывают наибольший интерес.

## Плохие практики

Некоторые подходы и форматы общения строго запрещены на платформе. Вам нужно избегать:
*  Потери контекста перехода в игру. Например, в сообщении говорилось об акции, а при переходе в игре открылся главный экран или модальные окна до окна, связанного с темой сообщения; 
*  Отправки сообщений сразу после закрытия игры;
*  Отправки сообщений без контекста («Вернись в игру немедленно! Тут такое!»);
*  Отправки любых ссылок, уводящих за пределы ВКонтакте.

Игры | Продвижение | Лучшие практики

# Платформа

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

Маски широко используются в историях, клипах, видеозвонках и трансляциях.

![alt=Примеры масок](58f8bb9537759117f9063616564131ad64e3afe279c72199d8f6d0f0 "1294238990372714489")

На нашей платформе можно создавать:
* Маски — визуальные элементы, привязанные к точкам на лице пользователя. Например: шапки, рога, очки, причёски.
* Эффекты — визуальные элементы, не привязанные к лицу. Например: фильтры цветокоррекции, постэффекты, шейдеры.
* Интерактивы — визуальные элементы, реагирующие на какие-то события (триггеры). Например: игры, викторины, рандомайзеры.

## Первые шаги

Создайте свою первую маску с помощью [пошаговой инструкции](masks/getting-started).

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

Научитесь [просматривать и тестировать](masks/view) маску.
Посмотрите [список программ](masks/tools), которые могут пригодиться в работе. 

## Создание маски

По сути маска ВКонтакте — это папка с конфигурационным файлом и набором текстур, 3D-моделей и скриптов.

Начните изучение с того, как устроен [конфигурационный файл](masks/configuration), как работают [эффекты](masks/effects/overview) и [плагины](masks/plugins/overview).

## Скрипты

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

Прокачайте свою маску с помощью [скриптов](masks/development/script-creation) и [событий](masks/development/events/overview).

## Публикация

Чтобы каждая маска нашла свою аудиторию, мы создали [каталог](https://vk.com/masks). 

Поделитесь своей маской — отправьте её на [модерацию](masks/publication/moderation).

Маски | Платформа

Account

AppWidgets

Apps

Auth

Board

Calls

Database

Docs

Donut

DownloadedGames

Fave

Friends

Gifts

Groups

LeadForms

Likes

Market

Messages

Newsfeed

Notes

Notifications

Orders

Pages

Photos

Places

Podcasts

Polls

PrettyCards

Search

Secure

Stats

Status

Storage

Store

Stories

Streaming

Users

Utils

Video

Wall

Widgets

Описание методов API

Помечает текущего пользователя как `offline` (только в текущем приложении).

После успешного выполнения возвращает `1`.

account.setOffline

# Список методов секции appWidgets

appWidgets

Проверить есть ли у пользователя подарок в игре.

Идентификатор промо-акции.

promo_id

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

user_id

Идентификатор акции будет сообщен администрацией заранее при планирование проведения акции.

```json
{
  "response": 0|1
}
```

Где в поле `response` хранятся данные о наличии подарка в игре:
`1` - у пользователя есть активный подарок, нужно выдать подарок пользователю в игре и затем погасить его используя метод `apps.promoUseGift`.
`0` - у пользователя нет активного подарка в вашей игре.

apps.promoHasActiveGift

Позволяет восстановить доступ к аккаунту, используя код, полученный через SMS.

> Данный метод доступен только приложениям, имеющим доступ к [Прямой авторизации](api/direct-auth).

1105

Номер телефона пользователя.

phone

last_name

В случае успеха метод возвращает объект содержащий следующие поля:
* `success` – `1`;
* `sid` – параметр необходимый для получения доступа по коду.

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

```
https://oauth.vk.com/token?grant_type=restore_code&client_id={Идентификатор приложения}&client_secret={Секретный_ключ}&username={Номер телефона}&scope={Список прав доступа}&sid={Параметр, получаемый в данном методе}&code={Код полученный через SMS}
```

Список параметров:
* `grant_type` – необходимо передать значение: `restore_code`;
* `client_id` – Идентификатор приложения;
* `client_secret` – Секретный ключ;
* `username` – Номер телефона по которому был восстановлен пароль;
* `scope` – список [прав доступа, разделенных через запятую](reference/access-rights);
* `sid` – идентификатор сессии, полученный в результате выполнения этого метода;
* `code` – код, полученный через SMS.

В результате авторизации через `restore_code` OAuth вернет данные аналогичные обычной авторизации, с дополнительным параметром `change_password_hash` необходимым для метода [`account.changePassword`](method/account.changePassword).

auth.restore

Удаляет сообщение темы в обсуждениях сообщества.

Восстанавливает удаленное сообщение темы в обсуждениях группы.

board.restoreComment

Добавляет новый комментарий в обсуждении.

board.createComment

Редактирует одно из сообщений в обсуждении сообщества.

board.editComment

Идентификатор сообщества.

group_id

Идентификатор обсуждения.

topic_id

Идентификатор комментария в обсуждении.

comment_id

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

board.deleteComment

Методы этой секции предоставляют доступ к базе данных учебных заведений ВКонтакте. Доступ к данным является бесплатным и не требует авторизации, однако количество запросов с одного **IP** адреса может быть ограничено, при необходимости делать большое количество запросов рекомендуется выполнять запросы с клиентской стороны, используя [JSONP](api/api-requests).

database

Возвращает список стран.

`1` — вернуть список всех стран.

need_all

Перечисленные через запятую двухбуквенные коды стран в стандарте [ISO 3166-1 alpha-2](reference/country-codes), для которых необходимо выдать информацию.

Пример значения `code`:

```
RU,UA,BY
```

code

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

offset

Количество стран, которое необходимо вернуть.

count

После успешного выполнения возвращает объект, содержащий число результатов в поле `count` и массив объектов, описывающих страны, в поле `items`.

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

`id`
`integer`
Идентификатор страны. 

`title`
`string`
Название страны.

Если не заданы параметры `need_all` и `code`, то возвращается краткий список стран, расположенных наиболее близко к стране текущего пользователя. Если задан параметр `need_all`, то будет возвращен список всех стран. Если задан параметр `code`, то будут возвращены только страны с перечисленными [ISO 3166-1 alpha-2](reference/country-codes) кодами.

database.getCountries

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

Количество документов, информацию о которых нужно вернуть. 
По умолчанию: все документы. Максимальное количество документов, которое можно получить: 2000.

Смещение, необходимое для выборки определенного подмножества документов. Максимальное значение: `1999`.

Фильтр по типу документа.

Возможные варианты:
*  `1` — текстовые документы;
*  `2` — архивы;
*  `3` — gif;
*  `4` — изображения;
*  `5` — аудио;
*  `6` — видео;
*  `7` — электронные книги;
*  `8` — неизвестно.

type

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

> Обратите внимание, идентификатор сообщества в параметре `owner_id` необходимо указывать со знаком `«-»` — например, `owner_id=-1` соответствует идентификатору сообщества [ВКонтакте API](https://vk.com/apiclub) (club1).

owner_id

return_tags

После успешного выполнения возвращает объект, содержащий число результатов в поле `count` и массив объектов [файлов](reference/objects/doc) в поле `items`.

docs.get

Возвращает информацию о документах по их идентификаторам.

идентификаторы документов, информацию о которых нужно вернуть.
Пример значения `docs`:

```
66748_91488,66748_91455
```

Метод поддерживает передачу [`access_key`](reference/objects).

docs

После успешного выполнения возвращает объект, содержащий число результатов в поле `count` и массив объектов [документов](reference/objects/doc) в поле `items`.

docs.getById

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

Код алгоритма в VKScript-формате, похожем на JavaSсript или ActionScript (предполагается совместимость с ECMAScript). Алгоритм должен завершаться командой `return %выражение%`. Операторы должны быть разделены точкой с запятой.

> Внутри `code` может содержаться не более 25 обращений к методам API.

func_v

### Пример значения параметра `code`

```VKScript
// Присваивает переменной a результат поиска по фотографиям с данными параметрами. 
var a = API.photos.search({"q":"Nature","count":3});

// Присваивает переменной b список владельцев найденных фотографий.
var b = a.items@.owner_id;

// Присваивает переменной с данные о страницах владельцев из списка b. 
var c = API.users.get({"user_ids":b});

// Возвращает список фамилий из данных о владельцах.
return c@.last_name;

// Пример цикла.
var a = 1; 
var b = 10; 
while (b != 0) { 
    b = b - 1; 
    a = a + 1; 
}; 
return a;
```

То же самое можно более коротко записать так:

```VKScript
return API.users.get({"user_ids": API.photos.search({"q":"Beatles", "count":3}).items@.owner_id})@.last_name;
```

Поддерживаются:
* арифметические операции,
* логические операции,
* создание массивов и списков ([X,Y]),
* `parseInt` и `parseDouble`,
* конкатенация (`+`),
* конструкция `if`,
* фильтр массива по параметру (`@.`),
* вызовы методов API, параметр `length`,
* циклы, используя оператор `while`,
* методы Javascript: `slice`, `push`, `pop`, `shift`, `unshift`, `splice`, `substr`, `split`,
* оператор `delete`,
* присваивания элементам маcсива, например: `row.user.action = "test"`,
* поиск в массиве или строке — `indexOf`, например: `"123".indexOf(2) = 1, [[1, 2, 3]].indexOf(3) = 2`. Возвращает `-1`, если элемент не найден.

В данный момент не поддерживается создание функций. 

Обращение к элементам массива с результатом какого-либо метода всего должно основываться на структуре JSON, а не XML. Например, правильным обращением является:

```VKScript
API.photos.search({"q":"Nature","count":3}).items@.owner_id;
```

А не:

```VKScript
API.photos.search({"q":"Nature","count":3}).items@.photo@.owner_id;
```

 Метод `execute` также может использоваться и для получения результатов нескольких не связанных между собой запросов.

**Пример значений параметра `code`**

```VKScript
return [API.friends.get(), API.status.get()];
return {"friends": API.friends.get(), "status": API.status.get()};
```

 В методе `execute` поддерживаются логические операции `<` (меньше), `>` (больше), `<=` (меньше или равно), `>=` (больше или равно), `==` (равно) и `!=` (не равно). В данный момент поддерживаются сравнения двух строк, двух чисел и строки и числа (в этом случае строка приводится к числу).

 Результат логического выражения может быть использован в управляющей конструкции `if...[[else...]]`:

**Пример значения параметра `code`**

```VKScript
var posts = API.wall.get({"count": 1});
 
if (posts.count<0) {
  return {"post": null, "copy_owner": null};
} else {
  var post = posts.items[0];
  var copy_owner=null;
  if (post.copy_history[0]){
    if (post.copy_history[0].owner_id > 0) {
      copy_owner = API.users.get({"user_id": post.copy_history[0].owner_id})[0];
    } else
    if (post.copy_history[0].owner_id  < 0) {
      copy_owner = API.groups.getById({"group_ids": -post.copy_history[0].owner_id})[0];
    }
    return {"post": post, "copy_owner": copy_owner};
  } else {
    return {"post": post, "copy_owner": null};
  }
}
```


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

Обратите внимание: версия API, указанная при вызове `execute`, не применяется автоматически к методам, вызываемым внутри `code`.

> **Обратите внимание!** 
> Существует ограничение на объём ответа. В случае, если данные в ответе занимают больше 5 МБ, вернётся ошибка 13 с комментарием `"response size is too big"`.


execute

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

fave

Удаляет пользователя из списка друзей или отклоняет заявку в друзья.

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

После успешного выполнения начиная с версии **5.28** возвращается объект с полями:
* `success` — удалось успешно удалить друга;
* `friend_deleted` — был удален друг;
* `out_request_deleted` — отменена исходящая заявка;
* `in_request_deleted` — отклонена входящая заявка;
* `suggestion_deleted` — отклонена рекомендация друга.

Для версии **5.27** и более старых возвращает одно из следующих значений:
* `1` — пользователь удален из списка друзей;
* `2` — заявка на добавление в друзья данного пользователя отклонена (входящая или исходящая);
* `3` — рекомендация добавить в друзья данного пользователя удалена.

friends.delete

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

gifts

Методы для работы с сообществами.

groups

Позволяет назначить/разжаловать руководителя в сообществе или изменить уровень его полномочий.

Идентификатор сообщества (указывается без знака «минус»).

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

Уровень полномочий:
* `moderator` — модератор;
* `editor` — редактор;
* `administrator` — администратор.
* `advertiser` — рекламодатель

Если параметр не задан, с пользователя `user_id` снимаются полномочия руководителя.

role

Отображать ли пользователя в блоке контактов сообщества.

is_contact

Должность пользователя, отображаемая в блоке контактов.

contact_position

Телефон пользователя, отображаемый в блоке контактов.

contact_phone

Email пользователя, отображаемый в блоке контактов.

contact_email

В случае успешного выполнения возвращает `1`.

groups.editManager

Возвращает информацию о заданном сообществе или о нескольких сообществах.

Идентификаторы или короткие имена сообществ. Максимальное число идентификаторов — 500.

group_ids

Иидентификатор или короткое имя сообщества.

Список дополнительных полей, которые необходимо вернуть. Например: 
* `activity`;
* `ban_info`;
* `can_post`;
* `can_see_all_posts`;
* `city`;
* `contacts`;
* `counters`;
* `country`;
* `cover`;
* `description`;
* `finish_date`;
* `fixed_post`;
* `links`;
* `market`;
* `members_count`;
* `place`;
* `site`;
* `start_date`;
* `status`;
* `verified`;
* `wiki_page`.

Полный список полей доступен [на этой странице](reference/objects/group). 

> Обратите внимание, для получения некоторых полей требуется право доступа `groups`. Подробнее смотрите [описание полей объекта `group`](reference/objects/group).

fields

После успешного выполнения возвращает массив [объектов](reference/objects/group), описывающих сообщества.

groups.getById

Возвращает данные для подключения к [Bots Longpoll API](api/bots-long-poll/getting-started).

Возвращает объект, который содержит следующие поля:
* `key` (`string`) — ключ;
* `server` (`string`) — URL сервера;
* `ts` (`string`) — timestamp.

groups.getLongPollServer

Позволяет задать настройки уведомлений о событиях в [Callback API](api/callback/getting-started).

В объектах, описывающих [сообщество](reference/objects/group), добавлено поле **is_messages_blocked**.

В Callback API добавлены два новых события — **message_allow** и **message_deny**. Метод [groups.setCallbackSettings](groups.setCallbackSettings) принимает два новых параметра, а метод [groups.getCallbackSettings](groups.getCallbackSettings) возвращает два новых поля, соответственно.

5.58

Идентификатор сервера.

server_id

api_version

Уведомления о новых сообщениях (`0` — выключить, `1` — включить).

message_new

Уведомления об исходящем сообщении (`0` — выключить, `1` — включить).

message_reply

Уведомления о подписке на сообщения  (`0` — выключить, `1` — включить).

message_allow

Уведомления о редактировании сообщения (`0` — выключить, `1` — включить).