Игры ВКонтакте — Первые шаги

Игры ВКонтакте — это HTML5-приложения, которые запускаются из пользовательского интерфейса ВКонтакте.

Игры могут быть созданы сотрудниками компании или сторонними разработчиками. Цель этого раздела — рассказать об играх и объяснить, как добавить готовую игру на платформу ВКонтакте. Мы не будем говорить о написании кода или создании графики для игры. Это очень обширные темы, которые выходят за рамки данного руководства.

Краткая инструкция для опытных пользователей

Об играх

Игры ВКонтакте — это HTML5-приложения. Их клиентская часть, работающая на стороне пользователя, — это обычные веб-страницы. Серверная часть может быть реализована с использованием любой современной серверной технологии.

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

Для упрощения обмена данными игры используют специальную библиотеку — VK Bridge. С её помощью удобнее отправлять запросы и получать ответы.

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

Direct Games и Web-игры

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

• •

  Direct Games — игры, которые запускаются из мобильных приложений ВКонтакте для Android или iOS, а также в мобильной версии сайта ВКонтакте (https://m.vk.com);

• •

  Web — игры, которые запускаются в десктопной версии сайта ВКонтакте (https://vk.com).

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

Как создать игру

1. 1.
   Создайте HTML5-приложение игры.
2. 2.
   Подключите к игре библиотеку VK Bridge.
3. 3.
   Разместите игру на каком-либо сервере (хостинге).
4. 4.
   Зарегистрируйте игру ВКонтакте.
5. 5.
   Запустите игру, чтобы проверить, как она работает.

1. Создайте приложение игры

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

Перед тем как зарегистрировать игру ВКонтакте, убедитесь, что она работает. Игра не обязательно должна быть готова на 100%, но она должна возвращать какую-либо страницу или выполнять другие действия, которые позволят понять, запускается она или нет.

2. Подключите VK Bridge

VK Bridge — это библиотека с открытым исходным кодом для обмена данными между вашей игрой и платформой ВКонтакте. Библиотека написана на TypeScript, её код находится на GitHub: https://github.com/VKCOM/vk-bridge.

Есть несколько способов подключения библиотеки к игре.

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

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

1. 1.

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

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

   Чтобы включить файл, используйте следующий код:

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

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

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

   HTML<script> vkBridge.send("VKWebAppInit", {}); </script>

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

Важно! Отправка сообщения VKWebAppInit необходима. Без него библиотека VK Bridge и игровое приложение могут работать некорректно. Мы рекомендуем отправлять сообщение как можно раньше при запуске игры. В идеале — после выполнения минимума начальных действий и до массовой загрузки ресурсов. Допустимый интервал — 30 секунд после старта. Игра должна отправлять это сообщение до отсылки других сообщений.

Способ 2. Использование npm-пакетов

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

1. 1.

   Откройте окно командной строки, перейдите в папку с исходным кодом игры и установите пакет @vkontakte/vk-bridge.

   npm install @vkontakte/vk-bridge

   Если вы используете менеджер пакетов yarn, то установить VK Bridge можно так:

   yarn add @vkontakte/vk-bridge
2. 2.

   Добавьте ссылку на библиотеку в скриптовые файлы вашей игры:

   JavaScriptimport bridge from '@vkontakte/vk-bridge';

   Теперь вы можете использовать объект bridge для обмена данными с серверами ВКонтакте.

3. 3.

   При запуске игра должна посылать сообщение VKWebAppInit. Оно сигнализирует ВКонтакте о старте игры пользователем. Чтобы отправить сообщение, добавьте в код игры следующий вызов:

   JavaScriptbridge.send("VKWebAppInit", {});

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

3. Разместите игру на хостинге

Зачем это нужно

Ваша игра — это веб-приложение. Поэтому вам необходимо разместить файлы игры на каком-либо веб-сервере.

Важно: файлы и ресурсы игры должны быть публично доступны по протоколу HTTPS.

Каким хостингом воспользоваться

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

Проверьте, что сервер работает

После того как вы разместите файлы игры на хостинге, запустите браузер и откройте в нём URL вашей игры. Вы увидите страницу с игровым полем:

Важно: при запуске Web-игры, ВКонтакте открывает веб-страницу с элементом iframe и загружает игру в этот элемент. Большинство веб-серверов разрешает загрузку своих страниц в iframe, но некоторые серверы могут запрещать это делать. Как правило, они включают в свои HTTP-ответы заголовок X-Frame-Options, который сигнализирует браузеру, что страница не должна загружаться в iframe. Важно, чтобы веб-сервер, который вы используете, не накладывал таких запретов. Это требование актуально для Web-игр, а также для игр Direct Games, которые будут работать в мобильной версии сайта ВКонтакте. Для игр Direct Games, которые будут запускаться из мобильных приложений для Android и iOS, такое требование отсутствует.

4. Зарегистрируйте игру ВКонтакте

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

Начните регистрацию

1. 1.

   Откройте десктопную версию сайта ВКонтакте и войдите под своим аккаунтом.

2. 2.

   Перейдите на страницу Мои приложения. Открыть её можно по ссылке vk.com/apps?act=manage или с портала разработчиков dev.vk.com:

   На странице нажмите Создать.

3. 3.

   Заполните свойства игры:

   • •

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

   • •

     Выберите платформу Встраиваемое приложение, тип Игра:

   • •
     Категорию игры (жанр) и описание можно добавить позже. Пока эти поля можно оставить пустыми.
4. 4.

   Нажмите на кнопку Перейти к настройке приложения.

   ВКонтакте отправит код подтверждения на ваш телефон. Это нужно для привязки игры к вашему аккаунту. Оповещение придёт в виде SMS или уведомления в мобильном приложении ВКонтакте.

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

Ура! Игра зарегистрирована. Откроется страница с информацией о ней и настройками.

Примечание: нажимая на кнопку Перейти к настройке приложения, вы выражаете своё согласие с правилами платформы ВКонтакте. Ссылка на эти правила есть на экране создания игры.   Если вы не согласны с правилами — не размещайте игру.

Скопируйте идентификатор игры

В левом меню перейдите в раздел Настройки. В поле ID приложения вы увидите идентификатор вашей игры. Такой идентификатор есть у каждой игры или мини-приложения ВКонтакте. Он понадобится вам для запуска игры.

Укажите настройки Web-игры

Если ваша игра должна запускаться в десктопной версии сайта ВКонтакте, то найдите на странице Настройки блок Web. В этом блоке, в поле Адрес iframe введите URL, который будет использоваться для запуска игры. ВКонтакте загрузит этот URL в iframe при старте игры.

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

Нажмите Сохранить изменения.

Укажите настройки Direct Games

Если ваша игра будет запускаться в мобильном приложении ВКонтакте для Android и iOS или будет работать в мобильной версии сайта ВКонтакте, то прокрутите страницу настроек до раздела Direct Games. В поле Мобильная версия укажите URL для загрузки игры.

Нажмите Сохранить изменения.

  Если ваша игра будет работать и в браузере, и в мобильных приложениях, то заполните поля и в блоке Web, и в Direct Games. Необходимо указать URL для загрузки хотя бы в одном из них. Если очистить оба поля, то одно из значений (последнее заполненное) сохранится.

После того как вы зарегистрировали игру, её можно запустить прямо из ВКонтакте.

5. Запустите игру

В браузере

Сразу после регистрации игра доступна только её создателю и администраторам. Чтобы запустить её, перейдите на страницу Мои приложения и щёлкните по игре:

Вы увидите игру в интерфейсе ВКонтакте.

В мобильном приложении

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

https://m.vk.com/app{game-id}

где {game-id} — это идентификатор, который отображается на странице настроек игры.

Примечания

• •

  При старте игры платформа ВКонтакте передаёт ей URL-параметры с идентификатором пользователя, настройками запуска и информацией об источнике запуска. Игры и мини-приложения, как правило, анализируют их, чтобы вернуть данные, соответствующие контексту запуска. Подробноcти — в разделе Авторизация пользователя.

• •

  Web-игры могут быть запущены в стандартном или широкоформатном режиме. Подробнее о переключении режимов — в разделе Форматы экрана.

• •

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

Краткая инструкция

1. 1.

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

2. 2.

   Подключите к игре библиотеку VK Bridge. Добавьте код, который будет отправлять платформе ВКонтакте сообщение о старте игры:

   JavaScriptbridge.send("VKWebAppInit", {});

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

3. 3.

   Разместите игру на каком-либо веб-сервере (хостинге). HTML-страницы, скриптовые файлы, изображения и другие ресурсы игры должны быть доступны по протоколу HTTPS.

   Для игр, которые будут работать в десктопной или мобильной версии сайта ВКонтакте, веб-сервер игры не должен запрещать загружать файлы в iframe. Как правило, веб-серверы для этого добавляют заголовок X-Frame-Options в свои ответы. Ваш веб-сервер не должен его добавлять.

4. 4.

   Зарегистрируйте игру ВКонтакте на странице Мои приложения.

   Укажите страницу или ресурс, который будет загружаться при старте игры. Для игр Web и Direct Games за это отвечают различные настройки. При необходимости заполните обе группы настроек.

5. 5.

   Запустите игру из ВКонтакте, чтобы убедиться, что она работает.

Далее вы можете развивать и монетизировать игру:

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

Что дальше

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

Описание и скриншоты

Зайдите в настройки игры на страницу Информация. Отредактируйте описание и жанр игры, добавьте скриншоты. Это важные параметры для продвижения игры и для её показа в каталогах и подборках.

Тестирование и разработка

Вы можете зарегистрировать игру ВКонтакте и продолжать её разработку. Чтобы указать URL для разработки:

• •

  перейдите в настройки игры;

• •

  в блоках Web и Direct Games поставьте галочку Режим разработки;

• •

  укажите адрес для загрузки тестовой версии вашей игры.

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

С самоподписанным SSL-сертификатом игра не будет работать в мобильных приложениях ВКонтакте.

Взаимодействие с API ВКонтакте

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

Работа с ресурсами для iOS

Для организации ресурсов игр, работающих на устройствах iOS, используйте технологию ODR (On-Demand Resources) компании Apple. Эта технология позволяет игре хранить свои ресурсы (файлы .css, .js, шрифты, графику) отдельно от игровых модулей в App Store и загружать их по запросу пользователя. Это уменьшает размер игрового приложения, ускоряет загрузку игры и даёт возможность игре использовать больше ресурсов. Подробное описание есть в разделе Работа с ресурсами для iOS.

Доступ к игре

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

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

Мы рекомендуем настроить двухфакторную аутентификацию (2FA) всем пользователям-администраторам игры. Это повысит как безопасность их аккаунтов, так и самой игры. Включить этот режим можно в настройках аккаунта ВКонтакте.

Публикация

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

Игры можно размещать в каталогах игр, сообществах и виджетах ВКонтакте, а также на других популярных площадках: в Одноклассниках, в мобильной версии браузера Atom для Android и в мобильном приложении Почта Mail.ru.

Реклама и монетизация

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

Продвижение

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