ДокументацияAPIСообществоСоздать приложение
Войти

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

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

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

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

Разработка

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

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

Если вы разрабатываете фронтенд мини-приложения на TypeScript, используйте библиотеку vite-plugin-singlefile. Если вы не будете использовать эту библиотеку, технология ODR не будет работать.

Важно! Убедитесь, что вы указали Apple Developer Team ID и Apple Developer Team Name.

Шаг 1. Подготовка

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

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

Пример каталога проекта

. ├ index.html ├ favicon.ico ├ manifest.json ├ service-worker.js └ static ├ css   └── main.css ├ js   └── main.js └ media └── main.png

Следующий шаг зависит от того, где вы храните файлы проекта. Если вы используете хостинг статики, пропустите шаг 2.

Шаг 2. Загрузка архива с файлами проекта

  1. 1.

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

    Важно!

    • •

      Формат файла — ZIP-архив с расширением .zip.

    • •

      Максимальный размер архива — 20 МБ.

    • •

      Максимальный размер распакованного архива — 40 МБ.

    • •

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

  2. 2.

    В разделе Загрузка архива для ODR нажмите кнопку Загрузить архив.

  3. 3.

    Во всплывающем окне Загрузка архива:

    • •
      Введите версию архива.
    • •
      Нажмите кнопку Выбрать файл.
    • •
      Нажмите кнопку Сохранить.

Шаг 3. Модерация архива

Чтобы подать заявку на проверку архива, нажмите на кнопку Отправить на модерацию.

Дедлайн отправки архивов — 12 часов каждого вторника (GMT+3). Полученные к этому времени архивы отправляются на модерацию.

Процесс модерации архива:

  • •
    Понедельник и вторник следующей недели — проверка архивов.
  • •
    Среда — тестирование архива. Некоторые архивы могут не пройти тестирование и не перейти на следующий шаг. Вы получите соответствующее сообщение.
  • •
    После успешного тестирования архив передаётся на проверку в App Store.
  • •
    Модерация архива занимает 1-2 недели.

После создания заявки она появится в разделе Помощь на вкладке Все вопросы. Все сообщения этапов модерации будут доступны там же.

Шаг 4. Загрузка с помощью хостинга статики

Если вы используете хостинг статики:

  1. 1.
    В разделе Загрузка архива для ODR поставьте флажок Загружать мини-приложения в ODR из хостинга. Флажок доступен только тем мини-приложениям, которые уже используют хостинг статики.
  2. 2.
    Нажмите кнопку Сохранить изменения.
  3. 3.
    Обновите каталог со своим проектом на хостинге.

CORS-ошибки

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

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

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

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

CORS header ‘Origin’ cannot be added

URL-схема vkcors

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

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

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

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

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

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

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

Проблема при отправке BLOB-объектов

Если вам необходимо передавать в запросе двоичные данные в виде BLOB, с помощью FormData или просто в теле запроса, конвертируйте BLOB-объекты в USVString любым удобным способом.

Пример

JavaScriptconst promises = []; for (let [name, value] of formData) { if (typeof value === 'string') { formData.append(name, value); } else { promises.push(new Promise((resolve, reject) => { var reader = new FileReader(); reader.onloadend = function () { resolve(reader.result); } reader.readAsDataURL(value); }); .then((dataUrl) => { formData.append(name, dataUrl); // Добавить значение любого поля, кроме Blob. })); } } Promise.all(promises) .then((arr) => { this.sendOrig(formData); });

Проблема в том, что у WebKit, который мы используем для поддержки схемы vkcors, пока отсутствует функциональность, позволяющая отправлять BLOB-объекты в запросах, использующих схемы, отличные от HTTP.

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

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

Шаг 1. Размещение тестовой сборки

  • •

    Если ваше приложение размещено не на хостинге мини-приложений, в разделе Загрузка архива для ODR разместите тестовую сборку.

  • •

    Если ваше приложение размещено на хостинге мини-приложений:

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

Шаг 2. Создание группы тестировщиков архива ODR

  1. 1.
    В разделе Загрузка архива для ODR нажмите кнопку Тестирование ODR.
  2. 2.
    Во всплывающем окне Управление участниками тестирования ODR:
    • •
      Выберите тестировщиков из администраторов мини-приложения.
    • •
      Нажмите кнопку Сохранить.

Шаг 3. Завершение

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

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

FAQ

Обязательно ли отправлять вам ресурсы?

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

Что такое ODR?

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

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

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

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

Как протестировать архив?

Чтобы локально протестировать архив, откройте файл со ссылками на ресурсы (например, index.html) в браузере на локальной машине.

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

Как поменять абсолютные пути к ресурсам на относительные?

Чтобы заменить все абсолютные пути на относительные, в файле package.json укажите: "homepage": "./". Важно проследить, чтобы был правильно указан HTML-тег <base>.

Как часто обновляется каталог с ресурсами мини-приложения на устройстве пользователя?

Каталог обновляется один раз в неделю вместе с обновлением в App Store приложения ВКонтакте.

Я выбираю в настройках «Загружать мини-приложения в ODR из хостинга», но ничего не меняется.

Отправьте каталог проекта на хостинг ещё раз.

Что такое CORS?

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

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

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

Не могу передать серверу данные из формы.

Возможно, данные не передаются, потому что отсутствует тело запроса. Проверьте, что вы не отправляете запросы с BLOB-объектами и не используете объект FormData, содержащий эти объекты. Использовать BLOB пока нельзя, так как WebKit не умеет передавать этот тип данных в vkcors-запросах.

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

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

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

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

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

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

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

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

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

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

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

JavaScriptconst 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" && checkVersion(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); }

Я не вижу блок «Загрузка архива для ODR» в настройках мини-приложения. Что делать?

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

Список Кто может загружать архив находится в разделе Загрузка архива для ODR.