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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

### Redirect_uri

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

# Рекламный 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 ВКонтакте, перед началом работы мы рекомендуем вам прочитать [это руководство](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) используемого языка.

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

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

# VK Donut API

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

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

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

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

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

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

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

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

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

## Методы

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

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

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

### Пример

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

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

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

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

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

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

## События

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

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

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

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

## FAQ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```
51eff86578a3bbbcb5c7043a122a69fd04dca057ac821dd7afd7c2d8e35b60172d45a26599c08034cc40a
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Что дальше

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Доставка

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

![](d84302030ec7bf82e0824216cd40405b0f35762c05c8fbd7f123eeb8 "-536902625946196038")

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

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

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

![](d2b5b34c5da9100bff19aec8d49be18a7d99ded64798fe42c557a02e "8014173844027144298")

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

![](7a6b0cd237030915c8546f4023ef9e4f75796655401306a5c23a113c "7767136780412586436")

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

![](39a7f82a6cf220740f1e7d3b86b4a387e7bc86579d064c6207bc7827 "-4074010642457854577")

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

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

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

![](75cafdffa3a261a3af5ebdb6788b3c3a0e9c6f0168e611b45a0802c2 "-4967459588447635267")

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

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

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

![](7dd640fdd996ee64368dd36520497c5f916cda6c226e47d2a1e03d9d "-6931970821843698708")

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

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

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

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

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

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

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

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

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

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

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

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

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

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

![](a5b0a5d31fbae44ec0aedc30e75625128639282b0279dc8529c5ffd8 "1565333712537667774")

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

![](55f4339a699abb4df078b1f3293c5fc25900ecae0c844aac4b617bd0 "5578399229701508714")

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

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

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

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

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

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

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

###  CRM системы

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

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

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

###  Прочее

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

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

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

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

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

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

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

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

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

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

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

# VKWebAppAddToProfile

`VKWebAppAddToProfile` открывает окно, в котором пользователь может добавить в свой профиль [кнопку вызова мини-приложения](mini-apps/profile-button).

## Пример

```JavaScript
bridge.send('VKWebAppAddToProfile', {
  ttl: 1666076431
  })
  .then((data) => { 
    if (data.visibility) {
      // Кнопка добавлена в профиль
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `ttl` &#x0d;&#x0a;*необязательное* | `integer` | Дата и время отключения кнопки в секундах ([Unix Timestamp](https://www.unixtimestamp.com/)).&#x0d;&#x0a;&#x0d;&#x0a; Если в качестве параметра передать `0`, кнопка будет находиться в профиле пользователя, пока он сам её не отключит. |

## Результат

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `visibility` | `string` | Информация о том, кому видна кнопка. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `all` — кнопка видна всем пользователям.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `friends` — кнопка видна только друзьям пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `best_friends` — кнопка видна только близким друзьям пользователя. |

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

### События

#### `VKWebAppAddToProfileResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppAddToProfileResult",
    data: {
      visibility: "best_friends"
    }
  }
}
```

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

#### `VKWebAppAddToProfileFailed`

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

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

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

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


VKWebAppAddToProfile

# VKWebAppConversionHit

`VKWebAppConversionHit` позволяет отслеживать [конверсионные действия](https://vk.com/faq16578) пользователей в мини-приложении.

## Пример

```JavaScript
bridge.send("VKWebAppConversionHit", {
    "pixel_code": "VK-Boo-427253-dUuM", 
    "conversion_event": "purchase",
    "conversion_value": 3500
  })

```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

`pixel_code` 
`string`, `required` 
Код пикселя. Например: `VK-Boo-427253-dUuM`. Код пикселя можно найти в [рекламном кабинете](https://vk.com/ads?act=retargeting&show=pixels). 

`conversion_event`
`string`, `required`
Конверсионное действие, которое необходимо отслеживать. Например, чтобы отслеживать добавление товара в корзину, значение `conversion_event` должно быть равно `add_to_cart`, если покупку товара, значение `conversion_event` должно быть равно `purchase`. Список всех возможных значений описан в [документации рекламного кабинета](https://vk.com/faq16578). 

`conversion_value` 
`float`
 Стоимость (ценность) конверсионного события (если есть). Например, если пользователь купил товар за 3500 рублей, значение `conversion_event` должно быть равно `purchase`, а значение `conversion_value` должно быть равно `3500`. 

> Обратите внимание. При создании пикселя в рекламном кабинете можно указывать только идентификатор мини-приложения (поле **Разрешённый Mini App id**). Указывать домен или поддомен не обязательно.

## Результат

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

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

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

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

VK Bridge | Отслеживание пользователей | VKWebAppConversionHit

# VKWebAppCreateHash

`VKWebAppCreateHash` генерирует хеш. Хеш помогает защититься от подмены данных, которые ВКонтакте отправляет мини-приложению или игре, например при показах рекламы.

Чтобы убедиться, что данные приходят именно от сервера ВКонтакте, достаточно [вычислить хеш](#Вычисление%20хеша) и сравнить с тем, что мини-приложение или игра получило в ответе.

## Пример

```JavaScript
bridge.send('VKWebAppCreateHash')
  .then((data) => { 
    if (data.sign) {
      // Хеш сгенерирован
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `request_id` &#x0d;&#x0a;*необязательное* | `string` | Идентификатор запроса. Используется для проверки соответствия запроса и ответа. |

## Результат

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `sign` | `string` | Хеш, который генерирует сервер ВКонтакте, используя защищённый ключ и текущее значение времени. Такой же принцип используется для подписи [параметров запуска](mini-apps/development/launch-params). |
| `ts` | `integer` |  Дата и время в секундах, когда хеш был сгенерирован ([Unix Timestamp](https://www.unixtimestamp.com/)). |

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

### События

#### VKWebAppCreateHashResult

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

```JavaScript
{
  detail: {
    type: "VKWebAppCreateHashResult",
    data: {
      sign: "m7TwcoveOwy4BE180UCTwyTkPApprYP81RjrOEuQcos",
      ts: 1664541985
    }
  }
}
```

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

#### VKWebAppCreateHashFailed

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

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

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

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

## Вычисление хеша

Чтобы вычислить хеш:

1. Добавьте в ответ идентификатор пользователя `user_id` и идентификатор мини-приложения или игры `app_id`.
1. Отсортируйте параметры ответа по ключу (в алфавитном порядке) и объедините пары «ключ=значение» в строку с амперсандом в качестве разделителя.
1. Сериализуйте строку с помощью алгоритма хеширования [HMAC-SHA256](https://ru.wikipedia.org/wiki/HMAC). В качестве ключа используйте защищённый ключ из настроек [мини-приложения](mini-apps/management/settings) или игры. Выбранная реализация HMAC должна использовать хеш-функцию SHA-256.
1. Преобразуйте в строку двоичные данные, полученные на предыдущем шаге. Используйте алгоритм [Base64](https://ru.wikipedia.org/wiki/Base64).

### Пример

```PHP
$sign_param = 'fSibt9N1v3DYflFKFl2qyRk-g3szAKiGDL0p6fYGFSI';

$hash_params = [
  'ts' => 1630076629,
  'request_id' => '123',
];

// Добавляем идентификатор пользователя и мини-приложения или игры к ответу на событие.
$hash_params['user_id'] = 123;
$hash_params['app_id'] = 123;

// Сортируем массив по ключам.
ksort($hash_params);

// Формируем строку вида param_name1=value&param_name2=value.
$sign_params_query = http_build_query($hash_params);

// Получаем хеш-код от строки, используя защищёный ключ приложения (метод HMAC).
$sign = rtrim(strtr(base64_encode(hash_hmac('sha256', $sign_params_query, $client_secret, true)), '+/', '-_'), '=');

// Сравниваем полученную строку со значением из VKWebAppCreateHash.
$status = $sign === $sign_param;

echo ($status ? 'ok' : 'fail')."\n";
```

## Песочница

[VKWebAppCreateHash](https://vk.cc/c6kfQV)


VK Bridge | Общие события | VKWebAppCreateHash

# VKWebAppDeviceMotionStop

`VKWebAppDeviceMotionStop` останавливает [отслеживание данных о вращении устройства в пространстве](bridge/VKWebAppDeviceMotionStart).

## Пример

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

```

## Платформы

Android, iOS

## Параметры

—

## Результат

Если генерируется событие `VKWebAppDeviceMotionStopResult`, приложение больше не будет получать данные.

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

### Поля ответа

* `result` (`boolean`)
Всегда `true`. 

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

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

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

# VKWebAppGetPhoneNumber

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

> **Совет.** Если вам требуется запросить не только номер телефона, но и адрес электронной почты, используйте вызов [карточки контактов](bridge/VKWebAppGetPersonalCard).

## Пример

```JavaScript
bridge.send('VKWebAppGetPhoneNumber')
  .then((data) => { 
    if (data.phone_number) {
      // Номер телефона получен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Web

## Параметры

—

## Результат

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

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

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

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

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

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.
* `User denied`, если пользователь запретил доступ к номеру телефона.

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `phone_number` | `string` | Номер телефона пользователя. |
| `sign` | `string` | Подпись полученных данных. |

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

### События

#### `VKWebAppGetPhoneNumberResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppGetPhoneNumberResult",
    data: {
      sign: "YdUTMy8uAmFXUqzMsAUjYFTZ1cUfhRJBpTjmqgZBCtg",
      phone_number: "79111234567" 
    }
  }
}
```

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

#### `VKWebAppGetPhoneNumberFailed`

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

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

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

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

## Вычисление подписи

Для подписи последовательно объединяются значения:

* Идентификатор мини-приложения `app_id`.
* [Защищённый ключ](mini-apps/management/settings#Защищённый%20ключ) `api_secret`.
* Идентификатор пользователя `user_id`.
* Пара `$field_name.$field_value`, вернувшаяся в событии.

От полученной после объединения строки вычисляется криптографический хеш SHA256 в байтовом представлении, затем хеш кодируется с помощью алгоритма Base64 Encode.

Пример формирования подписи события на PHP, где `app_id = 7770000`, `api_secret = W7kVvxVxZ4`, `user_id = 162447`, `field_name = phone_number`, `field_value = 70000000000`:

```PHP
$sign = rtrim(strtr(base64_encode(hash('sha256', '7770000W7kVvxVxZ4162447phone_number70000000000', true)), '+/', '-_'), '=');
```

## Песочница

[VKWebAppGetPhoneNumber](https://vk.cc/bZfjAn)


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

# VKWebAppGetUserInfo

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

## Пример

```JavaScript
bridge.send('VKWebAppGetUserInfo', {
  user_id: 743784474
  })
  .then((data) => { 
    if (data.id) {
      // Данные пользователя получены
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `user_id`  &#x0d;&#x0a;*обязательное* | `integer` | Идентификатор пользователя. |

## Результат

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `id` | `integer` | Идентификатор пользователя. |
| `bdate` | `string` | Дата рождения пользователя. Например 10.4.1990 или 10.4 (если год рождения скрыт). Если дата рождения скрыта целиком, поле в ответе отсутствует. |
| `bdate_visibility` | `integer` | Информация о том, отображается ли дата рождения пользователя. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `1` — дата рождения открыта целиком.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `2` — открыты только день и месяц даты рождения.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `0` — дата рождения скрыта. |
| `city` | `object` | Информация о городе пользователя. Объект, который содержит поля:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `id` (`integer`) — идентификатор города.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `title` (`string`) — название города. |
| `country` | `object` | Информация о стране пользователя. Объект, который содержит поля:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `id` (`integer`) — идентификатор страны.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `title` (`string`) — название страны. |
| `photo_200` | `string` | URL квадратной фотографии пользователя с шириной 200 пикселей. Если у пользователя отсутствует фотография, возвращается `https://vk.com/images/camera_200.png`. |
| `photo_max_orig` | `string` | URL фотографии максимального размера. Может быть возвращена фотография, имеющая ширину как 400, так и 200 пикселей. Если у пользователя отсутствует фотография, возвращается `https://vk.com/images/camera_400.png`. |
| `sex` | `integer` | Пол пользователя. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `1` — женский.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `2` — мужской.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `0` — пол не указан. |
| `photo_100` | `string` | URL квадратной фотографии пользователя с шириной 100 пикселей. Если у пользователя отсутствует фотография, возвращается `https://vk.com/images/camera_100.png`. |
| `first_name` | `string` | Имя пользователя. |
| `last_name` | `string` | Фамилия пользователя. |
| `can_access_closed` | `boolean` | Информация о том, может ли пользователь, который открыл мини-приложение, видеть закрытый профиль пользователя. |
| `is_closed` | `boolean` | Информация о том, закрыт ли профиль пользователя. |

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

### События

#### `VKWebAppGetUserInfoResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppGetUserInfoResult",
    data: {
      id: 743784474,
      bdate: "21.12.2000",
      bdate_visibility: 1,
      city: {
        id: 2,
        title: "Санкт-Петербург"
      },
      country: {
        id: 1,
        title: "Россия"
      },
      photo_200: "https://sun1-91.userapi.com/s/v1/ig2/Dcf-SWu7nVYDDldq9oQegiC06VqsSa43-HpDxzPjrvFCUUk9nSevY2Uf9xzm0bxvLfgsTOH6XiiW-zeLcDhPDj_w.jpg?size=200x200&quality=96&crop=26,26,204,204&ava=1",
      photo_max_orig: "https://sun1-91.userapi.com/s/v1/ig2/trHNebJQhG4BmLxC8h4hOpDU6bKRy6uJi586wcyFcCj5fzrwYk7AtoNab-RSil0Bp9b569VQyGK_skG9e6oK7Ap7.jpg?size=256x256&quality=96&crop=0,0,256,256&ava=1",
      sex": 2,
      photo_100: "https://sun1-91.userapi.com/s/v1/ig2/M4vtl7tcmeP6ANUgE0vU7JZWuJszbHaN5QcCcK2xD66EIc6SeSA1NyFVLTSOt2iLOkFhJSJ4DawEJGOjzKtszMpR.jpg?size=100x100&quality=96&crop=26,26,204,204&ava=1",
      first_name: "Персик",
      last_name: "Рыжий",
      can_access_closed: true,
      is_closed: false
    }
  }
}
```

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

#### `VKWebAppGetUserInfoFailed`

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

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

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

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

## Песочница

[VKWebAppGetUserInfo](https://vk.cc/bZfhUc)


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

# VKWebAppShowNativeAds

`VKWebAppShowNativeAds` показывает [рекламу](games/monetization/ad/overview) пользователям в играх и мини-приложениях. Параметры вызова задают [вид желаемой рекламы](games/monetization/ad/overview#Виды%20рекламы%20в%20играх).

Если на стороне пользователя нет рекламных материалов желаемого типа, то [VK&nbsp;Bridge](bridge/overview) запрашивает материалы у платформы ВКонтакте и показывает рекламу после её получения.

## Пример

```JavaScript
bridge.send('VKWebAppShowNativeAds', {
  ad_format: 'interstitial' /* Тип рекламы */
  })
  .then( (data) => { 
    if (data.result) {
      // Реклама была показана
    } else {
      // Ошибка
    }
  })
  .catch((error) => { console.log(error); });
```

#### Другие примеры

* [Реклама за вознаграждение](games/monetization/ad/implementation#Пример%20показа%20рекламы%20за%20вознаграждение)

* [Реклама между экранами](games/monetization/ad/implementation#Пример%20показа%20рекламы%20между%20экранами)

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

В качестве параметров события `VKWebAppShowNativeAds` передайте в [`bridge.send(...)`](bridge/getting-started#Вызов%20события%20VK%20Bridge) объект со следующими полями:

| Параметр | Тип | Описание |
| --- | --- | --- |
| `ad_format` | `string` | [Вид](games/monetization/ad/overview#Виды%20рекламы%20в%20играх) рекламы для показа. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `reward` — [реклама за вознаграждение](games/monetization/ad/overview#Реклама%20за%20вознаграждение).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `interstitial` — [реклама между экранами](games/monetization/ad/overview#Реклама%20между%20экранами). |
| `use_waterfall` | `boolean` | Применим только при `ad_format: 'reward'`. Сообщает ВКонтакте, можно ли использовать рекламные материалы вида `interstitial` в случае отсутствия материалов вида `reward`.&#x0d;&#x0a;Значение по умолчанию: `true`. |

## Результат

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если реклама была показана, или `false` в ином случае. |

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

### События

#### `VKWebAppShowNativeAdsResult`

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

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

```JavaScript
{
  detail: 
  {
    type: "VKWebAppShowNativeAdsResult",
    data:{
      result : true,
      request_id: 5 
    }
  }
}
```

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

#### `VKWebAppShowNativeAdsFailed`

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

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

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

## Примечания

* Перед показом рекламы VK Brdige проверяет, есть ли предзагруженные рекламные материалы указанного типа. Если такие материалы есть, VK Bridge показывает их. Если предзагруженных материалов нет, то библиотека отправляет запрос на их загрузку и показывает полученный контент.

  В общем случае это может приводить к задержке при показе. Чтобы избежать её, используйте [предзагрузку рекламных материалов](games/monetization/ad/implementation).
  
  Запрос не гарантирует, что материалы будут загружены. Сбои в сети или проблемы на стороне рекламной платформы могут привести к тому, что контент не будет получен.

* Сразу после успешного показа рекламы VK Bridge отправляет запрос на предзагрузку следующей порции рекламных материалов.

## Песочница

* Игры: [VKWebAppShowNativeAds](https://vk.cc/bZfCRH)

* Мини-приложения: [VKWebAppShowNativeAds](https://vk.com/app6909581#VktXZWJBcHBTaG93TmF0aXZlQWRzQCU3QiUyMmFkX2Zvcm1hdCUyMiUzQSUyMnByZWxvYWRlciUyMiU3RA)

## Материалы по теме

* [Подробнее о работе с VK Bridge](bridge/getting-started)

* [Реклама в играх](games/monetization/ad/overview)

* [Реклама в мини-приложениях](mini-apps/monetization/ads)

* [VKWebAppCheckNativeAds](bridge/VKWebAppCheckNativeAds)


VK Bridge | Реклама | VKWebAppShowNativeAds

# VKWebAppViewHide

`VKWebAppViewHide` отправляется платформой, когда клиент сворачивает мини-приложение.

## Пример

```JavaScript
bridge.subscribe((e) => {
  if (e.detail.type === 'VKWebAppViewHide') {
    // Логика мини-приложения
  }
});
```

## Платформы

Android, iOS

## Параметры

—

## Результат

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

```JavaScript
{
  detail: {
    type: "VKWebAppViewHide",
    data: { }
  }
}
```

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

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


VK Bridge | События жизненного цикла | VKWebAppViewHide

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

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

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

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

Сообщество

# Грантовая программа Fresh Code 2022 от VK Mini Apps

> Сроки проведения: с 7 октября по 2 декабря 2022 года.
> Подведение итогов: 5 декабря 2022 года.

Мы верим в технологии: видим, как удобные сервисы каждый день помогают миллионам пользователей ВКонтакте делать покупки, путешествовать, учиться, знакомиться. Поэтому развиваем платформу VK Mini Apps — вместе со всеми, кто хочет попробовать себя в разработке мини-приложений или уже создаёт их.

Если у вас есть идея или готовый проект, присоединяйтесь к грантовой программе VK Fresh Code. В этом году она длится два месяца: за это время новые мини-приложения найдут свою аудиторию, и уже в декабре создатели лучших 25 сервисов смогут получить гранты — по 180 000 рублей.

![](26b96330c778c2a0c6cabd5bf91c033e16900373954e0d9f7349f7c6 "1269910100372578947")

**Рассказываем по порядку:**

1. [Как присоединиться к программе и побороться за грант](#Как%20присоединиться%20к%20программе%20и%20побороться%20за%20грант) 
2. [Что даёт Fresh Code, помимо грантов](#Что%20даёт%20Fresh%20Code,%20помимо%20грантов)
3. [Почему мини-приложения в тренде](#Почему%20мини-приложения%20в%20тренде)

## Как присоединиться к программе и побороться за грант

### Шаг 1. Cоздайте оригинальное мини-приложение в тематиках программы

В грантовой программе VK Fresh Code 2022 десять тематик:

* Образ жизни
* Образование
* Мероприятия
* Транспорт
* Развлечения
* Путешествия
* Еда и напитки
* Красота и здоровье
* Бизнес
* Покупки

> Последний день приёма заявок – 2 декабря.
>
> Можно всё это время работать над одним проектом или успеть подготовить несколько мини-приложений в разных темах.

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

* Точно соответствуют одной из тематик.
* Содержат оригинальную идею, которая ещё не встречалась на платформе VK Mini Apps.
* Классно продуманы в плане UX и UI — пользовательского опыта и интерфейса.
* Технически качественно реализованы, пролечены от багов, запускаются на вебе и мобильных платформах.
* Круто прошли питчинг — публичную защиту перед экспертами.
* Попали в каталог мини-приложений.

Полезные ресурсы при подготовке проекта:

* [Документация](mini-apps/getting-started) по разработке мини-приложений.
* [Библиотека VKUI](libraries/vkui) и [макеты Figma](https://www.figma.com/@vk).
* В [сообществе VK Mini Apps](https://vk.com/vkappsdev) вы найдёте много полезных материалов.
* На промежуточных питчингах и сессиях вопросов-ответов все участники смогут получить рекомендации от Команды ВКонтакте.
* Всё о процессе разработки мини-приложения от идеи до релиза вы найдёте в нашем [гайде на Хабре](https://habr.com/ru/company/vk/blog/521192/).

### Шаг 2. Опубликуйте мини-приложение ВКонтакте

Да, публикация мини-приложения в каталоге ВКонтакте не является обязательным условием участия в грантовом конкурсе VK Fresh Code 2022 и получения приза. Но для тех участников, кто всё же планирует получить дополнительные баллы за публикацию мини-приложения в каталоге, дадим пару советов. Стоит учесть, что прежде чем проект попадёт в каталог, он должен пройти [модерацию](mini-apps/catalog/getting-started) и тестирование командой [VK Testers](https://vk.com/testers). Здесь важно рассчитать время, чтобы уложиться в сроки программы: в среднем этот этап занимает около двух недель. Или больше, если в сервисе найдётся много багов.

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

После публикации ваш сервис станет доступен всем пользователям ВКонтакте. Они смогут найти его на вкладке **Сервисы** в мобильном приложении, на [m.vk.com](https://m.vk.com) и в версии для компьютера, а также по ссылке [vk.com/services](https://vk.com/services).

> Для всех победителей конкурса, чьи мини-приложения окажутся в каталоге до&nbsp;**2&nbsp;декабря** включительно, мы подготовим специальное продвижение в рамках новогодних праздников. Это отличная возможность бодро набрать аудиторию для своих проектов.

### Шаг 3. Участвуйте в питчингах с экспертами

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

### Шаг 4. Подайте заявку на грант

Для этого до **23:59 2 декабря** нужно заполнить [форму](https://vk.com/app6013442_-166562603?form_id=33#form_id=33), которая также будет опубликована в [сообществе VK Mini Apps](https://vk.com/vkappsdev). Обязательно укажите в ней ссылку на готовое приложение.

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

### Шаг 5. Дождитесь итогов

Результаты объявим **5 декабря**. Эксперты выберут 25 лучших мини-приложений, авторы которых получат денежные призы — по 180 000 рублей.

## Что даёт Fresh Code, помимо грантов

* **Новые идеи и механики для ваших проектов**

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

* **Опыт питчингов и обратную связь от экспертов**

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

## Почему мини-приложения в тренде

Потому что это удобно: сервисы открываются внутри ВКонтакте и не забивают память телефона, а в каталоге можно найти инструменты на любой случай — купить билеты, записаться на стрижку, проверить курс валют. Поэтому и пользуются мини-приложениями всё чаще: **ежемесячная аудитория VK Mini Apps — более 45 миллионов человек**.

При этом платформа VK Mini Apps продолжает расширяться: к октябрю на ней уже более **50 000 мини-приложений**. Всё потому, что здесь рады разработчикам: документация и обучающие материалы в открытом доступе, образовательные и грантовые программы стали традицией. А в [сообществе](https://vk.com/vkappsdev) легко найти единомышленников, посоветоваться, собрать команду — словом, есть всё, чтобы вместе запускать проекты, которых ждут пользователи.

Fresh Code от VK Mini Apps меняется вместе с платформой: становится динамичнее и предлагает больше. В 2022 году это не только программа, где можно получить знания, создать своё мини-приложение и выиграть грант. Это шанс сделать крутой сервис для миллионов пользователей.
С вопросами о программе пишите в сообщество VK Mini Apps: [vk.me/vkappsdev](https://vk.me/vkappsdev).
Ждём ваши заявки — мы будем рядом на всех этапах. ВКонтакте.

> Актуальной информацией о конкурсе будем делиться в первую очередь в специальном [чате для участников](https://vk.cc/chUkvy), там же можно обсудить, какие технологии стоит интегрировать в свои проекты, и задать интересующие вопросы команде ВКонтакте. Присоединяйтесь: [vk.cc/chUkvy](https://vk.cc/chUkvy)

## Положение о конкурсе

* [Публичное положение об участии в конкурсе](community/events/fresh-code-2022-regulations) 


Сообщество | События | Грантовая программа Fresh Code 2022 от VK Mini Apps

# VK 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 символа.

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

# Примеры масок и эффектов

## `beautify`

| Скачать | Описание |
| --- | --- |
| [**beautify.zip**](https://mask.vk.me/sample/beautify.zip)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Использование эффекта [`beautify`](masks/effects/beautify) для сглаживания кожи лица. Данный эффект рекомендуется размещать самым первым слоем.&#x0d;&#x0a;Автор: Александр Подгайко |

## `colorfilter`

| Скачать | Описание |
| --- | --- |
| [**colorfilter.zip**](https://mask.vk.me/sample/colorfilter.zip)&nbsp;&nbsp;&nbsp;&nbsp; | Примеры использования [фильтра цветокоррекции](masks/effects/colorfilter).&#x0d;&#x0a;Автор: Виталий Заяц |

## `copyface` и `pasteface`

| Скачать | Описание |
| --- | --- |
| [**snail.zip**](https://mask.vk.me/sample/snail.zip) | Размещение частей лица на изображении с помощью эффектов [`copyface`](masks/effects/copyface) и [`pasteface`](masks/effects/pasteface).&#x0d;&#x0a;Автор: Ильназ Габбасович |
| [**funface.zip**](https://mask.vk.me/sample/funface.zip)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Использование эффектов [`copyface`](masks/effects/copyface) и [`pasteface`](masks/effects/pasteface) вместе с [`beautify`](masks/effects/beautify) и [`liquifiedwarp`](masks/effects/liquifiedwarp).&#x0d;&#x0a;Автор: Ильназ Габбасович |

## `facemodel`

| Скачать | Описание |
| --- | --- |
| [**сosmos.zip**](https://mask.vk.me/sample/cosmos.zip)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &#x0d;&#x0a; [**neon.zip**](https://mask.vk.me/sample/neon.zip) &#x0d;&#x0a; [**orange.zip**](https://mask.vk.me/sample/orange.zip) &#x0d;&#x0a; [**tatu.zip**](https://mask.vk.me/sample/tatu.zip) | Использование эффекта [`facemodel`](masks/effects/facemodel) с минимальным набором параметров.&#x0d;&#x0a;Автор: Aнна Ловчикова|
| [**zebra.zip**](https://mask.vk.me/sample/zebra.zip) | Использование эффекта `facemodel` с [разными режимами наложения](masks/effects/facemodel#Параметры%20texture), дополняющими друг друга.&#x0d;&#x0a;Автор: Анна Ловчикова |
| [**skull.zip**](https://mask.vk.me/sample/skull.zip) | [Анимация текстур](masks/effects/facemodel#Параметры%20animation) эффекта `facemodel`.&#x0d;&#x0a;Автор: Анна Ловчикова |

## `liquifiedwarp`

| Скачать | Описание |
| --- | --- |
| [**liquifiedwarp.zip**](https://mask.vk.me/sample/liquifiedwarp.zip)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Преобразование лица с помощью [эффекта пластической деформации](masks/effects/liquifiedwarp).&#x0d;&#x0a;Автор: Никита Конюхов |

## `model3d`

| Скачать | Описание |
| --- | --- |
| [**retro.zip**](https://mask.vk.me/sample/retro.zip)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Использование эффекта [`model3d`](masks/effects/model3d) вместе с [окклюдером](masks/effects/model3d#Invisible%20Occluder).&#x0d;&#x0a;Автор: Ильназ Габбасович |

## `patch`

| Скачать | Описание |
| --- | --- |
| [**beard.zip**](https://mask.vk.me/sample/beard.zip)&#x0d;&#x0a;[**bow_tie.zip**](https://mask.vk.me/sample/bow_tie.zip)&#x0d;&#x0a;[**frame.zip**](https://mask.vk.me/sample/frame.zip)&#x0d;&#x0a;[**glasses.zip**](https://mask.vk.me/sample/glasses.zip)&#x0d;&#x0a;[**hat.zip**](https://mask.vk.me/sample/hat.zip)&#x0d;&#x0a;[**pink_ears.zip**](https://mask.vk.me/sample/pink_ears.zip) | Использование эффекта [`patch`](masks/effects/patch) с минимальным набором параметров.&#x0d;&#x0a;Автор: Aнна Ловчикова |
| [**AnimalEars.zip**](https://mask.vk.me/sample/animalears.zip) | Использование одной текстуры в двух эффектах [`patch`](masks/effects/patch). В примере используются [расширенные параметры текстур](masks/effects/patch#Параметры%20texture).&#x0d;&#x0a;Автор: Виталий Заяц |
| [**LeafAnimation.zip**](https://mask.vk.me/sample/leafanimation.zip)&nbsp;&nbsp; | [Анимация текстуры](masks/effects/patch#Параметры%20animation) эффекта [`patch`](masks/effects/patch). Задание произвольного порядка следования кадров с помощью параметра `timeline_ex`. &#x0d;&#x0a;Автор: Анна Ловчикова |

Маски | Примеры

# Первые шаги

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

* [Подготовьте инструменты](#Шаг%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)

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

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

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

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

owner_id

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

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

account.ban

Создает рекламные объявления.

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

Some part of the request has not been completed

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

account_id

Сериализованный JSON-массив объектов, описывающих создаваемые объявления. Описание объектов `ad_specification` см. ниже.
Максимальное допустимое количество объявлений,
создаваемых  с помощью одного запроса — **5**. Если нужно больше, то можно использовать [`execute`](method/execute).

Пример значения `data`:
```JSON
[{
    "campaign_id": 123456,
    "ad_format": 1,
    "cost_type": 0,
    "cpc": 2.00,
    "category1_id" : 5,
    "title": "Test Title",
    "link_url" : "https://mysite.com",
    "name": "My ad"
}]
```

data

## `ad_specification`

`campaign_id`
Обязательный параметр, `int` (числовое значение).
ID кампании, в которой будет создаваться объявление.

## `ad_format`
Обязательный параметр, `int` (числовое значение).
Формат объявления:
* `1` — изображение и текст;
* `2` — большое изображение;
* `4` — продвижение сообществ или приложений, квадратное изображение. Заголовок объявления (`title`) должен совпадать с названием сообщества/приложения;
* `8` — специальный формат сообществ;
* `9` — запись в сообществе (рекламная запись может быть создана с помощью метода [`wall.postAdsStealth`](method/wall.postAdsStealth));
* `11` — адаптивный формат.

## `autobidding`
Флаг, может принимать значения `0` или `1`.
Автоматическое управление ценой:
* `0` — выключено;
* `1` — включено.

## `autobidding_max_cost`
`integer`, `string`
Максимальное ограничение автоматической ставки в рублях с копейками, `0` — снятие ограничения.

## `cost_type`
Флаг, может принимать значения `0` или `1`
Способ оплаты:
* `0` — оплата за переходы;
* `1` — оплата за показы (включая цель «Максимум показов»);
* `3` — оптимизированная оплата за показы.

## `cpc`
Обязательный параметр, дробное число.
Если `cost_type` равен `0` — цена за переход. Цена указывается в рублях с копейками в дробной части.

## `cpm`
Обязательный параметр, дробное число.
Если `cost_type` равен `1` — цена за 1000 показов. Цена указывается в рублях с копейками в дробной части.

## `ocpm`
Обязательный параметр, дробное число.
Если `cost_type` равен `3` — цена за действие для oCPM. Цена указывается в рублях с копейками в дробной части.

## `goal_type`
`Int` (числовое значение).
Обязательный параметр, если `cost_type` равен `3`.
Тип цели. См. описание возможных значений на [отдельной странице](method/ads.createAds).
[Примеры создания целей](method/ads.createAds).

## `impressions_limit`
`Int` (числовое значение).
Если `ad_format` = `9` или `11` и `cost_type` = `1` — ограничение количества показов данного объявления на одного пользователя.
Допустимые значения: `1`, `2`, `3`, `5`, `10`, `15`, `20`.

## `impressions_limited`
`Флаг`, может принимать значения `0` или `1`.
Если `cost_type` равен `1` и `impressions_limit` не может быть задан — признак того, что количество показов объявления на одного пользователя ограничено.
* `0` — нет ограничения;
* `1` — не более 100 показов на одного пользователя.

## `impressions_limit_period`
`Int` (числовое значение).
Если `ad_format` = `9` или `11` и `cost_type` = `1` — может быть задан период ограничения на количество показов на одного пользователя.
Значение задается в секундах, должно быть кратно суткам (86400 секунд), максимум 90 суток
При наступлении нового периода счетчик показов сбрасывается.

*  `0` — отключает сброс счетчика показов.

## `ad_platform`
Рекламные площадки, на которых будет показываться объявление:
* (если `ad_format` равен `1` и `cost_type` равен `0`):
   * `0` — ВКонтакте и сайты-партнёры;
   * `1` — только ВКонтакте.
* (если `ad_format` равен `9`):
   * `all` — все площадки;
   * `desktop` — полная версия сайта;
   * `mobile` — мобильный сайт и приложения.
* (если `ad_format` равен `11`):
   * `all` — все площадки;
   * `desktop` — полная версия сайта;
   * `mobile` — мобильный сайт и приложения.

## `ad_platform_no_wall`
Только для `ad_format` = `9` или `11`. `1` — не показывать объявление на стенах сообществ (по умолчанию `0`). 

## `ad_platform_no_ad_network`
`integer`, `[0,1]`
Только для `ad_format` = `9` или `11`. `1` — не показывать объявление в рекламной сети (по умолчанию `0`). 

## `publisher_platforms`
Только для `ad_format` = `9` или `11`
На каких площадках будет показываться объявление:

* `all` — Все площадки (по умолчанию);
* `social` — Все соцсети (ВКонтакте и Одноклассники);
* `vk` — Только ВКонтакте.

## `day_limit`
Положительное число.
Дневной лимит в рублях.

## `all_limit`
Положительное число.
Общий лимит в рублях.

## `category1_id`
Положительное число.
ID тематики или подраздела тематики объявления. Если объявление имеет несколько тематик, то дополнительную можно задать в параметре `category2_id`. См. [`ads.getCategories`](method/ads.getCategories).

## `category2_id`
положительное число
ID тематики или подраздела тематики объявления.

## `age_restriction`
Отображение отметки возрастного ограничения на объявлении.
* `0` — не отображать отметку;
* `1` — использовать отметку **0+**;
* `2` — использовать отметку **6+**;
* `3` — использовать отметку **12+**;
* `4` — использовать отметку **16+**;
* `5` — использовать отметку **18+**.

## `status`
Флаг, может принимать значения `0` или `1`
Статус рекламного объявления (`0` — остановлено, `1` — запущено).

## `name`
Строка длиной от **3** до **60** символов.
Название объявления (для использования в рекламном кабинете).

## `title`
Строка длиной от **3** до **33** символов. Для `ad_format` = `11` — до **25** символов.
Заголовок объявления. Может быть задан только для некоторых рекламных форматов.

## `description`
Строка длиной от **3** до **70** символов. Для `ad_format` = `11` — до **90** символов.
Описание объявления. Может быть задано только для некоторых рекламных форматов.

## `link_url`
Обязательный параметр, строка.
Ссылка на рекламируемый объект в формате:
* `http://yoursite.com`;
* `https://vk.com/wall-22822305_383737`;
* `http://vk.cоm/club1`.

Если в ссылке содержатся строки `{ad_id}` или `{campaign_id}`, то они заменяются соответственно на ID объявления и ID кампании в момент перехода пользователя по такой ссылке.

## `link_domain`
Строка.
Домен рекламируемого объекта в формате `yoursite.com`.

## `link_title`
Строка длиной от **3** до **25** символов.
Заголовок рядом с кнопкой/ссылкой. Может быть задан только для некоторых рекламных форматов.

## `link_button`
Идентификатор кнопки объявления. Может быть задан только для некоторых рекламных форматов.

## `photo`
Основное изображение. Может быть передано только для некоторых рекламных форматов. В качестве значения должен быть передан результат [загрузки изображения на сервер](method/ads.getUploadURL).
Если `ad_format` равен 4 или 5, то этот параметр можно не передавать и в этом случае будет использовано изображение из сообщества или приложения.

## `photo_icon`
Логотип. Может быть передано только для некоторых рекламных форматов. В качестве значения должен быть передан результат [загрузки изображения на сервер](method/ads.getUploadURL).

## `video`
Основное видео. Может быть передано только для адаптивного формата. В качестве значения должен быть передан результат [загрузки видео на сервер](method/ads.getVideoUploadURL).

## `repeat_video`
`Флаг`, может принимать значения `0` или `1`.
Зацикливание видео. Возможные значения:
* 0 — не зацикливать видео;
* 1 — зацикливать видео.

## `disclaimer_medical`
`Флаг`, может принимать значения `0` или `1`.
Отображение предупреждения:
«Есть противопоказания. Требуется консультация специалиста.»
* 1 — включить отображение.

## `disclaimer_specialist`
`Флаг`, может принимать значения `0` или `1`.
Отображение предупреждения:
«Необходима консультация специалистов.»
* 1 — включить отображение.

## `disclaimer_supplements`
`Флаг`, может принимать значения `0` или `1`.
Отображение предупреждения:
«БАД. Не является лекарственным препаратом.»
* 1 — включить отображение.

## `weekly_schedule_hours`
`array`
Расписание показа объявления по часам. Массив из семи строк. Каждая из строк соответствует дню недели и содержит последовательность символов `0` или `1`. `0` — не показывать объявление в час, номер которого равен позиции символа. `1` — показывать.
При вызове метода с этим параметром также необходимо обязательно указывать параметр `weekly_schedule_use_holidays`.

## `weekly_schedule_use_holidays`
`Флаг`, может принимать значения `0` или `1`.
Использовать ли расписание воскресенья в праздничные дни.

## `stats_url`
Пиксель внешней статистики. Доступно в избранных кабинетах.

## `stats_url2`
Дополнительный пиксель внешней статистики. Доступно в избранных кабинетах.

## `Настройки таргетинга`
Набор полей, соответствующих настройкам таргетинга. См. описание возможных полей на [отдельной странице](method/ads.updateAds).

```admin
## Параметры (для внутреннего использования)
## `impressions_limit`
`int` (числовое значение)
Если `ad_format` равен 3 и включена возможность установки точного ограничения для данного формата, то допустимые значения:
`0`, `1`, `5`, `10`, `15`, `20`, `30`, `50`, `100`.

Возвращает массив объектов - ответов на каждый запрос в массиве `data`. Соответствующий объект в выходном массиве имеет свойство `id`, соответствующее `id` созданного объявления (или `0` в случае неудачи), а также, возможно, поля `error_code` и `error_desc`, описывающие ошибку, при ее возникновении. Наличие одновременно ненулевого `id` и `error_code` говорит о том, что объявление было создано, однако, возможно, не все параметры установлены (например, объявление не запущено).

ads.createAds

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

Перечисленные через запятую id запрашиваемых объявлений. Максимум **100** объявлений.

ads_ids

Возвращает массив объектов, описывающих охват. Каждый объект содержит следующие поля:

`reach_subscribers`
`integer`
Охват подписчиков.

`reach_total`
`integer`
Суммарный охват.

`links`
`integer`
Переходы по ссылке.

`to_group`
`integer`
Переходы в сообщество.

`join_group`
`integer`
Вступления в сообщество.

`report`
`integer`
Количество жалоб на запись.

`hide`
`integer`
Количество скрытий записи.

`unsubscribe`
`integer`
Количество отписавшихся участников.

ads.getAdsPostsReach

Возвращает URL-адрес для загрузки фотографии рекламного объявления.

Формат объявления:
* `1` — изображение и текст,
* `2` — большое изображение,
* `3` — эксклюзивный формат,
* `4` — продвижение сообществ или приложений, квадратное изображение,
* `5` — приложение в новостной ленте (устаревший),
* `6` — мобильное приложение,
* `11` — адаптивный формат.

Для формата объявления «запись в сообществе» этот метод не используется, т.к. фотографии являются частью записи со стены сообщества. См. методы [`ads.createAds`](method/ads.createAds) и [`wall.postAdsStealth`](method/wall.postAdsStealth).

ad_format

`1` — получить URL для загрузки логотипа, а не основного изображения. Используется только для `ad_format = 11`.

icon

Возвращает URL-адрес для загрузки изображения.

ads.getUploadURL

Редактирует аудиторию ретаргетинга.

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

Id клиента, в рекламном кабинете которого будет редактироваться аудитория.

client_id

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

target_group_id

Новое название аудитории ретаргетинга — строка до 64 символов.

name

Домен сайта, на котором будет размещен код учета пользователей.

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

domain

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

lifetime

Передайте в этом параметре идентификатор пикселя, если требуется собирать аудиторию с веб-сайта.

target_pixel_id

Закодированный в JSON массив правил, в соответствии с которыми будет пополняться аудитория из пикселя. Подробнее см. документацию метода [`ads.createTargetGroup`](method/ads.createTargetGroup).

target_pixel_rules

В случае успеха метод возвратит `1`.

ads.updateTargetGroup

Позволяет получить адрес для загрузки фотографии в коллекцию приложения для [виджетов приложений сообществ](api/community-apps-widgets/getting-started).

Тип изображения. Возможные значения:
* `24x24`;
* `50x50`;
* `160x160`;
* `160x240`;
* `510x128`.

image_type

Возвращает объект с единственным полем `upload_url`, содержащим URL для загрузки изображения.
Для загрузки изображения сгенерируйте `POST`-запрос с файлом в поле `image` на полученный адрес, а затем вызовите метод [`appWidgets.saveAppImage`](method/appWidgets.saveAppImage).

appWidgets.getAppImageUploadServer

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

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

1105

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

phone

last_name

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

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

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

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

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

auth.restore

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

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

board.createComment

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

board.deleteComment

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

group_id

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

topic_id

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

comment_id

Новый текст комментария (является обязательным, если не задан параметр `attachments`).

message

Новый список объектов, приложенных к комментарию и разделённых символом `","`. Поле `attachments` представляется в формате:

```
<type><owner_id>_<media_id>,<type><owner_id>_<media_id>
```

`<type>` — тип медиа-вложения:
* `photo` — фотография 
* `video` — видеозапись 
* `audio` — аудиозапись 
* `doc` — документ

`<owner_id>` — идентификатор владельца медиа-вложения 
`<media_id>` — идентификатор медиа-вложения. 

Например:
```
photo100172_166443618,photo66748_265827614
```

Параметр является обязательным, если не задан параметр `message`.

attachments

board.editComment

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

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

country_id

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

database.getSchoolClasses

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

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

count

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

offset

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

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

type

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

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

return_tags

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

docs.get

Сохраняет документ после его успешной [загрузки](api/upload) на сервер.

Параметр, возвращаемый в результате [загрузки файла](api/upload) на сервер.

file

title

docs.save

downloadedGames

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

Код алгоритма в 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

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

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

user_ids

`1` – необходимо вернуть поле `sign` которое равно: `md5("{id}_{user_id}_{friends_status}_{application_secret}")`, 
Где, id — это идентификатор пользователя, для которого выполняется запрос. Позволяет на сервере убедиться что данные не были подделаны на клиенте.
`0` — поле `sign` возвращать не нужно.

need_sign

После успешного выполнения возвращает массив объектов, каждый из которых содержит следующие поля:
* `user_id` — идентификатор пользователя (из числа переданных в параметре `user_ids`);
* `friend_status` — статус дружбы с пользователем:
   * `0` – пользователь не является другом;
   * `1` – отправлена заявка/подписка пользователю;
   * `2` – имеется входящая заявка/подписка от пользователя;
   * `3` – пользователь является другом. 
* `is_request_unread` — есть ли непрочитанная заявка в друзья от пользователя (`true` — есть, `false` или отсутсвие поля — непрочитанной заявки нет), возвращается только если передан параметр `extended` и `friend_status` = `2`. 

5.38