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

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

# Рекламный API

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

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

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

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


## Работа с API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Примеры

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

### PHP

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

### Java

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

### JS

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

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

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

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

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

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

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

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

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

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

![](94dbda6f9957847362a13776b0676208b2cedee8d63b617201bc5742 "-8033473622113514247")

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Callback API

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

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

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

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

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

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

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

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

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

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

### Bots Long Poll API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

![](47b0490c93d3c32d6c544be551a8806fe61b18d0ea3a07e85e0fcb85 "-5636580476323788944")

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# VK Donut API

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

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

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

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

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

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

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

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

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

## Методы

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

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

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

### Пример

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

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

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

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

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

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

## События

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

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

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

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

## FAQ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Публикации ВКонтакте

## Публикации с сайтов

### Share

Для публикации ссылки на страницу вашего сайта используйте виджет [Публикация ссылок](widgets/share) или его упрощенную версию — ссылку вида [`https://vk.com/share.php?url=`](https://vk.com/share.php?url=).

![width=50%;height=200px](a0aafaec2d6784e88292f269935d0dce9d70b14e9fc87ec2bd762190 "-6087573413949829335")

### Другие виджеты

Возможность поделиться с друзьями реализована в нескольких виджетах для внешних сайтов. В каждом из этих случаев к записи на стене пользователя будет прикреплена ссылка на страницу вашего сайта, где размещен виджет:
*  [Виджет комментариев](widgets/comments) — пользователь может поделиться комментарием на своей стене. Параметр `autoPublish` позволяет настроить публикацию по умолчанию.
*  [Виджет «Мне нравится»](widgets/like) — действие **Рассказать друзьям** создает на странице пользователя запись с  опциональным комментарием.
*  [Виджет опросов](widgets/poll) — пользователь может поделиться результатом голосования в опросе. 

## Публикации из приложений

Для публикации записей из клиентских и серверных приложений используйте метод [`wall.post`](method/wall.post). Вы можете обращаться к нему напрямую, используя [классическую схему взаимодействия с API](api/api-requests), из [SDK](sdk/overview), из [Open API](api/open-api/getting-started), если речь идет о приложении-сайте. В Open API и приложениях на vk.com действие потребует подтверждения пользователя.

### Медиаконтент в записи на стене

Чтобы добавить к записи аудио, видео или фото, передайте в параметре `attachments` тип объекта и его строковый идентификатор.

Тип объекта — `audio`, `video`, `photo` или `doc`.

Строковый идентификатор — это строка, включающая идентификатор владельца объекта (`owner_id`) и идентификатор самого объекта (`audio_id`, `video_id` и т.д.).

Например, для фотографии [`photo34_408897832`](https://vk.com/photo34_408897832) в `attachments` нужно передать значение `photo34_408897832`.

```
https://api.vk.com/method/wall.post
?owner_id=-1
&message="Tanya"
&attachments="photo34_408897832"
&access_token={YOUR_ACCESS_TOKEN}
&v=:version
```

Запрос к методу [`wall.post`](method/wall.post) для публикации записи с текстом «Tanya» и прикреплённой фотографией [`photo34_408897832`](https://vk.com/photo34_408897832) на стену сообщества [`club1`](https://vk.com/club1).

Если вы хотите прикрепить новый объект к записи на стене, необходимо сначала загрузить его на сервер ВКонтакте. В зависимости от типа контента используйте один из подходов, описанных [на этой странице](api/upload). Затем используйте идентификатор загруженного объекта в параметре `attachments`.

### Предложенные и отложенные записи

С помощью [`wall.post`](method/wall.post) вы можете работать с предложенными и отложенными записями. Чтобы создать предложенную запись, передайте в `owner_id` идентификатор публичной страницы, в которой текущий пользователь не является руководителем.

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

Для публикации предложенных и отложенных записей используйте параметр `post_id`, значение для которого можно получить методом [`wall.get`](method/wall.get) с `filter`=`suggests` и `postponed` соответственно.

### Ссылки на внешние сайты

Чтобы добавить к записи сниппет ссылки с внешнего сайта (превью-изображение, заголовок и описание), передайте URL в параметре `attachments`. Например, [`https://yandex.ru/`](https://yandex.ru/). Сниппет генерируется автоматически, более подробно об этом вы можете прочитать в следующем разделе.

## Оформление внешних ссылок

### Данные сниппета

![alt=Сниппет ссылки на внешний сайт в записи на стене;title=Сниппет ссылки на внешний сайт в записи на стене](6532be6f132bb58468fa5d9b40ad6ee64076944dc2dc3dd16ba777eb "-3983918226128625608")

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

А именно:
*  Заголовок. Если на странице есть теги `og:title`, `mrc__share_title` или `twitter:title`, то заголовок будет взят из одного из них (указанного первым), иначе будет использован тег `<title>`. 
*  Иллюстрация. Если на странице есть тег `vk:image`, то адрес изображения для иллюстрации будет взят из него. Если такого тега нет, проверяется содержимое тегов `og:image`, `twitter:image`, `image` — адрес изображения для иллюстрации будет взят из указанного первым, иначе будут взяты первые 8 тегов `<img src="...">`, и из них предложены в качестве иллюстрации те картинки, размер которых по ширине и высоте превышает 160 пикселей. 

Мы рекомендуем использовать картинки размером не менее 510x228 пикселей. В этом случае ссылка будет сопровождаться увеличенной картинкой (510x228 пикселей) в сниппете на стене. Если картинка имеет меньший размер (но не менее 160 пикселей по каждой из сторон), или к записи помимо ссылки прикреплены другие вложения, картинка в сниппете будет уменьшенная — 150x83 пикселя.

Например, указать заголовок и картинку для сниппета можно так: 

```HTML
 <head>
 <meta property="og:title" content="Заголовок страницы" />
 <meta property="vk:image"  content="https://pp.vk.me/c629531/v629531034/3172e/xEBYyER1WE4.jpg" />
</head>
```

Обратите внимание, данные для публикации могут кэшироваться. Если вы изменили данные на своем сайте, а ВКонтакте при публикации отображаются старые значения, сбросьте кэш для ссылки на странице [`pages.clearCache`](method/pages.clearCache).

## Предпросмотр содержимого страниц сайтов

В записях сообщества можно размещать ссылки на статьи, содержимое которых пользователь сможет посмотреть в интерфейсе ВКонтакте без перехода на внешний сайт. В таких записях появляется кнопка **Просмотреть**. Нажав на неё, пользователь увидит содержимое статьи на странице с адресом, начинающимся с `https://vk.com/@`, который будет сформирован автоматически. 

![alt=Кнопка предпросмотра под записью;title=Кнопка предпросмотра под записью](ce804419bf7ada3eef0a74df08aca4e6718180ebed2cc25be2abe7ae "2184200479553297311")

Чтобы подключить предпросмотр для ссылок с вашего сайта, пожалуйста, напишите в [Поддержку](https://vk.com/support?act=new_api). В заявке необходимо указать ссылки на несколько примеров статей, ссылку на сообщество вашего сайта ВКонтакте, а также данные о посещаемости сайта и сообщества.

Интеграция | Публикации | Публикации

# API историй

Статистика историй ВКонтакте — 12 миллионов авторов, 71 миллион историй, 4,4 миллиарда просмотров от 46 миллионов пользователей каждый месяц. Загружать истории с помощью API могут любые пользователи и сообщества.

![](d0618ed378f440b275f817e6cce855080d6a77c542f56f07848f6566 "4448781307036623856")

#### Как работать с API историй

Пошаговая инструкция при работе с API Историй ВКонтакте заключает в себе несколько шагов:

1. Авторизуйте пользователя ВКонтакте [одним из этих способов](api/access-token/getting-started) или с помощью наших SDK для [Android](sdk/android) и [iOS](sdk/ios).
2. Подготовьте историю — фотографию или видео.
3. Если вы разрабатываете мини-приложение, опубликуйте историю с помощью редактора историй (событие [`VKWebAppShowStoryBox`](bridge/VKWebAppShowStoryBox)).
4. Если вы работаете над другим приложением, размещайте историю с помощью методов секции [`Stories`](method/stories). Сначала получите адрес для загрузки с помощью [`stories.getPhotoUploadServer`](method/stories.getPhotoUploadServer), затем загрузите фотографию или видео и сохраните историю, воспользовавшись [`stories.save`](method/stories.save).

История появится в новостях у друзей и подписчиков пользователя в зависимости от настроек приватности. [С помощью API](method/stories) можно также управлять историями и следить за количеством просмотров.

API ВКонтакте | Истории | API историй 

Интеграция | Публикации | Загрузка файлов

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

# Правила для ботов

**1.** Ботам запрещено использовать подписку на сообщество, отметки «Нравится», репосты и подписку на рассылку как обязательное условие работы бота. Полная или частичная функциональность ботов не должна зависеть от того, является пользователь участником сообщества, поставил ли он отметку «Нравится», сделал ли он репост и подписался ли на рассылку. Например, если основная функция бота — обрабатывать фотографии, то он не может делать это только после подписки на сообщество.
**1.1.** Примеры запрещённых условий: «Чтобы получить арт, подпишись на меня», «Эта возможность доступна только подписчикам», «Если хочешь продолжить игру, сделай репост закреплённой записи и поставь лайк на аватар» и подобные. Такие просьбы недопустимы в переписке с пользователями, приветственном сообщении, на стене сообщества и т. д.
**1.2.** Разрешено устраивать раздачи и конкурсы на стене сообщества, благодаря которым участники могут получить пользу (игровую валюту, дополнительные жизни, бесплатные выполнения команд в платных ботах и т. д.), сделав репост, поставив лайк или написав комментарий. Например: «Раздаём 100 монет всем, кто сделает репост», «10 дополнительных бесплатных артов за репост» и т. д. 
**1.2.1.** Любые раздачи и конкурсы должны соответствовать [Правилам проведения конкурсов ВКонтакте](https://vk.com/page-59800369_53731448).

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

**3.** Просьбы подписаться на сообщество, поставить лайк, сделать репост и т. д.
**3.1.** Пока бот обрабатывает запрос от пользователя и не выполнил свою команду, ему не следует отправлять такие просьбы. Примеры неправильного ответа: «Пока ждёшь арт, подпишись», «Запрос принят в обработку, не забудь поставить лайк на закреплённую запись». 
**3.2.** Подобные просьбы недопустимы в приветственном сообщении сообщества. 
**3.3.** Подобные просьбы разрешено рассылать не более одного раза в сутки и только после выполнения основной функции бота.
**3.4.** Подобные просьбы разрешено отправлять только в сообщениях, которые отвечают за запрос пользователя, например: «Держи обработанную фотографию. Если тебе нравится наш бот — подпишись на сообщество, чтобы быть в курсе всех новостей».

**4.** Название команды должно ясно и чётко отражать действие, которое произойдёт в результате её выполнения.
**4.1.** Если по команде бота пользователю будут предложены ссылки на другие сообщества или сайты, не имеющие прямого отношения к боту или касающиеся его косвенно, команда должна иметь соответствующее название или содержать предупреждение. Например, если при выполнении команды бот пришлёт ссылку на официальный сайт партнёра, команда должна так и называться: «Ссылка на оф. сайт партнёра».
**4.2.** Запрещено вводить пользователя в заблуждение, намерено указывая неправильные названия команд.

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

**6.** Бот может отправлять рекламные сообщения / рассылки пользователю, если они соответствуют [Правилам размещения рекламы в сообществах](https://vk.com/page-59800369_53731475) и [Правилам монетизации ботов](bots-rules#Правила%20монетизации%20ботов).

**7.** Администрация Сайта имеет право отключить бота, если он не соответствует вышеперечисленным правилам или противоречит стандартам Администрации. 
**7.1.** Любые рекламные сообщения / рассылки в многопользовательские беседы запрещены. При нарушении этого правила сообществу будут отключены сообщения.

**8.** При отправке сообщений, содержащих пользовательский контент, необходимо [передавать его источник](api/bots/development/messages#Сообщения%20с%20пользовательским%20контентом). Им может быть: фотография из альбома, запись, комментарий, сообщение и т. д. Наличие источника позволит избежать блокировок, если пользователи будут отправлять запрещённые [Правилами платформы](https://vk.com/terms) материалы, и может быть полезно любым ботам, пересылающим пользовательский контент. Например, ботам, позволяющим людям общаться между собой, или дейтинг-ботам с анкетами, в которых можно добавлять фотографии, указывать информацию о себе и т. д., особенно в тех случаях, когда её видят другие пользователи чат-бота.

## Правила монетизации ботов
Вы можете монетизировать бота следующими способами: 
**1.** Платная подписка. 
**1.1.** Бот может выполнять свои команды платно: давать пользователям необходимую информацию и удовлетворять их запросы за вознаграждение. Разработчик сам определяет стоимость запроса, а также настраивает систему оплаты. 
**1.2.** Бот может работать по платным подпискам разных уровней доступа к возможностям бота. 
**1.3.** Информация о платных вариантах работы бота должна быть легкодоступна и хорошо видна. Например, в меню сообщества, приветственном сообщении или в закреплённой записи. 
**1.4.** Пример платной подписки: «Получить дополнительно ещё 10 фотографий можно, оплатив 50 рублей», «Купите 30 дней неограниченного использования всех возможностей бота за 490 рублей».

**2.** Бот может просить подписаться на рекламную рассылку. Сообщения из этой рассылки пользователь должен получать не чаще, чем один раз в семь дней. 
**2.1.** За подписку на рекламную рассылку бот может предлагать выполнение какой-то команды или бонусы (это может быть игровая валюта, бесплатное выполнение платных команд бота и другое).
**2.2.** Попросить подписаться на рассылку можно в приветственном сообщении, которое задается в настройках сообщества, в основном меню бота или в его подменю. Например, можно сделать следующую структуру: «Основное меню» -> «Управление рассылкой» -> «Подписаться на рекламную рассылку». При этом запрещено просить подписаться на рассылку во время выполнения команд пользователя или в процессе взаимодействия с ботом.
**2.3.** Просьба подписаться на рассылку и кнопка, которая выполняет подписку, должна в явном виде давать понять пользователю, что он будет подписан на рекламную рассылку и будет получать сообщения не чаще, чем один раз в семь дней. 
**2.4.** После нажатия на кнопку подписки бот должен написать пользователю, что тот подписан на рекламную рассылку, и указать способ отписки. 
**2.5.** Каждое сообщение рекламной рассылки должно сопровождаться кнопкой для отписки от рассылки. 
**2.6.** Сообщение должно быть помечено интентом — `promo_newsletter`.

**3.** Бот может получить доступ к Рекламному API, если он проходит по критериям, описанным в пункте **3-1**, и прошёл модерацию командой ВКонтакте. 
**3.1.** Критерии:
**3.1.1.** Среднесуточная аудитория бота за последние 30 дней — не менее 50К пользователей.
**3.1.2.** Бот включён в сообществе более трёх месяцев.
**3.1.3.** К сообществу бота не применялось каких-либо наказаний за нарушения правил сайта за последние полгода.
**3.1.4.** Администрация оставляет за собой право отказать боту в доступе к Рекламному API, если он не соответствует правилам или противоречит стандартам Администрации.
**3.2.** После прохождения модерации бот сможет отправлять сообщения, используя Рекламный API.
**3.2.1.** В диалоге с ботом пользователю будет показано предупреждение о том, что этот бот может присылать рекламные сообщения.
**3.3.** Бот может отправлять рекламу пользователю не более одного раза в сутки и только после выполнения своей основной функции. При этом бот предварительно должен спросить у пользователя разрешение на показ рекламы.
**3.3.1.** Сообщение с приглашением получить рекламу должно в явном виде быть помечено как реклама (внутри сообщения текстом должно быть написано, что это реклама / партнёрский материал / акция и т. д.). Хороший пример такого сообщения: «Сообщение от партнёра: „Привет! Сегодня твоя анкета популярнее других. У меня есть несколько свободных мест на кастинг для фотомоделей. Одно из этих мест я решил отдать тебе. Это уникальная возможность пройти обучение и стать топ-моделью. Хочешь узнать больше?“»
**3.3.2.** Сообщение с предложением получить рекламу должно быть помечено интентом `bot_ad_invite`.
**3.3.3.** В ответ на приглашение получить рекламу пользователь может согласиться получить рекламу или отказаться от получения рекламы. 
**3.3.4.** Пользователь должен иметь возможность продолжить пользоваться ботом после отказа получить рекламу. 
**3.3.5.** Рекламное сообщение должно отправляться пользователю только после его согласия получить рекламу и должно отмечаться интентом `bot_ad_promo`.
**3.3.6.** Сообщение с предложением получить рекламу и рекламное сообщение должно соответствовать 
[правилам платформы](https://vk.com/terms) и [правилам размещения рекламы](https://vk.com/page-59800369_53731475).
**4.** При нарушении правил, перечисленных в разделе [Правила монетизации ботов](#Правила%20монетизации%20ботов), сообществу будут отключены сообщения.
**5.** Бот, которого наказали за нарушение правил сайта, автоматически отключается от возможностей Рекламного API. Получить разрешение для повторного подключения он может через Поддержку, если произошла ошибка. Либо через полгода, согласно критериям отбора сообществ.

Правила | Правила для ботов

# VKWebAppAllowMessagesFromGroup

`VKWebAppAllowMessagesFromGroup` показывает окно с запросом прав доступа на отправку сообщений от имени сообщества.

## Пример

```JavaScript
bridge.send('VKWebAppAllowMessagesFromGroup', {
  group_id: 166562603,
  key: 'dBuBKe1kFcdemzB' 
  })
  .then((data) => { 
    if (data.result) {
      // Пользователь разрешил отправку сообщений от имени сообщества
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `group_id` &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор сообщества. |
| `key` &#x0d;&#x0a;*необязательное* | `string` | Произвольная строка. Этот параметр можно использовать для идентификации пользователя. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppAllowMessagesFromGroupResult` и `VKWebAppAllowMessagesFromGroupFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `User denied`, если пользователь запретил отправку сообщений от имени сообщества.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если пользователь разрешил отправку сообщений от имени сообщества. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppAllowMessagesFromGroupResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppAllowMessagesFromGroupResult",
    data: {
      result: true
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppAllowMessagesFromGroupFailed`

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

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

 [VKWebAppAllowMessagesFromGroup](https://vk.cc/bZfqcr)


VK Bridge | Сообщества | VKWebAppAllowMessagesFromGroup

# VKWebAppCallAPIMethod

`VKWebAppCallAPIMethod` получает результат вызова метода API ВКонтакте.

## Пример

```JavaScript
bridge.send('VKWebAppCallAPIMethod', {
  method: 'users.get',
  params: {
    user_ids: '743784474,743784479',
    v: '5.131',
    access_token: 'ПОЛЬЗОВАТЕЛЬСКИЙ_КЛЮЧ_ДОСТУПА'
  }})
  .then((data) => { 
    if (data.response) {
      // Метод API выполнен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `method` &#x0d;&#x0a;*обязательное* | `string` | Имя вызываемого [метода API](methods). |
| `params` &#x0d;&#x0a;*обязательное* | `object` | Параметры метода API. Возможные поля:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `access_token` (`string`) — ключ доступа пользователя с соответствующими правами, полученный с помощью события [`VKWebAppGetAuthToken`](bridge/VKWebAppGetAuthToken).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `v` (`string`) — версия API, используемая для запроса (последняя доступная версия: `:version`).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; другие обязательные параметры метода API. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppCallAPIMethodResult` и `VKWebAppCallAPIMethodFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `response` | `array[object]` | Результат выполнения метода API. Описание структуры объекта `response` можно найти на странице соответствующего метода. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppCallAPIMethodResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppCallAPIMethodResult",
    data: {
      response: [
        {
          id: 743784474,
          first_name: "Персик",
          last_name: "Рыжий",
          can_access_closed: true,
          is_closed: false
        },
        {
          id: 743784479,
          first_name: "Сеня",
          last_name: "Хомяк",
          can_access_closed: true,
          is_closed: false
        }
      ]
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppCallAPIMethodFailed`

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

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppCallAPIMethod](https://vk.cc/bZfnNu)


VK Bridge | Пользователи | VKWebAppCallAPIMethod

# VKWebAppGyroscopeStart

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

## Пример

```JavaScript
bridge.send("VKWebAppGyroscopeStart", {});
```

## Платформы

Android, iOS

## Параметр (Android)

* `refresh_rate` (`integer`)
Период обновления данных гироскопа в миллисекундах. Минимальное значение — 20 мс, максимальное — 1000 мс, значение по умолчанию — 1000 мс. 

> Период обновления можно задать только для Android-устройств. 

## Пример (Android)

```JavaScript
bridge.send("VKWebAppGyroscopeStart", {"refresh_rate": 500});

```

## Результат

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

```JSON
{
  "type": "VKWebAppGyroscopeStartResult",
  "data": {
   "result": true
  }
}
```

После этого данные гироскопа отправляются в событии `VKWebAppGyroscopeChanged`.
В случае ошибки или отмены действия пользователем генерируется событие `VKWebAppGyroscopeStartFailed`:

```JSON
{
  "type": "VKWebAppGyroscopeStartFailed",
  "data": {
    "error_type": "..."
    "error_data": {
      ...
    }
  }
}
```

## Формат данных гироскопа

```JSON
{
"type": "VKWebAppGyroscopeChanged",
  "data": {
    "x": "3.0",
    "y": "-1.3",
    "z": "0.0"
  }
}
```

Событие `VKWebAppGyroscopeChanged` содержит данные гироскопа о вращении устройства. Знак числа (положительное или отрицательное) указывает на направление вращения.

![](6b9a59ccbb3099e6144a5a56d07aab6ca3b02e9d91ad6bb8285c57b9 "-6293649683936718223")

### Структура объекта `data`

* `x` (`number`)
Скорость вращения устройства вокруг оси X (рад/c). 
* `y` (`number`)
Скорость вращения устройства вокруг оси Y (рад/c). 
* `z` (`number`)
Скорость вращения устройства вокруг оси Z (рад/c).

VK Bridge | Данные датчиков | VKWebAppGyroscopeStart

# VKWebAppResizeWindow

`VKWebAppResizeWindow` инициирует изменение ширины и высоты элемента IFrame. 

## Пример

```JavaScript
bridge.send("VKWebAppResizeWindow", {"width": 800, "height": 1000});

```

## Платформы

Web 

## Параметры

* `width` (`integer`, обязательный)
Ширина окна. Может принимать значения от 630px до 1000px.
* `height` (`integer`)
Высота окна. Может принимать значения от 500px до 8050px.

## Результат

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

```JSON
{ 
  "type": "VKWebAppResizeWindowResult", 
  "data": { 
    "width": 800, 
    "height": 1000 
  } 
}

```

В случае ошибки генерируется событие `VKWebAppResizeWindowFailed`.

```JSON
{ 
  "type": "VKWebAppResizeWindowFailed", 
  "data": { 
    "error_type": "..." 
    "error_data": { 
      ... 
    } 
  } 
}

```

## Песочница

[VKWebAppResizeWindow](https://vk.cc/bZfsxT)

VK Bridge | Интерфейс и навигация | VKWebAppResizeWindow

# VKWebAppShowStoryBox

`VKWebAppShowStoryBox` открывает редактор историй.

## Пример

```JavaScript
bridge.send("VKWebAppShowStoryBox", { 
  "background_type" : "image", 
  "url" : "https://sun9-65.userapi.com/c850136/v850136098/1b77eb/0YK6suXkY24.jpg"
});

```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

* `background_type` (`string`, обязательный)
Тип истории. Возможные значения: 
`image` (платформы: iOS, Android, Web, Mobile Web);
`video` (платформы: iOS, Android);
`none` (для случая передачи стикера непосредственно на камеру, платформы: iOS, Android). 
* `url` (`string`)
Ссылка на изображение или видео (нужно указать прямую ссылку на MP4).
* `blob` (`string`)
Base64-строка с BLOB (поддерживается только для `image`). Перед строкой необходимо добавить следующий префикс: `data:image/png;base64,<blob-base64>` или `data:image/jpeg;base64,<blob-base64>` в зависимости от типа изображения. 
* `locked` (`bool`)
Можно ли перемещать фотографию. 
* `attachment` (`attachment`) 
Описание [объекта, присоединённого к истории.](#Объект%20attachment) 
* `stickers` (`sticker_container []`)
Массив [объектов `sticker_container`](#Объект%20sticker_container). 

## Результат

После начала загрузки истории возвращается событие `VKWebAppShowStoryBoxResult`.

```JSON
{
  "type": "VKWebAppShowStoryBoxResult",
  "data": {
    "result": true
  }
}
```

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

```JSON
{
  "type": "VKWebAppShowStoryBoxLoadFinish",
  "data": {
    "story_owner_id": 212424,
    "story_id": 123322,
  }
}
```

`VKWebAppShowStoryBoxLoadFinish` будет работать только при наличии `request_id`.

В случае неудачи возвращается событие `VKWebAppShowStoryBoxFailed`.

```JSON
{ 
  "type": "VKWebAppShowStoryBoxFailed", 
  "data": {
     "error_type": "..."
     "error_data": {
        ...
     }
  }
}
```

## Объект `sticker_container`

* `sticker_type` (`string`, обязательный)
Тип стикера. Возможные значения:
`native`,
`renderable`. 
* `sticker` (`renderable_sticker` или `native_sticker`, обязательный) 
Объект cтикера. См. [`renderable_sticker`](#Объект%20renderable_sticker).

## Объект `service_info`

* `mask_id` (`string`)
Полный ID маски в формате ${owner_id}_${mask_id}. Например: 148038958_18424.
* `effect_id` (`string`)
Полный ID эффекта в формате ${owner_id}_${effect_id}.
* `user_id_birthday` (`int`)
ID пользователя, у которого день рождение.
* `open_text_editor` (`boolean`)
Открытие текстового редактора при переходе в камеру (с готовой историей, background != none), по умолчанию `false`.
* `situational_suggest_id` (`int`)
ID события от пользователя.


## Объект `native_sticker`

* `action_type` (`string`, обязательный)
Тип стикера. Возможные значения:
`text`, 
`hashtag`, 
`mention`, 
`time`, 
`place`, 
`question`, 
`emoji`, 
`sticker`, 
`market_item`. 
* `action` (`action_*`, обязательный)
Данные для стикера.
* `transform` (`transform`)
Описание объекта трансформации объекта.
* `can_delete` (`boolean`)
Может ли стикер быть удален с экрана, по умолчанию `true`.

## Объект `attachment`

* `text` (`string`, обязательный) 
Ключ для текста кнопки (см. `link_text` в [`stories.getVideoUploadServer`](method/stories.getVideoUploadServer))
* `type` (`string`, обязательный)
Тип объекта. Возможные значения: 
`url`, 
`audio`,
`video`, 
`photo`. 
* `url` (`string`) 
Ссылка на объект.
* `owner_id` (`int`)
Идентификатор владельца объекта. 
* `id` (`int`) 
Идентификатор объекта. 
* `access_key` (`string`) 
Ключ доступа для вложения. 

## Объект `renderable_sticker`

* `content_type` (`string`, обязательный)
Тип истории. Возможное значение: 
`image`,
`gif` (в формате webp),
`video` (не поддержан на клиентах).
* `url` (`string`)
Ссылка на контент. Обязательна, если не указано поле `blob`. 
* `blob` (`string`)
Base64-строка с BLOB. Обязательна, если не указано поле `url`. 
* `transform` (`transform`)
[Описание возможностей трансформации объекта.](#Объект%20transform) 
* `clickable_zones` (`clickable_zone []`)
[Массив областей контента, нажатие на которые может вызвать какое-либо действие.](#Объект%20clickable_zone) [См. объекты `action`](#Объекты%20action). 
* `can_delete` (`bool`)
Может ли стикер быть удалён с экрана, по умолчанию `true`. 

## Объект `clickable_zone`

* `action_type` (`string`, обязательный)
Описывает тип действия на нажатие. Возможные значения: 
`app`,
`hashtag`,
`mention`,
`link`,
`place`,
`question`,
`market_item`.
* `action` (`action`, обязательный)
[Необходимые данные для действия.](#Объекты%20action)
* `clickable_area` (`clickable_area_coordinate []`)
[Граница зоны стикера, на которую можно нажать.](#Объект%20clickable_area_coordinate) Точки должны располагаться по часовой стрелке, образуя замкнутый квадрат. 

## Объект `clickable_area_coordinate`

* `x` (`int`, обязательный)
Координата X (от 0 до ширины переданного контента). 
* `y` (`int`, обязательный)
Координата Y (от 0 до высоты переданного контента). 

## Объект `transform`

* `rotation` (`int`)
Градусы. От 0 до 359. Вращение против часовой стрелки. 
* `relation_width` (`float`) 
Желаемая ширина стикера относительно экрана — (`0`, `1`), высота будет рассчитана с учётом сохранения соотношения сторон контента. 
* `translation_x` (`float`) 
От -1 до 1. От ширины экрана. 
* `translation_y` (`float`)
 От -1 до 1. От высоты экрана. 
* `gravity` (`string`)
Расположение. По умолчанию: `center`. Возможные значения: 
 `left_top`,
 `left_center`, 
 `left_bottom`,
 `center_top`,
 `center`,
 `center_bottom`,
 `right_top, right_center`,
 `right_bottom`.

Для расчёта итоговой позиции:
x = начальная_позиция_x + `artboard_width` *  `translation_x`
y = начальная_позиция_y + `artboard_height` *  `translation_y`

## Объекты `action`

### Объект `action_link`

> В ближайшем будущем объект `action_link` перестанет поддерживаться. Вместо него рекомендуем использовать `action_app`.

 * `link` (`string`, обязательный)
Ссылка на объект. 
* `tooltip_text_key` (`string`)
Значение строки, которая будет отображаться на клиенте при нажатии на тултип. Возможные значения: 
`tooltip_open_post` — открыть запись, 
`tooltip_open_photo` — открыть фотографию, 
`tooltip_open_page` — открыть страницу, 
`tooltip_open_default` — перейти (по умолчанию). 

### Объект `action_app`

* `app_id` (`int`, обязательный)
Идентификатор приложения. 
* `app_context` (`string`)
Если приложение открывается из истории, то [в параметрах запуска](mini-apps/development/launch-params), в `vk_ref`, приходит значение `story{owner_id}_{story_id}_{access_key}_{sticker_id}_{context}`. `context` — Base64-строка, максимум — 500 символов.


### Объект `action_hashtag`

* `hashtag` (`string`, обязательный)
Текст хештега.
* `style` (`string`)
Стиль хештега. По умолчанию: `blue_gradient`. Возможные значения: 
`transparent`,
`blue_gradient`.


### Объект `action_mention`

* `mention` (`string`, обязательный)
Текст в формате меншена: для профилей людей "[id123|name]", для групп/сообществ/событий - "[club123|name]".
* `style` (`string`)
Стиль хештега. По умолчанию: `red_gradient`. Возможные значения: 
`transparent`,
`red_gradient`.

### Объект `action_place`

* `place_id` (`integer`, обязательный)
ID места.
* `title` (`string`, обязательный)
Название места.
* `category_id` (`integer`)
ID категории места.
* `style` (`string`)
Стиль. По умолчанию: `blue`. Возможные значения:
`transparent`,
`blue`,
`green`,
`white`.

### Объект `action_time`

* `style` (`string`)
Стиль стикера времени. По умолчанию: date. Возможные значения:
`black`,
`white`,
`green`,
`text`,
`date`.
* `timestamp_ms` (`long`)
Unix timestamp в миллисекундах.
* `date` (`string`)
Дата (альтернатива timestamp_ms) в формате yyyy:MM:dd HH:mm:ss (такой формат выбран для унификации даты из exif полей).
* `title` (`string`)
Верхний тайтл стикера, значим только для стиля `date`.

### Объект `action_question`

* `place_id` (`integer`, обязательный)
ID места.
* `title` (`string`, обязательный)
Название места.
* `category_id` (`integer`)
ID категории места.
* `style` (`string`)
Стиль. По умолчанию: `blue`. Возможные значения:
`transparent`,
`blue`,
`green`,
`white`.

### Объект `action_text`

* `text` (`string`, обязательный)
Текст, может содержать меншены/хештеги в форматах указанных с соответствующих объектах.
* `style` (`string`)
Стиль текста. Возможные значения: 
`classic`,
`cursive`,
`marker`,
`italics`,
`typewriter`,
`poster`,
`retro`.
* `background_style` (`string`)
Стиль фона/обводки. По умолчанию: `none`. Применимость стиля фона зависит от исходного стиля текста. Возможные значения:
`none`,
`alpha`,
`solid`,
`sticker`,
`neon`.
* `alignment` (`string`)
Выравнивание. Возможные значения: 
`center`,
`left`,
`right`.
* `selection_color` (`string`)
Цвет в формате: #ff0000. Если `background_style` задан `none`, то значение будет определять цвет текста, иначе будет означать цвет, применяемый к стилю.

#### Поддерживаемые стили фона относительно стиля текста

| Имя `style` | Поддерживаемые `background_style` |
|---|---|
| classic | none, solid, alpha, sticker |
| cursive | none, solid |
| marker | none, neon |
| italics | none, solid |
| typewriter | none, solid |
| poster | none, solid |
| retro | none, solid |

### Объект `action_emoji`

* `emoji` (`string`, обязательный)
Символ emoji.

### Объект `action_sticker`

* `sticker_id` (`int`, обязательный)
ID стикера.
* `pack_id` (`int`, обязательный)
ID набора стикера.

### Объект `action_market_item`

* `title` (`string`, обязательный)
Текст для тайтла товара.
* `product_id` (`int`)
ID продукта для товаров ВКонтакте.
* `owner_id` (`int`)
ID владельца для товаров ВКонтакте.
* `link` (`string`)
Ссылка на товар aliexpress.

## Объект `poll`

* `poll_id` (`int`, обязательный)
ID опроса.
* `owner_id` (`int`)
ID владельца.
* `is_board` (`Boolean`)
Из обсуждений ли опрос.

## Пример объекта `story_box`

```JSON
{
  "background_type": "image",
  "url": "https://sun9-65.userapi.com/c850136/v850136098/1b77eb/0YK6suXkY24.jpg",
  "stickers": [
    {
      "sticker_type": "renderable",
      "sticker": {
        "can_delete": 0,
        "content_type": "image",
        "url": "https://upload.wikimedia.org/wikipedia/commons/c/c7/Dialog.png",
        "clickable_zones": [
          {
            "action_type": "link",
            "action": {
              "link": "https://vk.com/wall-166562603_1192",
              "tooltip_text_key": "tooltip_open_post"
            },
            "clickable_area": [
              {
                "x": 17,
                "y": 110
              },
              {
                "x": 97,
                "y": 110
              },
              {
                "x": 97,
                "y": 132
              },
              {
                "x": 17,
                "y": 132
              }
            ]
          }
        ]
      }
    }
  ]
}
```

## Песочница

[VKWebAppShowStoryBox](https://vk.cc/bZfCnr)

VK Bridge | Редактор историй | VKWebAppShowStoryBox

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

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

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

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

Сообщество

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

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

![](260c42caf5f0ca0c2d6fe47d11337eacc4441a7af23b04903693e80f "-5045488956225453333")

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

Инструкции в этом разделе касаются только Direct Games и работы с ключом доступа. Если вы отправляете запрос к API с сервера и используете для этого сервисный ключ доступа (см.  [Мои приложения](https://vk.com/apps?act=manage) → **Редактировать** → **Настройки**), то вам не потребуется информация из этого раздела. 

## Режимы запроса прав

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

Чтобы увидеть окно запроса прав в разных режимах, откройте приложение https://vk.com/app7851579 (**По мере необходимости**) и https://vk.com/app7170524 (**При запуске игры**). 

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

## Выбор прав, выдаваемых игре при первом запуске

Если игра использует для веб-версии или Direct Games запрос прав **При запуске игры**, то возможно выбрать права, которые будут запрашиваться при первом входе пользователя в игру. При выборе режима **По мере необходимости** их выбор невозможен.

Чтобы выбрать, какие данные будет запрашивать игра при первом запуске:
1. Откройте [Мои приложения](https://vk.com/apps?act=manage) → **Редактировать** → **Настройки**.
2. В разделе **Запрос прав** в поле **Права доступа при запуске** выберите, какие именно данные будет использовать игра.

В разделе **Запрос прав** в поле **Первый запрос к API** вы можете указать запрос. Убедитесь, что на момент выполнения кода игра имеет необходимые доступы.
Например, метод [`users.get`](users.get) будет успешно выполнен в первом запросе к API, так как он не требует дополнительных прав. Но метод [`friends.getAppUsers`](friends.getAppUsers) будет успешно выполнен только после получения игрой права доступа `friends`.

## Запрос прав для игр, использующих VK Bridge

При запуске игры вы получаете ключ доступа ко всем ранее выданным правам.
Если необходимо получить новые доступы в дополнение к уже имеющимся, то:
1. Перед тем как использовать метод, который требует доступа к данным пользователя, стоит проверить, есть ли у игры нужное разрешение. Чтобы получить список прав, вызовите событие [`VKWebAppCheckAllowedScopes`](bridge/VKWebAppCheckAllowedScopes).
2. Если нужного права нет, покажите пользователю диалоговое окно с запросом доступа. Для этого вызовите событие [`VKWebAppGetAuthToken`](bridge/VKWebAppGetAuthToken).

Если пользователь нажал на кнопку:
1. **Разрешить**. В ответе на событие вернётся ключ доступа, который будет содержать в себе все разрешённые права (право доступа, которое пользователь дал в диалоговом окне, будет добавлено к остальным). Теперь с этим ключом доступа можно выполнять запросы к API. 
2. **Запретить**. Отправить запрос к API не получится. Мы рекомендуем запрашивать только те права, которые действительно необходимы. Также не стоит запрашивать их слишком часто — раздражённые пользователи закрывают не только окно с запросом прав доступа, но и саму игру.

## Пример кода для игр, использующих VK Bridge

### Пример функции RequestApiHelper

```JavaScript
const requestApiHelper = new RequestApiHelper(appId, accessToken, allowedScopes);

requestApiHelper.trySendRequest(apiMethodName, scope, paramsMethod).then(
      //Обработка данных пользователя, полученных в ответе на запрос к API.
    ).catch(
      //Обработка ошибки, полученной в ответе на запрос к API. 
    )
```

### Входные параметры функции RequestApiHelper

*  `appId` — идентификатор приложения, который передаётся при запуске игры. 
*  `accessToken` — ключ доступа пользователя, который передаётся при запуске игры. 
*  `allowedScopes` — права, выданные игре в момент запуска. В переменной `allowedScopes` данные хранятся в объекте `Map()`. Формат элементов: `Map.set(scope, true|false)`.
*  `apiMethodName` — имя метода API ВКонтакте.
*  `scope` — права доступа, которые необходимы методу API ВКонтакте.
*  `paramsMethod`  — параметры запроса к API ВКонтакте.

### Тело функции RequestApiHelper

```JavaScript
import bridge from "@vkontakte/vk-bridge";

const VK_BRIDGE_CHECK_SCOPE_METHOD = 'VKWebAppCheckAllowedScopes';

export default class RequestApiHelper {

   constructor(appId, accessToken, allowedScopes) {
     this.appId = appId;
     this.accessToken = accessToken;
     this.scopes = allowedScopes;
   }

   async trySendRequest(method, scope, params) {
     const sendApiRequest = (method, params) => {
       return bridge.send('VKWebAppCallAPIMethod', {"method": method, "request_id": "1234", "params": 
 params});
     }

     if (bridge.supports(VK_BRIDGE_CHECK_SCOPE_METHOD) && !this.scopes.has(scope)) {
       try {
         const allowedScopes = await bridge.send(VK_BRIDGE_CHECK_SCOPE_METHOD, {
           "app_id": this.appId,
           "scopes": scope
         });
         this.scopes.set(scope, allowedScopes.some((item) => {
           return item.scope === scope && item.allowed;
         }));
       } catch (e) {
         console.error(e);
       }
     }

     if (!this.scopes.get(scope)) {
       try {
         const authTokenData = await bridge.send('VKWebAppGetAuthToken', {
           "app_id": this.appId,
           "scope": scope
         });
 
         this.accessToken = authTokenData.access_token;
         this.scopes.set(scope, true);
       } catch (e) {
         console.error(e);
       }
 
       params['access_token'] = this.accessToken;
       return sendApiRequest(method, params);
     } else {
       return sendApiRequest(method, params);
     }
   }
 }
```

## Запрос прав для игр, использующих Client API

Если игра запущена на веб-платформе и использует Client API ([JavaScript SDK](sdk/javascript)):
*  Перед тем как использовать метод, который требует доступа к данным пользователя, стоит проверить, есть ли у игры нужное разрешение. Это можно сделать двумя способами:
   * Запустите игру. Список прав, которые пользователь выдал игре, закодирован в [битовой маске](reference/access-rights) прав, которая передается вместе с другими [параметрам запуска](api/app-run-parameters), в поле `api_settings`.
   * Отправьте запрос к API: [`account.getAppPermissions`](account.getAppPermissions). 
*  Запросите права. Для этого методу [`showSettingsBox`](sdk/javascript#showSettingsBox) передайте [битовую маску](reference/access-rights) запрашиваемых прав доступа.

## FAQ

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

Названия прав передаются в параметре `access_token_settings` при запуске игры. 

###  Когда лучше запрашивать доступ к данным?

Мы рекомендуем запрашивать доступ к данным непосредственно перед тем, как их использовать. Если запрашивать все разрешения на экране установки, который показывается при первом запуске, игра теряет больше аудитории, чем при запросах в процессе.

###  Как узнать, какие права нужны методу?

Эта информация есть в [справочнике](method), на странице метода.

![](42bb2d57df5c6af8e123202c862d890f2ad32ebd849f28ef064c1faf "8318987506215515805")

### Что такое первый запрос к API?

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

### Что делать, если событие VKWebAppCheckAllowedScopes не возвращает данные?

Обновите Android-приложение ВКонтакте до последней версии. Также, возможно, версия библиотеки VK Bridge, которую вы используете, не поддерживает событие. Чтобы это проверить, используйте метод:

```JavaScript
bridge.supports(‘VKWebAppCheckAllowedScopes’)
```

Чтобы обновить версию пакета, выполните команду:

```Shell
npm update @vkontakte/vk-bridge

```

Игры | Direct Games | Права доступа

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

# Вывод средств зарубежными разработчиками

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

## Требования

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

* Для вывода средств необходимо подключиться к нашему партнёру — компании [AppsCentrum](https://appscentrum.com/).

## Вход в личный кабинет AppsCentrum

1. Откройте страницу [appscentrum.com](https://appscentrum.com/) в браузере и нажмите на кнопку **Войти через ВКонтакте**.

2. Войдите с использованием аккаунта главного администратора вашей игры.

    Подтвердите доступ к данным вашего аккаунта ВКонтакте.

Личный кабинет AppsCentrum выглядит так:


![alt=Личный кабинет AppsCentrum;title=Личный кабинет AppsCentrum](ee7e5c38ca38132f414795f60314e7bcc4bf6d1b4fcd5b2382c83963 "7499577937995034609")

| Раздел | Описание |
| --- | --- |
| **Голоса** |  Информация о начислениях за [покупки и подписки](games/monetization/digital-goods). |
| **Трансляции** | Информация о показах и начислениях за трансляции. |
| **Медиареклама** | Информация о показах и начислениях за [рекламу](games/monetization/ad/overview). |
| **Мои реквизиты** | Информация об электронных кошельках и банковских реквизитах, которые будут использованы для вывода. |
| **Служба поддержки** | Форма для связи со службой поддержки AppsCentrum. |
| **Тарифы и лимиты** | Информация о комиссионных отчислениях и ограничениях, применяемых AppsCentrum. |
| **Реклама в играх** и&#x0d;&#x0a;**Реклама в мини-приложениях** | Ссылки на документацию ВКонтакте. |

## Подключение игры

Для получения выплат необходимо подключить игру к вашему аккаунту в AppsCentrum.

1. В личном кабинете перейдите в раздел **Медиареклама**.

2. Найдите вашу игру в списке и нажмите на кнопку **Подключить**.

> Подключение игры важно. Без этого AppsCentrum не сможет показывать начисления за показ рекламы и игровые покупки.

## Просмотр статистики

1. В личном кабинете AppsCentrum перейдите на вкладку **Медиареклама** и затем нажмите на кнопку **Статистика**.

2. Выберите желаемый период, приложение и критерии разбивки данных. Нажмите на кнопку **Показать статистику**.

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

## Вывод средств из AppsCentrum

Заработанные деньги поступят на ваш аккаунт AppsCentrum в течение 70 дней после окончания отчётного периода (месяца), во время которого они были начислены.

После того как деньги появятся на аккаунте, вы сможете получить выплату любым удобным способом: на банковскую карту, электронный кошелёк или банковский счёт. Следуйте этим шагам.

### Шаг 1. Укажите платёжные реквизиты

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

1. В личном кабинете AppsCentrum перейдите в раздел [Мои реквизиты](https://appscentrum.com/user).

    В этом разделе, в блоке **Кошельки**, вы можете видеть способы вывода средств, которые поддерживает AppsCentrum.

    
    ![alt=Пример страницы «Мои реквизиты»;title=Пример страницы «Мои реквизиты»](d02704bc725089234f533de6cbe8f0014a43886d2453bd035f0aaafe "-5851390484158581116")

1. Нажмите на ссылку **подключить** для нужного вам пункта в списке и на следующем экране укажите реквизиты для перевода средств.

Вы можете указать данные нескольких электронных кошельков или банковских карт и выводить средства на разные счета.

### Шаг 2. Запросите вывод средств

1. Дождитесь, когда на вашем счету будет достаточно средств.

    Существует минимальный порог вывода. Он указан на главной странице личного кабинета AppsCentrum, а также на странице [Тарифы и лимиты](https://appscentrum.com/limits). Если начисления не достигли минимального порога, то необходимо дождаться, когда они его превысят.

1. Когда на вашем счёте будет достаточно средств, на главной странице личного кабинета появится кнопка **Запросить выплату**. Нажмите на неё.

1. На следующем экране:

    * В выпадающем списке **Способ вывода** выберите банковскую карту или электронный кошелёк, данные которых вы указали на предыдущем шаге.

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

    * В поле **Сумма** укажите желаемую сумму для перевода. Она не может быть меньше порога вывода.

    * После заполнения всех полей в конце страницы появится кнопка **Запросить выплату**. Нажмите на неё.

### Как узнать, в какие страны возможен вывод

Если в разделе [Мои реквизиты](https://appscentrum.com/user) личного кабинета AppsCentrum выбрать **Иностранная карта**, то личный кабинет покажет экран, где нужно ввести данные вашей банковской карты. В поле **Страна банка-эмитента карты** вы можете видеть страны, в которые возможен перевод.


![alt=Список стран, в которые возможен перевод средств из AppsCentrum;title=Список стран, в которые возможен перевод средств из AppsCentrum](d3ba26a2b1722a3373aaf38c08b850f3b0194b0136f7a3182cc96f61 "-1583969661206517456")

## Поддержка AppsCentrum

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

* В личном кабинете, в разделе [Служба поддержки](https://appscentrum.com/support/new).

    — либо —

* По электронной почте: [info@appscentrum.com](mailto:info@appscentrum.com).

Игры | Монетизация | Вывод средств | Зарубежные авторы

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

**Игры ВКонтакте** &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)


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

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

## Создание приложений

### [Мини-приложения](mini-apps/overview)
Создавайте полезные сервисы на каждый день с помощью кросс-платформенных приложений на базе веб-технологий: HTML, JavaScript, CSS.

### [Игры](games/overview)
Увлекайте миллионы игроков своими идеями. Ни паролей, ни скачиваний — игры мгновенно запускаются прямо из интерфейса ВКонтакте. 

### [VK Bridge](bridge/overview)
Используйте API ВКонтакте и API операционной системы, установленной на устройстве пользователя, с помощью одной библиотеки.

### [Маруся](marusia/getting-started)
Создавайте голосовой интерфейс своего продукта с помощью Маруси.

## Бизнес-инструменты

### [VK Pay](pay/getting-started)
Принимайте оплату за товары и услуги — прямо в чатах, сообществах и мини-приложениях, с баланса VK Pay или привязанных к нему карт.

### [VK Donut](api/donut/getting-started)
Управляйте платной подпиской и разнообразными программами лояльности в сообществе.

### [Рекламный API](api/ads/getting-started)
Автоматически запускайте объявления и целые рекламные кампании, обновляйте аудитории ретаргетинга и получайте статистику.

## Интеграция контента

### [Виджеты для сайтов](widgets/overview)
Предоставьте посетителям сайта возможность авторизовываться через ВКонтакте, добавлять комментарии и плейлисты, общаться в сообщениях.

### [Публикации ВКонтакте](api/posts)
Предложите пользователям делиться ВКонтакте статьями или комментариями с вашего сайта или из приложения.

### [Маски](masks/overview)
Создавайте маски — развивайте персональный бренд, заявляйте о себе и привлекайте подписчиков на личную страницу или в сообщество.

### [Чат-боты](api/bots/getting-started)
Автоматизируйте рутинные и похожие задачи с помощью чат-бота ВКонтакте.

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

# VK Tunnel

**VK Tunnel** — это утилита, которая позволит отобразить в интернете веб-сервер, работающий на вашем локальном компьютере.

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

После запуска VK Tunnel вы можете отслеживать в терминале информацию о состоянии и показателях соединений, установленных через ваш туннель.

> NPM: [`vk-tunnel`](https://www.npmjs.com/package/@vkontakte/vk-tunnel).

## Использование

Вы можете настроить работу через VK Tunnel для любого сервера. Ниже мы приведём пример запуска при создании VK Mini Apps из шаблона. В иных случаях внимательно изучите используемые [параметры](#Переменные%20окружения%20и%20параметры) и их значения.

### Проект мини-приложения из шаблона

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

    ```sh
    npm install @vkontakte/vk-tunnel -g
    ```

1. [Создайте мини-приложение из шаблона](mini-apps/getting-started#Создание%20мини-приложения).
1. Перейдите к папке проекта мини-приложения:

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

1. В командной строке проекта запустите его:

    ```sh
    npm start
    ```

1. Откройте новую командную строку. Вызовите VK Tunnel:
    * Через переменные окружения:

        ```sh
        cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 PROXY_HTTP_PROTO=https PROXY_WS_PROTO=wss PROXY_HOST=0.0.0.0 PROXY_PORT=10888 vk-tunnel 
        ```

    * Через параметры:

        ```sh
        vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888
        ```

1. Или добавьте в файл `package.json` скрипт `tunnel`, после чего сохраните файл:

    ```sh
    "tunnel": "vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888 app_id=8174360 endpoints=[web]"
    ```

    И вызовите VK Tunnel:

    ```sh
    npm run tunnel
    ```

1. В командной строке будет предложено перейти по адресу в формате [`https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa`](https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa) для авторизации. Откройте ссылку в браузере, вернитесь в терминал и нажмите **Enter**.
    
    После успешной авторизации в командной строке появится ссылка вида [`https://user12345-jv7zlzzz.wormhole.vk-apps.com`](https://user12345-jv7zlzzz.wormhole.vk-apps.com).
    
    Укажите её в поле **URL** в [Настройках](mini-apps/management/settings) для дальнейшей работы. Если приложение ещё не создано, воспользуйтесь разделом [Регистрация мини-приложения ВКонтакте](mini-apps/getting-started#Регистрация%20мини-приложения%20ВКонтакте).

### Проект мини-приложения на Node.js

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

    ```sh
    npm install @vkontakte/vk-tunnel -g
    ```

1. Перейдите к папке проекта мини-приложения:

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

1. Установите библиотеку `react-scripts`:

    ```sh
    npm i react-scripts
    ```

1. Создайте папку `public` и переместите в неё файл `index.html`.
1. Создайте папку `src` и переместите в неё оставшиеся статические файлы.

    > **Обратите внимание!** Каталог `src` должен иметь файл `index.js`.
    Структура каталога проекта мини-приложения:
    ```
    .
    └── mini-app
        ├── public
            └── index.html
        ├── src
            ├── cactus.png
            ├── dinosaur.png
            ├── index.js
            └── style.css
        ├── package-lock.json
        ├── package.json
        └── README.md
    ```


1. В командной строке проекта запустите его:

    ```sh
    env PORT=10888 HTTPS=true react-scripts start
    ```

1. Или добавьте в файл `package.json` скрипт `start`, после чего сохраните файл:

    ```sh
    "start": "cross-env PORT=10888 HTTPS=true react-scripts start",
    ```

    И запустите проект:

    ```sh
    npm start
    ```

1. Откройте новую командную строку. Вызовите VK Tunnel:
    * Через переменные окружения:

        ```sh
        env NODE_TLS_REJECT_UNAUTHORIZED=0 PROXY_HTTP_PROTO=https PROXY_WS_PROTO=wss PROXY_HOST=0.0.0.0 PROXY_PORT=10888 vk-tunnel 
        ```

    * Через параметры:

        ```sh
        vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888
        ```

1. Или добавьте в файл `package.json` скрипт `tunnel`, после чего сохраните файл:

    ```sh
    "tunnel": "vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888 app_id=8174360 endpoints=[web]"
    ```

    И вызовите VK Tunnel:

    ```sh
    npm run tunnel
    ```

1. В командной строке будет предложено перейти по адресу в формате [`https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa`](https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa) для авторизации. Откройте ссылку в браузере, вернитесь в терминал и нажмите **Enter**.
    
    После успешной авторизации в командной строке появится ссылка вида [`https://user12345-jv7zlzzz.wormhole.vk-apps.com`](https://user12345-jv7zlzzz.wormhole.vk-apps.com).
    
    Укажите её в поле **URL** в [Настройках](mini-apps/management/settings) для дальнейшей работы. Если приложение ещё не создано, воспользуйтесь разделом [Регистрация мини-приложения ВКонтакте](mini-apps/getting-started#Регистрация%20мини-приложения%20ВКонтакте).

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

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

### `NODE_TLS_REJECT_UNAUTHORIZED`

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

* `0` — пропустить проверку;
* `1` — проверить сертификат.

Аналогом переменной окружения является параметр `--insecure`. Возможные значения:

* `0` — проверить сертификат;
* `1` — пропустить проверку.

### `PROXY_HTTP_PROTO`

Схема для протокола HTTP. Возможные значения:

* `http` — нешифрованное соединение (значение по умолчанию);
* `https` — шифрованное соединение.

Аналогом переменной окружения является параметр `--http-protocol`. Возможные значения совпадают.

### `PROXY_WS_PROTO`

Схема для WebSocket-протокола. Возможные значения:

* `ws` — нешифрованное соединение (значение по умолчанию);
* `wss` — шифрованное соединение.

Аналогом переменной окружения является параметр `--ws-protocol`. Возможные значения совпадают.

### `PROXY_HOST`

Хост, на котором запущен проект. Значение по умолчанию: `localhost`.

Аналогом переменной окружения является параметр `--host`.

### `PROXY_PORT`

Порт, на котором запущен ваш проект. Значение по умолчанию: `10888`.

Аналогом переменной окружения является параметр `--port`.

### `PROXY_TIMEOUT`

Тайм-аут запросов к вашему приложению. Значение по умолчанию: `5000` (5 секунд). Увеличьте тайм-аут, если мини-приложение получает ответ с ошибкой `Bad gateway` и вы видите в логах сообщение `Error: timeout of 5000ms exceeded`.

Аналогом переменной окружения является параметр `--timeout`.

## Файл `vk-tunnel-config.json`

Для удобства настройки утилиты в проекте мини-приложения создайте файл `vk-tunnel-config.json`, в котором укажите идентификатор мини-приложения и платформы.

Пример файла:

```JSON
{
  "app_id": "8174360",
  "endpoints": ["mobile", "mvk", "web"]
}
```

### `app_id`

Идентификатор мини-приложения.

### `endpoints`

Массив платформ, для которых нужно автоматически заменить адрес в [Настройках](mini-apps/management/settings). Возможные значения:

* `mobile` — мобильное приложение;
* `mvk` — мобильная версия сайта;
* `web` — десктопная версия сайта.

## Ошибки

### Получаю ошибку `Error: Пользователь не является создателем приложения`. Что делать?

Если при запуске утилиты вы видите ошибку `ERROR: Пользователь не является создателем приложения`, обновите токен утилиты:

```sh
rm ~/.config/configstore/@vkontakte/vk-tunnel.json
```

> **Обратите внимание!** Если ошибка сохраняется, убедитесь, что вас добавили в [администраторы](mini-apps/management/admin) мини-приложения.

### Получаю ошибку `Error: connect ECONNREFUSED 127.0.0.1:10888`. Что делать?

Убедитесь, что вы запустили проект:

```sh
npm start
```

Библиотеки | Утилита VK Tunnel

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

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

**Скилл** — это приложение, которое работает сразу на всех платформах, где доступна Маруся. Создать его можно в этом разделе: [https://vk.com/editapp?act=create](https://vk.com/editapp?act=create). Главное, чтобы скилл соблюдал [протокол взаимодействия](marusia/api) с Марусей.

## Платформы

Сейчас Маруся работает на следующих платформах:
*  мобильное приложение ВКонтакте,
*  мобильное приложение Маруси на [iOS](https://apps.apple.com/ru/app/%D0%BC%D0%B0%D1%80%D1%83%D1%81%D1%8F-%D0%B3%D0%BE%D0%BB%D0%BE%D1%81%D0%BE%D0%B2%D0%BE%D0%B9-%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D0%BD%D0%B8%D0%BA/id1467719381) и [Android](https://play.google.com/store/apps/details?id=ru.mail.search.electroscope&hl=ru),
*  умная колонка [«Капсула»](https://capsula.mail.ru),
*  умная колонка «Капсула мини»,
*  умная колонка Prestigio Smartvoice,
*  приложение Почта Mail.ru для [iOS](https://apps.apple.com/ru/app/%D0%BF%D0%BE%D1%87%D1%82%D0%B0-mail-ru/id511310430) и [Android](https://play.google.com/store/apps/details?id=ru.mail.mailapp&hl=ru&gl=US). 

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

Список всех скиллов Маруси можно изучить в [каталоге](https://marusia.mail.ru). 

## Создание скиллов

Создать скилл можно двумя способами:
1. Использовать конструктор [Aimylogic](https://aimylogic.com/ru), который позволяет собрать необходимый сценарий в визуальном редакторе, а затем получить готовый webhook. Его, в свою очередь, уже можно зарегистрировать в качестве скилла Маруси. 
2. Написать код самостоятельно. Для этого изучите документацию. В ней подробно описан [протокол](marusia/api), по которому Маруся взаимодействует с внешними навыками, а также порядок работы с [TTS](marusia/tts), со [звуками](marusia/sound) и [изображениями](marusia/cards). Код приложения может быть написан на любом удобном вам языке и размещён на любом сервере. Главное, чтобы webhook был доступен из интернета и воспроизводил протокол Маруси из документации. 

После того как вы создадите скилл, необходимо его зарегистрировать и отправить на модерацию. Для этого выполните следующие действия:
1. [Создайте приложение](https://vk.com/editapp?act=create) в разделе для разработчиков. 
2. Выберите **Скилл Маруси** в типах приложения. 
3. Добавьте название, которое будет совпадать с командой для активации скилла. 
4. Введите в поле **Webhook URL** адрес сервера, на котором будет размещён навык, например [`https://example.com/test-webhook`](https://example.com/test-webhook). 
5. Нажмите на кнопку **Создать скилл**. 

![](cec687cc653698c24cee3af05ceaf922b93ba80f4dade06cf9b6af77 "4940476498664586883")

Вы попадёте в интерфейс администрирования скилла. 
> Все изменения полей скилла становятся доступны на всех платформах, где работает Маруся, примерно через 1–2 минуты.

## Некоторые ограничения и советы

> В день можно добавлять не более 3 скиллов, за 5 дней — не более 10. 

Фразы для вызова должны быть специфичными и уникальными, чтобы мы могли использовать их для внешних скиллов. Например, фразу «Расскажи анекдот» мы добавить не сможем, так как она уже используется во внутренних скиллах Маруси. А вот фразу «Давай сделаем код-ревью» — пока свободна и подойдёт для внешнего скилла. 

> Обратите внимание: имя «Маруся» будет первым словом фразы и триггером для вызова скилла.
>
> Длина фразы активации не может превышать 64 символа.

Маруся | Быстрый старт

# Первые шаги

Чтобы создать свою первую маску:

* [Подготовьте инструменты](#Шаг%201.%20Подготовьте%20инструменты)
* [Скачайте проект маски](#Шаг%202.%20Скачайте%20проект%20маски)
* [Добавьте в проект изображение](#Шаг%203.%20Добавьте%20в%20проект%20изображение)
* [Посмотрите на результат](#Шаг%204.%20Посмотрите%20на%20результат)

## Шаг 1. Подготовьте инструменты

1. Скачайте и установите приложение [test.mask](masks/tools#test.mask) для [Windows](https://mask.vk.me/app/test.mask3_windows.zip) или для [macOS](https://mask.vk.me/app/test.mask3_macos.zip). Приложение понадобится, чтобы увидеть готовую маску через веб-камеру компьютера. Если вы планируете просматривать маску только на мобильном устройстве, пропустите этот шаг.
1. Установите редактор кода с подсветкой синтаксиса, чтобы просматривать и редактировать конфигурационный файл. Например, удобно пользоваться [Visual Studio Code](https://code.visualstudio.com).

## Шаг 2. Скачайте проект маски

Мы подготовили [шаблон проекта](https://mask.vk.me/template/minimal_project.zip) маски с минимальным набором файлов.

1. Скачайте проект маски и откройте его, например в Visual Studio Code.

    ![alt=Проект маски в Visual Studio Code;title=Перенесите папку с проектом в окно Visual Studio Code;](5df9048cf244ceb2c1eef424c5aab0e00c8a54c79469317c32aefebf "-6381053188261687382")

1. В папке проекта вы увидите следующие файлы:

    * `Icon.png` — миниатюрное изображение, которое идентифицирует маску в каталоге камеры (иконка маски);
    * `mask.json` — конфигурационный файл, в котором указывается путь к иконке маски и параметры используемых в маске эффектов.

    Конфигурационный файл `mask.json` содержит строки в формате JSON и выглядит так:

    ```JSON
    {
        "preview": "Icon.png"
    }
    ```
    В поле `preview` указывается путь к иконке маски. В данном случае это просто имя файла с расширением `.png`, так как иконка лежит в той же папке, что и конфигурационный файл. 

1. Назовите папку с маской так, как будет называться ваш проект (например, `First steps`).

## Шаг 3. Добавьте в проект изображение

1. Подготовьте текстуру — любое изображение в формате PNG. Можно использовать файл [`Glasses.png`](https://mask.vk.me/sample/first_steps.zip) из готового проекта.
1. Создайте в корневой папке проекта маски папку `Textures` и поместите в неё файл с текстурой. В примере ниже файл называется `Glasses.png`.
1. В конфигурационный файл `mask.json` добавьте следующие поля.

    ```JSON

    {
        "preview": "Icon.png",
        
        "effects": [ 
            {
                "name": "patch",
                "anchor": "nose",
                "texture": "Textures/Glasses.png",
                "size": [100, 100]
            }
        ]
    }
    ```
Вы добавили поле `effects`, в котором перечисляются эффекты маски. В данном случае это перечисление (массив) содержит один эффект, который описывается следующим образом:

* `name` — название эффекта,
* `anchor` — точка привязки эффекта,
* `texture` — путь к файлу текстуры,
* `size` — размер эффекта по оси X и Y.

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

![alt=Проект маски в Visual Studio Code;title=Проект маски в Visual Studio Code;](25fac1447be816b615f3710cffeb7c9ac355517c18fa3acef2b4505d "4275018242743549721")

## Шаг 4. Посмотрите на результат

Для просмотра маски потребуется мобильное устройство или компьютер с камерой.

#### Windows

1. Запустите приложение test.mask, которое вы скачали на первом шаге.
1. Нажмите на кнопку **Open mask**.
1. Откройте папку с маской в проводнике, выберите файл `mask.json` и нажмите **Открыть**.

#### macOS

1. Запустите приложение test.mask, которое вы скачали на первом шаге.
1. В меню выберите **File** → **Open Mask...** .
1. Выберите каталог с проектом маски и нажмите **Open**.

#### Мобильное приложение

1. Откройте проект вашей маски и упакуйте все файлы и папки в ZIP-архив. Обратите внимание, что необходимо архивировать не только непосредственно папку проекта, но и все файлы и папки внутри неё.
1. Откройте сообщество [Маски ВКонтакте](https://vk.com/msx) и нажмите **Написать сообщение**.
1. Прикрепите ZIP-архив и отправьте сообщение. В ответ бот пришлёт вам ссылку.
1. Откройте ссылку на мобильном устройстве.

Если вы всё сделали правильно, то увидите маску на своём лице.

![alt=Маска на лице;title=Маска на лице](7649e608ceb6a6a20ef8e7290bf092e49b40d31b77584d60e8e72d22 "-1709775590157895052")

## FAQ

#### У меня не получилось :(

Если что-то не получилось, [скачайте готовый проект](https://mask.vk.me/sample/first_steps.zip) или [задайте вопрос в чате](https://vk.me/join/0vkXWqF_3HtlnKuKPd4Z3AGqfpks1Y189Pc=) сообщества.

#### Хочу открыть маску в мобильном приложении, но получаю сообщение о проблемах с архивом, что делать?

Посмотрите в разделе [Просмотр маски](masks/view#FAQ), как решать проблемы с архивом. Чаще всего пользователи совершают ошибку на последнем этапе — архивируют папку проекта, а не файлы и папки внутри неё.

#### Отправила архив в сообщество, но получила только сообщение о том, что маска загружается, в чём причина?

Если вы добавили в проект собственный файл текстуры, возможно, причина в неправильном формате. Проверьте, что формат изображения — PNG. Подробное описание проблемы есть в разделе [Просмотр маски](masks/view#FAQ).

## Что дальше

* [Узнайте больше о просмотре и тестировании масок](masks/view)
* [Воспользуйтесь библиотекой примеров масок](masks/examples)
* [Узнайте, какие существуют эффекты и как с ними работать](masks/effects/overview)
* [Разберитесь, как опубликовать готовую маску в каталоге](masks/publication/overview)

Маски | Первые шаги

# Платформа

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

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

![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).

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

# Плагины

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

Объявляются плагины в [файле конфигурации mask.json](masks/configuration), в поле&nbsp;`"plugins" : [...]`.

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

## Список плагинов

| Плагин | Описание |
| --- | --- |
| [`customhint`](masks/plugins/customhint) | Добавляет в маску всплывающее сообщение. |
| [`fixeddetection`](masks/plugins/fixeddetection) | Улучшает наложение маски. |
| [`maskswitching`](masks/plugins/maskswitching) | Добавляет механизм переключения маски. |
| [`mirror`](masks/plugins/mirror) | Отзеркаливает маску при использовании фронтальной камеры. |
| [`parallax`](masks/plugins/parallax) | Создаёт параллакс-эффект. |
| [`particles`](masks/plugins/particles) | Добавляет систему частиц. |
| [`perspective`](masks/plugins/perspective) | Добавляет в маску перспективу для 3D-моделей. |
| [`randomtest`](masks/plugins/randomtest) | Добавляет механизм рандомайзера. |
| [`spinner3d`](masks/plugins/spinner3d) | Вращает 3D-модели вокруг головы. |

## Объявление нескольких плагинов

Как и эффекты, плагины перечисляются через запятую. Существует и возможность объявлять одноимённые плагины с разной конфигурацией.

```JSON
{
  "preview": "Icon.png",
  "effects": [
    {
      "name": "model3d",
      "tag": "spinner",
      "anchor": "free",
      "model": "Models/Pizza.mdl",
      "material": {
        "technique": "Techniques/DiffUnlit.xml",
        "textures": {
          "diffuse": "Textures/Pizza.png"
        }
      },
      "position": [0, 0, 0],
      "rotation": [180, -90, 0],
      "scale": [13, 14, 13]
    },
    {
      "name": "model3d",
      "tag": "cacke",
      "anchor": "free",
      "model": "Models/Cacke.mdl",
      "material": {
        "technique": "Techniques/DiffUnlit.xml",
        "textures": {
          "diffuse": "Textures/Cacke.png"
        }
      },
      "position": [0, 0, 0],
      "rotation": [180, -90, 0],
      "scale": [13, 14, 13]
    }
  ],
  "plugins": [
    {
      "name": "perspective"
    },
    {
      "name": "fixeddetection"
    },
    {
      "name": "spinner3d",
      "tag": "pizza",
      "radius": 120,
      "number": 8,
      "offset_y": 12,
      "speed": 25
    },
    {
      "name": "spinner3d",
      "tag": "cacke",
      "radius": 120,
      "number": 5,
      "offset_y": 8,
      "speed": -15
    }
  ]
}
```

## Разработка плагинов

Если вы знакомы с программированием и хотите создать новую версию существующего плагина или собственный плагин, ознакомьтесь с разделом  [Создание плагинов](masks/development/plugin-creation).

Маски | Создание | Плагины

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

Позволяет сменить пароль пользователя после успешного восстановления доступа к аккаунту через СМС, используя метод [`auth.restore`](method/auth.restore).

Идентификатор сессии, полученный при восстановлении доступа используя метод [`auth.restore`](method/auth.restore). (В случае если пароль меняется сразу после восстановления доступа).

restore_sid

Хэш, полученный при успешной OAuth авторизации по коду полученному по СМС (В случае если пароль меняется сразу после восстановления доступа).

change_password_hash

Текущий пароль пользователя.

old_password

Новый пароль, который будет установлен в качестве текущего.

new_password

Возвращает объект с единственным полем `token`, содержащим новый токен.

account.changePassword

Возвращает список пользователей, находящихся в черном списке.

Смещение, необходимое для выборки определенного подмножества черного списка.

offset

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

count

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

account.getBanned

Сохраняет результат поиска похожей аудитории.

Permission denied. You have requested too many actions this day. Try later.

Lookalike request audience save already in progress

Max count of lookalike request audience saves per day reached

Идентификатор рекламного кабинета.

account_id

**Только для рекламных агентств**. 

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

client_id

Идентификатор запроса на поиск похожей аудитории. Получить список всех запросов на поиск похожей аудитории для данного кабинета можно с помощью [`ads.getLookalikeRequests`](method/ads.getLookalikeRequests).

request_id

Уровень конкретного размера похожей аудитории для сохранения. Получить список всех доступных размеров аудиторий можно с помощью [`ads.getLookalikeRequests`](method/ads.getLookalikeRequests).

level

Возвращает объект с полями:

* `retargeting_group_id` – идентификатор группы ретаргетинга, в которую будет сохранена запрошенная похожая аудитория.
* `audience_count` – размер запрошенной похожей аудитории.

ads.saveLookalikeRequestResult

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

**Обязательный параметр**. Идентификаторы пользователей, которые входят в группу тестировщиков, перечисленные через запятую (например, `"11, 13"`).

user_ids

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

group_id

Метод возвращает `1`, если пользователи добавлены в группу тестировщиков, и `0` в случае ошибки.

```JSON
{
  "response":1
}
```

Возможные ошибки:

* `Not found` — группа тестировщиков не существует;
* `Out of limits` — количество пользователей в группе превышает 1000.

apps.addUsersToTestingGroup

Использовать подарок, полученный пользователем в промо-акции.

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

apps.promoHasActiveGift

promo_id

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

user_id

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

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

Где в поле response хранится результат выполнения операции:
`1` —  успех операции.
`0` — неудача.

Также в ходе выполнения метода могут вернуться стандартные ошибки API.

apps.promoUseGift

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

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

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

code

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

Удаляет статью из закладок.

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

owner_id

article_id

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

fave.removeArticle

Одобряет или создаёт заявку на добавление в друзья.

Cannot add this user to friends as they have put you on their blacklist

Cannot add this user to friends as you put him on blacklist

Cannot add this user to friends as user not found

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

Текст сопроводительного сообщения для заявки на добавление в друзья. Максимальная длина сообщения — 500 символов.

text

`1`, если необходимо отклонить входящую заявку (оставить пользователя в подписчиках).

follow

После успешного выполнения возвращает одно из следующих значений:
* `1` — заявка на добавление данного пользователя в друзья отправлена;
* `2` — заявка на добавление в друзья от данного пользователя одобрена;
* `4` — повторная отправка заявки.

friends.add

Возвращает список меток друзей пользователя.

Создает новый список друзей у текущего пользователя.

friends.addList

Редактирует существующий список друзей текущего пользователя.

friends.editList

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

friends.deleteList

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

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

return_system

После успешного выполнения возвращает список объектов, каждый из которых содержит следующие поля:
* `name` — название списка друзей;
* `id` — идентификатор списка друзей.

friends.getLists

Возвращает список идентификаторов друзей пользователя, находящихся на сайте.

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

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

list_id

`1` — будет возвращено дополнительное поле `online_mobile`. 
По умолчанию — `0`.

online_mobile

Порядок, в котором нужно вернуть список друзей, находящихся на сайте. Допустимые значения: `random` — возвращает друзей в случайном порядке, `hints` — сортировать по рейтингу, аналогично тому, как друзья сортируются в разделе **Мои друзья** (данный параметр доступен только для [Desktop](guide)-приложений).

По умолчанию список сортируется в порядке возрастания идентификаторов пользователей.

order

Количество друзей онлайн, которое нужно вернуть. (По умолчанию — **все друзья онлайн**)

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

После успешного выполнения возвращает список идентификаторов (`id`) друзей, находящихся сейчас на сайте, у пользователя с идентификатором `uid` и входящих в список с идентификатором `lid`.
При использовании параметра `online_mobile` = `1` также возвращается поле `online_mobile`, содержащее список идентификатор друзей, находящихся на сайте с мобильного устройства.

friends.getOnline

Удаляет сервер для [Callback API](api/callback/getting-started) из сообщества.

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

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

server_id

groups.deleteCallbackServer

Возвращает список сообществ указанного пользователя.

Access to the groups list is denied due to the user's privacy settings

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

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

Если был задан параметр `extended`=`1`, возвращает объект, содержащий число результатов в поле `count` (`integer`) и массив [объектов](reference/objects/group), описывающих сообщества, в поле `items`.

5.118