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

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

Разработка

При первом запуске игры клиент ВКонтакте сохраняет все её ресурсы на устройстве пользователя. Например: файлы .css, .js, шрифты и графику. Это позволит в следующий раз запустить игру гораздо быстрее.

Для организации ресурсов используется технология ODR (On-Demand Resources), разработанная компанией Apple. Её должны применять не только игры и мини-приложения ВКонтакте, но и любые другие приложения, представленные в App Store и содержащие встроенные сервисы. Но разработчику игр не нужно самостоятельно в этом разбираться, достаточно отправить нам ресурсы, а всю остальную работу берёт на себя ВКонтакте.

Шаг 1. Подготовка файлов

Чтобы подготовить файлы ресурсов:

1.
В файлах с кодом игры .html укажите относительные пути ко всем файлам ресурсов, которые нужны вашей игре. Например: .css, .js, файлы шрифтов и графические файлы.
2.
Убедитесь, что вы указываете путь к текущему каталогу, а не к корневому. Правильно: "./main.js", неправильно: "/main.js". Чтобы проверить, корректно ли указаны пути к ресурсам, откройте файл .html в браузере и убедитесь, что все они доступны.
3.
Создайте ZIP-архив со всеми файлами, подготовленными на предыдущем шаге. Убедитесь, что размер архива не превышает 20 МБ.

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

Если файлы со ссылками на ресурсы (например, .php) генерируются на сервере только в момент запуска игры, их нельзя передать в архиве. Для запуска на iOS необходимо создать статическую версию проекта, которая будет содержать .html.

Шаг 2. Загрузка архива

1.
Откройте Мои приложения → Редактировать → Настройки.
2.
В разделе Загрузка архива для ODR нажмите на кнопку Загрузить архив.
3.
В открывшемся окне введите версию архива и загрузите его.
4.
Нажмите на кнопку Отправить на модерацию, чтобы подать заявку на проверку архива.

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

Важно!

•
Формат файла — ZIP-архив с расширением .zip.
•
Максимальный размер архива — 20 МБ.
•
Максимальный размер распакованного архива — 40 МБ.
•
В разделе «Название архива» на этапе загрузки необходимо указывать именно версию вида v0.0.1 и обновлять данные, когда загружаете новый архив.

CORS-ошибки

Все игры, которые запускаются в iOS-клиенте версии 6.46 и выше, используют технологию ODR. При этом файлы приложения (в том числе index.html) запускаются локально на устройстве пользователя.

Так как игра запускается из файла, сохраненного локально, при сетевых запросах, необходимых для взаимодействия с сервером, в HTTP-заголовке Origin передаётся значение null.

Если на вашем сервере настроены политики работы с CORS-заголовками, то в ответе на запросы без адреса источника вместо данных будет возвращаться CORS-ошибка.

Пример текста CORS-ошибки

[CORS header ‘Origin’ cannot be added](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSOriginHeaderNotAdded)

URL-схема vkcors

Чтобы получать данные с сервера, используйте в запросах адрес с URL-схемой vkcors. Это означает, что во всех HTTPS-запросах нужно заменять название протокола с https на vkcors.

Например, если для Android-клиента (где не используется технология ODR) URL в сетевом запросе выглядит:

let response = await fetch('https://server.io/api/endpoint');

То для iOS-клиента (с технологией ODR) URL должен выглядеть так:

let response = await fetch('vkcors://server.io/api/endpoint');

В результате будет выполнен HTTPS-запрос, в котором заголовок Origin будет содержать адрес хоста из URL приложения (Мои приложения → Настройки → Версия для мобильных клиентов).

Важно! URL-схема vkcors работает в iOS-клиенте версии 6.47 и выше.

Отладка работоспособности ODR-режима

Протестируйте загруженный архив в ODR-режиме, чтобы отладить его работу. Сделать это можно в iOS-клиенте, начиная с версии 6.48.

Шаг 1

Разместите тестовую сборку в настройках игры:

Шаг 2

Вы можете управлять администраторами игры, для которых будет доступна опция тестирования ODR-архива. Для этого нажмите на кнопку Тестирование ODR:

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

Шаг 3

Теперь игру можно открыть на клиенте — при этом оно загрузится в режиме тестирования архива ODR. Это означает, что будут использованы файлы из последнего загруженного вами архива.

Как проверить и удостовериться, что игра запущена именно в режиме тестирования архива ODR? Нажмите на три точки в правом верхнем углу экрана игры. В верхней части action menu будет видна пометка В режиме теста ODR:

FAQ

Что такое ODR?

Для организации ресурсов игр используется технология ODR (On-Demand Resources), разработанная компанией Apple. Суть её в том, что при первом запуске файл index.html с кодом игры и файлы ресурсов сохраняются на устройстве пользователя. То есть после первого запуска игра будет запускаться из файла, сохраненного локально.

Каким должен быть архив для ODR?

Создавая версию игры по ODR, обратите внимание на следующие моменты:

1.
Важно, чтобы в консоли разработчика отображался только локальный путь, то есть в архив надо спрятать всё, что интерпретируется как код (CSS, HTML, JS). Исключением могут быть только аналитические сервисы.
2.
Медиа и данные не обязательно размещать в архиве (грузить json и интерпретировать их как код не нужно). Рекомендуем размещать в архиве только те материалы, которые нужны для первого запуска.
3.
Максимальный размер архива — 20 МБ, после распаковки — 40 МБ. Если архив тяжелее, вынесите из него данные или медиа.
4.
В консоли разработчика не должны отображаться ошибки CORS. Проверьте, чтобы во всех HTTPS-запросах было заменено название протокола с https на vkcors.

Как понять, что игра использует для запуска технологию ODR?

Технология ODR используется во всех версиях iOS-приложения ВКонтакте версии 6.46 и выше. Также в параметрах запуска будет передаваться: odr_enabled=1.

https://prod-app.com/index.html?vk_access_token_settings=&vk_app_id=6909581& ... &odr_enabled=1

Что такое CORS?

Cross-Origin Resource Sharing – это механизм, который позволяет безопасно выполнять кроссдоменные запросы, то есть обращаться к ресурсам на другом домене.

Как пройти модерацию?

После того как вы подготовили архив и проверили, что он работает, загрузите его в управлении приложением (раздел Настройки → Загрузка архива для ODR iOS). После загрузки отправьте архив на модерацию. Обратите внимание, что вы не сможете загрузить новый файл, пока модерация не завершится. Если модерация пройдена, появится такое уведомление: После выхода новой версии приложения вы увидите уведомление о том, что ваша игра доступна в приложении. В случае отказа вы получите комментарий модератора.

Сколько времени занимает прохождение модерации?

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

Как обновлять приложение после прохождения модерации?

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

Обратите внимание:

•
Архив обновится в приложении только после обновления приложения ВКонтакте в AppStore. Это происходит примерно раз в неделю.
•
Если новый архив будет некорректным, игра будет удалена из каталога на iOS.

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

Можно ли просто отвечать на запросы с любых доменов?

Можно использовать HTTP-заголовок ответа Access-Control-Allow-Origin — только если вы полностью осознаете последствия. Мы не рекомендуем этот подход, так как в этом случае доступ к ресурсам открыт для любого источника.

Как проверить версию клиентского приложения ВКонтакте?

Вызовите событие VKWebAppGetClientVersion. Пример:

JavaScript

const checkVersion = (a, b) => {

 const [majorA, minorA] = String(a).split('.').map(v => Number.parseInt(v));
 const [majorB, minorB] = String(b).split('.').map(v => Number.parseInt(v));

 if (majorA !== majorB) {
  return majorA > majorB;
 }

 return minorA > minorB;

};

const params = new URLSearchParams(location.href);
const {
 version
} = await bridge.send('VKWebAppGetClientVersion');
let scheme = 'https';

if (params.get('odr_enabled') === "1" && isGreater(version, '6.46')) {
 scheme = 'vkcors';
}

let response = await fetch(`${scheme}://server.io/api/endpoint`);
if (response.ok) {
 let json = await response.json();
} else {
 alert('Ошибка: ' + response.status);
}

На этой странице

РазработкаШаг 1. Подготовка файловШаг 2. Загрузка архиваCORS-ошибкиURL-схема vkcorsОтладка работоспособности ODR-режимаFAQЧто такое ODR?Каким должен быть архив для ODR?Как понять, что игра использует для запуска технологию ODR?Что такое CORS?Как пройти модерацию?Сколько времени занимает прохождение модерации?Как обновлять приложение после прохождения модерации?Можно ли просто отвечать на запросы с любых доменов?Как проверить версию клиентского приложения ВКонтакте?