Битрикс24 позволяет хранить конфигурацию приложения на стороне портала: app.option — общие настройки для всех, user.option — персональные для каждого пользователя. Это избавляет от собственной базы под простые сценарии.
Зачем нужно хранилище опций
Почти каждому приложению нужно где-то держать настройки: ключ внешнего сервиса, выбранную воронку, флаги функций. Разворачивать под это отдельную БД избыточно, особенно для тиражного приложения, которое устанавливается на чужие порталы без вашей инфраструктуры.
Битрикс24 предлагает встроенное хранилище «ключ-значение», привязанное к приложению. Данные лежат на портале, доступны через REST и не требуют от вас ни сервера, ни миграций.
- app.option — общие настройки приложения на портале;
- user.option — настройки в разрезе конкретного пользователя.
app.option: общие настройки
Метод app.option.set сохраняет значения для всего приложения на портале, а app.option.get их читает. Настройки видят все пользователи, но менять их обычно разрешают только администратору — доступ к записи регулируется на уровне вашей логики.
Запись нескольких опций одним вызовом:
{
"options": {
"api_key": "abc123",
"default_pipeline": "7"
}
}
Чтение без параметров вернёт все сохранённые опции приложения. Если передать имя, вернётся конкретное значение. Значения хранятся как строки, поэтому массивы и объекты сериализуйте самостоятельно, например через JSON.stringify.
user.option: персональные настройки
Методы user.option.set и user.option.get работают так же, но привязывают данные к текущему пользователю в контексте приложения. Это удобно для индивидуальных предпочтений интерфейса.
- Выбранный вид отображения или фильтр в placement;
- Персональные уведомления и флаги «не показывать снова»;
- Черновики и последние введённые значения.
| Свойство | app.option | user.option |
|---|---|---|
| Область | Всё приложение | Один пользователь |
| Кто видит | Все | Только владелец |
| Типовой сценарий | Ключи, воронки, режимы | Настройки UI, черновики |
Лимиты и подводные камни
Встроенное хранилище удобно, но у него есть ограничения, о которых важно помнить на этапе проектирования.
- Только строки. Числа, массивы и объекты нужно сериализовать вручную;
- Ограничение объёма. Опции рассчитаны на компактную конфигурацию, а не на сотни килобайт данных;
- Нет выборок и индексов. Нельзя фильтровать по значению — вы читаете всё и разбираете на своей стороне;
- Привязка к приложению. При удалении приложения опции теряются вместе с ним.
Альтернативы: entity storage и своя БД
Когда конфигурации становится мало и нужны именно данные, опции перестают подходить. Битрикс24 предлагает два других уровня.
| Механизм | Для чего | Методы |
|---|---|---|
| Опции | Настройки и флаги | app.option.*, user.option.* |
| Entity storage | Небольшие структурированные данные на портале | entity.add, entity.item.add |
| Своя БД | Большие объёмы, аналитика, история | Ваш backend + REST |
Entity storage позволяет создать собственную сущность методом entity.add и хранить в ней элементы с полями и правами доступа. Это компромисс между опциями и полноценной БД. Для тяжёлых сценариев с отчётами и историей выбирайте собственное хранилище, а на портале держите только идентификаторы.
Практические рекомендации
Несколько правил, которые упрощают жизнь при работе с опциями в реальном приложении.
- Читайте настройки один раз при загрузке обработчика и кэшируйте в памяти запроса, а не дёргайте REST на каждый чих;
- Заводите префиксы имён опций, чтобы не конфликтовать при развитии приложения;
- Версионируйте формат: храните поле
schema_version, чтобы уметь мигрировать структуру; - При установке приложения задавайте значения по умолчанию, чтобы первый запуск не падал на пустом
app.option.get; - Для сериализованного JSON всегда оборачивайте разбор в try/catch — данные могли быть записаны старой версией.
Сценарий: настройки коннектора
Рассмотрим типовое тиражное приложение — коннектор к внешнему сервису. Ему нужно хранить ключ доступа, выбранную воронку и персональный режим отображения у каждого сотрудника. Здесь пригодятся оба вида опций.
| Данные | Где хранить | Метод |
|---|---|---|
| Ключ внешнего API | Общая опция | app.option.set |
| Воронка по умолчанию | Общая опция | app.option.set |
| Режим списка у сотрудника | Пользовательская | user.option.set |
Порядок работы простой: на странице настроек администратор сохраняет ключ и воронку в app.option, а каждый пользователь при первом открытии встройки получает значения по умолчанию, которые затем переопределяет в user.option. Обработчик встройки читает обе группы одним пакетом методом batch, чтобы не делать два последовательных запроса.
Если позже понадобится история изменений ключа или журнал синхронизаций, эти данные уже не помещаются в опции — их выносят в entity storage или во внешнюю БД, оставляя в опциях только текущее рабочее значение.
Итог
Встроенное хранилище опций Битрикс24 закрывает большинство потребностей приложения в конфигурации без собственной инфраструктуры: app.option — для общих настроек, user.option — для персональных. Помните про строковый формат, ограничение объёма и отсутствие выборок, а для данных переходите на entity storage или свою БД.
Мы проектируем слой хранения под конкретное приложение: где хватит опций, где нужна собственная сущность, а где — внешняя база с синхронизацией через REST. Такой подход экономит ресурсы и защищает вас от упирания в лимиты платформы при росте нагрузки.
Частые вопросы
Чем app.option отличается от user.option?
app.option хранит настройки для всего приложения на портале и виден всем пользователям, а user.option привязывает данные к конкретному пользователю. Первый — для общей конфигурации, второй — для персональных предпочтений.
Можно ли хранить в опциях массив или объект?
Напрямую нет, значения хранятся как строки. Сериализуйте структуру через JSON.stringify при записи и разбирайте при чтении, оборачивая парсинг в обработку ошибок.
Сколько данных можно положить в app.option?
Хранилище рассчитано на компактную конфигурацию, а не на объёмные данные. Для сотен килобайт и структурированных записей используйте entity storage или собственную базу.
Что происходит с опциями при удалении приложения?
Они удаляются вместе с приложением. Если данные должны пережить переустановку, храните их на своём сервере, а на портале держите только идентификаторы.
Безопасно ли хранить в app.option ключи API?
app.option доступен всем пользователям приложения через REST, поэтому чувствительные секреты лучше держать на своём backend. На портале оставляйте только некритичные идентификаторы.
Можно ли фильтровать записи по значению опции?
Нет, выборок и индексов у опций нет. Вы читаете все значения и фильтруете на своей стороне. Если нужна фильтрация, переходите на entity storage.
Как задать настройки по умолчанию?
Запишите значения при установке приложения в обработчике ONAPPINSTALL. Тогда первый вызов app.option.get вернёт корректные данные, а не пустоту.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.