Обновлена 20 октября 2026 г. в 14:33

Как включить загрузку вложений в офлайн-режиме

Назначение документа

В инструкции описана настройка загрузки вложений для отображения в офлайн-режиме в клиентского приложения VK WorkSpace — Супераппа (ранее — VK Teams). Документ предназначен для использования администраторами организации.

Документ предназначен для использования администраторами организации.

Общее описание

В конфигурационном файле myteam-config.json в секции offline-attachments с версии 26.3 доступно управление локальными кэшированием вложений Почты и Календаря. После завершения загрузки сохраненный файл можно повторно открыть без сетевого запроса, в том числе без подключения к сети.

Секция offline-attachments задается отдельно для Почты и Календаря (mail-android, calendar-android и т.д). Оба продукта используют одинаковый набор параметров, но независимые кэши и квоты.

Пример конфигурационного файла для Android:


{  "services": {    "config": {      "<домен Почты VK WorkSpace>": {        "mail-android": {          "offline-attachments": {            "attachments-offline-enabled": true,            "target-quota-bytes": 524288000,            "max-file-size-bytes": 104857600,            "cloud-ttl-ms": 3600000,            "immutable-ext-list": [],            "lower-urgency-preemption-threshold": 9999,            "shrink-target-usage-percent": 0.8,            "max-parallel-attachment-downloads": 2,            "shrink-period-minutes": 1440,            "shrink-start-hour": 4,            "notification-enabled": true,            "cloud-weblink-api-url": "https://openapi.cloud.<домен Почты VK WorkSpace>.ru/api/v1/weblink/download"          }        },        "calendar-android": {          "offline-attachments": {            "attachments-offline-enabled": true,            "target-quota-bytes": 524288000,            "max-file-size-bytes": 104857600,            "cloud-ttl-ms": 3600000,            "immutable-ext-list": [],            "lower-urgency-preemption-threshold": 9999,            "shrink-target-usage-percent": 0.8,            "max-parallel-attachment-downloads": 2,            "shrink-period-minutes": 1440,            "shrink-start-hour": 4,            "notification-enabled": true,            "cloud-weblink-api-url": "https://openapi.cloud.<домен Почты VK WorkSpace>.ru/api/v1/weblink/download"          }        }      }    }  }}

Ключевые особенности

Ключевые особенности работы:

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

Настройте загрузку офлайн-вложений

В конфигурационном файле /usr/local/nginx-im/html/myteam/myteam-config.json установите необходимые значения параметров. Описание параметров в секции offline-attachments приведено в таблице ниже:

Параметр	Тип	Значение по умолчанию	Описание
attachments-offline-enabled	Boolean	`false`	Главный флаг offline-вложений для выбранного продукта. `true` — разрешает предварительное сохранение вложений, использование локального кэша и его фоновую очистку. `false` — запрещает принимать новые запросы на offline-кэширование через этот механизм. Почта и Календарь включаются независимо. Выключение флага не удаляет уже сохраненные файлы автоматически.
target-quota-bytes	Long	`524288000` — 500 МБ	Целевой суммарный размер offline-кэша выбранного продукта. Если кэш превышает квоту, механизм очистки удаляет менее актуальные вложения, пока объем не вернется к целевому значению. Квоты Почты и Календаря независимы. Если для обоих продуктов указано 500 МБ, это два отдельных кэша по 500 МБ. Квота является целевым, а не абсолютно жестким лимитом: до очередного запуска очистки фактический объем может временно быть выше.
max-file-size-bytes	Long	`104857600` — 100 МБ.	Максимальный размер одного файла, который можно поместить в управляемый offline-кэш. Файл большего размера не сохраняется в кэше. При пользовательском открытии или экспорте платформа может скачать такой файл напрямую во временное либо выбранное пользователем хранилище. Параметр ограничивает размер кэшируемого файла, а не общий размер вложения, которое пользователь может скачать.
cloud-ttl-ms	Long	`3600000` — 1 час.	Определяет, сколько времени закэшированная версия изменяемого Cloud-вложения считается актуальной. После истечения TTL при следующем запросе на сохранение или обновление клиент проверяет актуальность файла и при необходимости загружает новую версию. Само истечение TTL не удаляет файл и не запускает загрузку по таймеру.Параметр применяется к изменяемым вложениям типа `cloud`. Вложения типов `mail` и `cloud_stock` считаются неизменяемыми.
immutable-ext-list	массив строк	`[]`	Список расширений Cloud-файлов, которые считаются неизменяемыми и не требуют обновления по `cloud-ttl-ms`. Пример: `immutable-ext-list":["pdf", "jpg", "png"]` . Расширения указываются без точки. Сравнение выполняется без учета регистра. Пустой список означает, что все вложения типа `cloud` считаются потенциально изменяемыми.
lower-urgency-preemption-threshold	`Int` или `null`	`9999`	Порог приоритета, начиная с которого запрос считается высокоприоритетным. Такая загрузка может приостановить менее приоритетную и не должна вытесняться фоновыми запросами. Стандартные приоритеты: `0` — Фоновое сохранение `100` — Пользователь открыл письмо или событие `200` — Пользователь перешел к конкретному вложению `10000` — Пользователь экспортирует файл `20000` — Пользователь открывает файл При значении `9999` высокоприоритетными считаются экспорт и открытие файла. Значение `null` отключает приоритетное прерывание для стандартных сценариев.
shrink-target-usage-percent	`Double` или `null`	`0.8`	Целевая доля заполнения кэша после очистки. Значение `0.8` означает, что при превышении квоты очистка должна освободить место до 80% от `target-quota-bytes`, создавая запас для новых файлов. Диапазон: от `0.0` до `1.0`.
max-parallel-attachment-downloads	`Int`	`1`	Максимальное количество вложений, которые клиент может загружать параллельно для выбранного продукта. Например, значение `2` разрешает одновременно загружать не более двух вложений; остальные запросы ожидают освобождения места в очереди. Увеличение значения может ускорить обработку очереди, но повышает одновременную нагрузку на сеть, процессор и хранилище устройства. Значение должно быть положительным целым числом.Фактическое ограничение Android при получении настройки через MyTeam config описано в разделе «Текущие особенности Android-интеграции».
shrink-period-minutes	`Int`	`1440` — 24 часа	Фактическое время запуска может быть сдвинуто операционной системой из-за ограничений фоновой работы, энергосбережения или состояния устройства.
shrink-start-hour	`Int`	`4`	Час первого планового запуска очистки по локальному времени устройства. Допустимые значения: от `0` до `23`. При значении `4` первая очистка планируется на ближайшие 04:00, после чего применяется интервал `shrink-period-minutes`.
notification-enabled	`Boolean`	`false`	Управляет системными уведомлениями о работе очереди offline-вложений: `true` — платформа может показывать начало загрузки, прогресс, завершение и ошибку приоритетной загрузки `false` — загрузка выполняется без таких уведомлений Внешний вид и правила показа уведомлений зависят от возможностей Android, iOS или Desktop.
cloud-weblink-api-url	`String`, абсолютный URL	`https://openapi.cloud.<домен Почты VK WorkSpace>.ru/api/v1/weblink/download`	Эндпойнт используется для получения прямой ссылки на скачивание вложения типа `cloud`. Клиент передает авторизационные данные, получает промежуточную ссылку, а затем финальный URL файла. Для вложений типов `mail` и `cloud_stock` используется переданная прямая ссылка, поэтому этот параметр на них не влияет.

Параметр

Тип

Значение по умолчанию

Описание

attachments-offline-enabled

Boolean

false

Главный флаг offline-вложений для выбранного продукта.
true — разрешает предварительное сохранение вложений, использование локального кэша и его фоновую очистку.
false — запрещает принимать новые запросы на offline-кэширование через этот механизм.
Почта и Календарь включаются независимо. Выключение флага не удаляет уже сохраненные файлы автоматически.

target-quota-bytes

Long

524288000 — 500 МБ

Целевой суммарный размер offline-кэша выбранного продукта. Если кэш превышает квоту, механизм очистки удаляет менее актуальные вложения, пока объем не вернется к целевому значению. Квоты Почты и Календаря независимы. Если для обоих продуктов указано 500 МБ, это два отдельных кэша по 500 МБ. Квота является целевым, а не абсолютно жестким лимитом: до очередного запуска очистки фактический объем может временно быть выше.

max-file-size-bytes

Long

104857600 — 100 МБ.

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

cloud-ttl-ms

Long

3600000 — 1 час.

Определяет, сколько времени закэшированная версия изменяемого Cloud-вложения считается актуальной. После истечения TTL при следующем запросе на сохранение или обновление клиент проверяет актуальность файла и при необходимости загружает новую версию. Само истечение TTL не удаляет файл и не запускает загрузку по таймеру.Параметр применяется к изменяемым вложениям типа cloud. Вложения типов mail и cloud_stock считаются неизменяемыми.

immutable-ext-list

массив строк

[]

Список расширений Cloud-файлов, которые считаются неизменяемыми и не требуют обновления по cloud-ttl-ms. Пример: immutable-ext-list":["pdf", "jpg", "png"] .
Расширения указываются без точки. Сравнение выполняется без учета регистра. Пустой список означает, что все вложения типа cloud считаются потенциально изменяемыми.

lower-urgency-preemption-threshold

Int или null

9999

Порог приоритета, начиная с которого запрос считается высокоприоритетным. Такая загрузка может приостановить менее приоритетную и не должна вытесняться фоновыми запросами. Стандартные приоритеты:
0 — Фоновое сохранение
100 — Пользователь открыл письмо или событие
200 — Пользователь перешел к конкретному вложению
10000 — Пользователь экспортирует файл
20000 — Пользователь открывает файл
При значении 9999 высокоприоритетными считаются экспорт и открытие файла. Значение null отключает приоритетное прерывание для стандартных сценариев.

shrink-target-usage-percent

Double или null

0.8

Целевая доля заполнения кэша после очистки. Значение 0.8 означает, что при превышении квоты очистка должна освободить место до 80% от target-quota-bytes, создавая запас для новых файлов. Диапазон: от 0.0 до 1.0.

max-parallel-attachment-downloads

Int

1

Максимальное количество вложений, которые клиент может загружать параллельно для выбранного продукта. Например, значение 2 разрешает одновременно загружать не более двух вложений; остальные запросы ожидают освобождения места в очереди. Увеличение значения может ускорить обработку очереди, но повышает одновременную нагрузку на сеть, процессор и хранилище устройства. Значение должно быть положительным целым числом.Фактическое ограничение Android при получении настройки через MyTeam config описано в разделе «Текущие особенности Android-интеграции».

shrink-period-minutes

Int

1440 — 24 часа

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

shrink-start-hour

Int

4

Час первого планового запуска очистки по локальному времени устройства. Допустимые значения: от 0 до 23. При значении 4 первая очистка планируется на ближайшие 04:00, после чего применяется интервал shrink-period-minutes.

notification-enabled

Boolean

false

Управляет системными уведомлениями о работе очереди offline-вложений:
true — платформа может показывать начало загрузки, прогресс, завершение и ошибку приоритетной загрузки
false — загрузка выполняется без таких уведомлений
Внешний вид и правила показа уведомлений зависят от возможностей Android, iOS или Desktop.

cloud-weblink-api-url

String, абсолютный URL

https://openapi.cloud.<домен Почты VK WorkSpace>.ru/api/v1/weblink/download

Эндпойнт используется для получения прямой ссылки на скачивание вложения типа cloud. Клиент передает авторизационные данные, получает промежуточную ссылку, а затем финальный URL файла. Для вложений типов mail и cloud_stock используется переданная прямая ссылка, поэтому этот параметр на них не влияет.

Была ли статья полезна?

Содержание

Была ли статья полезна?