назад
Разработка приложения для Битрикс24 от А до Я. Часть 1 - определяем задачи и действия
Мы уже больше года рассказываем о приложениях для Битрикс24. Наши эксперты изучили и подготовили обзоры более 130 приложений! Если вы еще не видели эти обзоры, крайне рекомендуем ознакомиться, наверняка вы найдете для себя что-то интересное. Все обзоры приложений собраны тут. Сегодня мы решили копнуть глубже и рассказать не просто про готовые приложения, а про процесс разработки приложений для Битрикс24. Наша команда регулярно создает приложения, которые помогают решать различные задачи клиентов, так что нам есть, что рассказать.
Руководитель отдела веб-разработки - Вадим Солуянов согласился поделиться своим бесценным опытом разработки приложений для интеграции сторонних сервисов с Битрикс24. Так как материал получился очень объемным, мы разделим его на 4 части, поэтому рекомендуем подписаться на нас в социальных сетях, чтобы ничего не пропустить. Описание работы над приложением будет вестись от лица Вадима. Итак, поехали!
С чего начинается приложение?
Моя задача при написании данного текста - обобщить опыт разработки интеграций портала Битрикс24 со сторонними сервисами, выделить в приложениях и работе над ними общие моменты, функционал, необходимый любому приложению, чтобы считать его хорошо написанным. Вероятно, нет хороших приложений и плохих исключительно по причине широты выполняемых ими задач. Даже при работе над маленьким можно проявить все свои таланты и написать все грамотно, ничего не упустив. Так, что в дальнейшем и вы сами, и другие разработчики не смогут ни к чему придраться и сказать, что это так себе приложеньице.
Из сказанного получается, что в качестве примера можно взять простую задачу и на ней провести анализ самого процесса разработки, составных частей программы, выполняемых подзадач, необходимых для ее эксплуатации в дальнейшем. В качестве такого примера я возьму интеграцию СМС-провайдера с порталом Битрикс24. В голове я при этом буду удерживать конкретное приложение, конкретную интеграцию, подглядывать в его логи и код, но для общего анализа совсем не важно, чего с чем оно действительно интегрирует.
Еще немного о приложении. Существует несколько способов работы с порталом Битрикс24. Здесь речь пойдет о приложении с пользовательским интерфейсом и размещаемом на стороннем сервере. Таким образом, в интеграции будет участвовать как минимум три сервера: портала, нашего приложения и СМС-провайдера.
Итак, поставлю задачу.
СМС-провайдер предоставляет API для отправки СМС-ок, отслеживания текущего статуса конкретного СМС-сообщения, получения сведений об аккаунте и текущем балансе пользователя. С другой стороны, портал Битрикс24 имеет API для регистрации СМС-провайдера, смены статуса отправленного сообщения, а также дает зарегистрированному провайдеру команду на отправку конкретного СМС. Наша задача связать одно с другим так, чтобы, например, при смене статуса у сделки в CRM кому-то отправлялось СМС-уведомление, а при изменении его статуса у СМС-провайдера менялся соответственно статус сообщения на портале.
Выделим подзадачи из этой общей. В итоге получим такие точки входа в приложение:
- install - установка приложения,
- settings - настройка его параметров,
- handler - обработка команд на отправку СМС,
- task - периодическая проверка статуса СМС,
- statistic - сбор статистики по работе и ошибкам приложения.
Во-первых, установка. В принципе, Битрикс24 не требует подобной точки входа, приложение будет установлено и без нее, но было бы неплохо регистрировать где-то у себя сам факт установки. В дальнейшем появится и еще одна тому причина, но пока довольно и одной. При установке необходимо где-то зафиксировать, что на таком-то портале было установлено наше приложение в такой-то день и т.п. Сразу следует отметить одну особенность Битрикс24: на данную точку входа портал постучит не только при установке приложения, но и при обновлении с версии на версию. Поэтому, регистрируя факт установки, нам потребуется отличить первую установку от обновлений. Сделать это элементарно по наличию у нас записи об установке: если она есть, значит произошло обновление, если нет - установка. Отмечу также, что установка - это страница с пользовательским интерфейсом. Она может содержать какую-то информацию, а может лишь вызывать метод js-библиотеки, предоставляемой Битрикс24, который фиксирует факт установки. Допустим, что у нас будет лишь этот вызов: BX24.installFinish(). После чего портал перенаправит пользователя на основную страницу приложения, т.е в настройки.
Теперь настройки. В данном приложении они совершенно необходимы, поскольку для взаимодействия с СМС-провайдером нам потребуются авторизационные данные. Это может быть т.н. API Key или логин и пароль или, как предпочитают делать в последнее время, логин и API Key вместо пароля. Эти данные мы можем получить лишь от самого пользователя, установившего приложение. Отмечу сразу, что для нашей задачи не требуется спрашивать ключи от каждого пользователя портала, одной авторизации будет достаточно. Итак, необходимо вывести на странице форму с полями ввода, в которых указать текущие значения, если они уже есть. Будет также неплохо дать возможность здесь же сразу проверить их валидность, предоставив возможность отправки тестового СМС-сообщения.
Обработчик. При описании настроек я забыл упомянуть еще об одном, спрятанном в backend действии в случае, когда авторизационные данные первый раз получены и проверены на валидность. Это регистрация на портале СМС-провайдера. При его регистрации мы указываем среди прочего URL обработчика команды на отправку сообщения. И в данной точке входа (handler) мы получаем набор параметров, среди которых есть само сообщение, а также номер телефона, на который оно должно быть отправлено. Задача обработчика постучать с этими данными (используя авторизацию, сохраненную в настройках) к СМС-провайдеру, вызывая некий его метод send и получая ответ об успешной или неудачной постановке в очередь на отправку. Когда она успешна, то нам вернется уникальный идентификатор сообщения у провайдера.
Проверка статуса. Еще одно упущение в описании. Чтобы проверять статус доставки нам в обработчике необходимо где-то у себя фиксировать факт отправки вместе со всеми данными, которые нам потребуются, чтобы узнать текущий статус и, если он изменился, передать его на портал. И тут всплывает еще одна недоделка. Чтобы выполнить что-либо на портале, нам необходим access_token - авторизационный ключ, который подтвердит наши права на запрашиваемое действие. Когда портал стучится на такие точки входа как install, settings, handler, то в самом запросе присылает нам авторизационные данные того пользователя, что зашел в приложение, но в данном случае проверка запускается без кого-либо, через cron сервера, где расположено приложение. Получается, что нам необходимо еще и хранить где-то авторизационные данные пользователя. Авторизацию СМС-провайдера мы сохраняли в настройках, а авторизацию портала можно, конечно, хранить вместе с данными о сообщении, но все-таки лучше их вынести куда-то отдельно в привязке к порталу и пользователю на нем. Почему лучше? Это станет понятнее, когда речь зайдет о refresh_token'е.
Статистика. Если мы хотим не просто написать приложуху, выложить в открытый доступ и забыть о ее существовании, то нам потребуется собирать статистику. Во-первых, для того, чтобы видеть насколько востребовано приложение, во-вторых, для технической поддержки. Под статистикой я подразумеваю два хранилища данных: лог приложения, в котором фиксируются действия и данные в ключевых точках программы, фиксируются факты установки, удаления, успешной/неудачной отправки/доставки, ошибки и собственно статистика - собранные за день и сложенные в одну цифру интересующие нас факты... Упс. Удаление... Придется внести правки в изначальный список точек входа. Теперь он будет выглядеть так:
- install,
- settings,
- handler,
- event_handler - обработка событий портала,
- task,
- statistic.
Появилась еще одна - обработчик событий. Факт удаления нашего приложения мы можем узнать лишь подписавшись в портале на событие OnAppUninstall. Когда оно произойдет, портал стукнется на тот URL, что мы указали при подписке. Помимо того, что мы зафиксируем факт удаления, мы еще и почистим все хранилища (за исключением логов и статистики) от записей, привязанных к данному порталу, поскольку от них больше никакого проку.
Ну, вот теперь все точки входа в наше приложение вкратце описаны, выяснены действия, какие необходимо выполнить, и данные, которые необходимо где-то у себя хранить. Было бы неплохо их еще раз перечислить отдельно от описания точек входа. Итак:
Действия
- При установке подписаться на событие OnAppUninstall.
- Зафиксировать факт установки или обновления в логах.
- Сделать где-то запись о портале, на котором произошла установка, чтобы в дальнейшем мы могли отличать установку от обновления.
- Получить текущие данные по авторизации из хранилища, если есть, и вывести в виде формы пользователю.
- Проверить новые авторизационные данные и, если они валидны, сохранить у себя.
- При первом получении валидных данных зарегистрировать на портале СМС-провайдер.
- В случае получения невалидных данных вывести пользователю сообщение об этом.
- При получении запроса на отправку тестового СМС выполнить отправку.
- После отправки тестового СМС вывести пользователю результат отправки.
- В hanlder при получении запроса выполнить отправку.
- При отправке запомнить все необходимые данные для дальнейшей проверки статуса.
- При получении уведомления об удалении приложения (OnAppUninstall) зафиксировать данный факт в логах и очистить хранилище от записей, связанных с данным порталом, за исключением логов и статистики.
- Периодически проверять статусы отправленных сообщений. Например, раз в 10 минут.
- Раз в сутки запускать сбор статистики, суммируя факты интересующих событий, произошедших за предыдущие сутки.
- Раз в сутки очищать хранилище от: 1) логов, старее времени, в течение которого мы их собираемся хранить (надо заметить что в требованиях к приложениям Битрикс24 указывает на обязательное хранение rest-запросов к порталу в течение 3 суток); 2) данных о сообщениях, которые были успешно/неудачно доставлены, т.е. уже не требующие дальнейшей проверки статуса (их мы храним какое-то время на случай, если они потребуются для техподдержки).
Данные
- Сведения о портале.
DOMAIN - доменное имя портала
MEMBER_ID - уникальный идентификатор портала на сервере авторизации
LICENSE_TYPE - тип лицензии (напр., чтобы знать бесплатники пользуются или не только)
... - другие интересующие о портале данные
DATE_INSTALL - дата установки приложения
DATE_UPDATE - дата обновления версии приложения
VERSION - текущая установленная версия -
Логирование.
DOMAIN - домен портала (все-таки при техподдержке с ним работать удобнее)
MEMBER_ID - идентификатор портала (домен может быть переименован, но id - нет)
EVENT_TYPE - тип события (напр., факт установки - INSTALL)
EVENT_DATA - любые интересующие данные в виде текста
DATE_CREATE - дата и время события в понятном человеку написании
DATE_POINT - дата, время и миллисекунды для сортировки и получения точной последовательности событий (просто DATE_CREATE для этого не хватит, поскольку за одну секунду может произойти несколько событий) -
Хранение авторизации СМС-провайдера
Для простоты добавим поля к п.1 в те самые другие поля
API_LOGIN - логин у СМС-провайдера
API_KEY - АПИ ключ -
Отправленные сообщения
DOMAIN
MEMBER_ID
BX_USER_ID - униальный в рамках портала id пользователя
MESSAGE_ID - идентификатор сообщения на портале
EXT_MESSAGE_ID - идентификатор на стороне СМС-провайдера
STATUS - текущий статус у СМС-провайдера
DATE_CREATE - дата создания записи
DATE_UPDATE - дата обновления записи
VERSION - версия приложения -
Авторизация пользователя портала
DOMAIN
MEMBER_ID
BX_USER_ID - униальный в рамках портала id пользователя
ACCESS_TOKEN - собственно, тот токен, с которым будем стучаться на портал
REFRESH_TOKEN - токен для обновления access_token
REFRESH_DATE_END - последняя дата-время валидности refresh_token
VERSION - версия приложения -
Статистика
DOMAIN
MEMBER_ID
EVENT_TYPE - тип события
DAY_VALUE - количество событий за день
DATE_CREATE - дата, на которую собрана статистика
Хранилище данных требует пояснений. Например, почему всюду дублируется домен и id портала. Ну.., домен, потому что так удобнее просматривать и фильтровать записи при осуществлении технической поддержки, а MEMBER_ID... можно, конечно, привязку сделать по первичному ключу с данными из п.1 (Сведения о портале). Но и выборки придется делать всегда с джойном двух таблиц... Короче, я выбираю именно вариант с id портала в каждой таблице. Когда мы работаем с порталом, то у нас в наличии всегда именно member_id, он приходит с портала, и его же мы посылаем самим себе при обращении с фронта в бэк.
Далее VERSION. Зачем она нужна в сообщениях и пользователях? Все дело в версиях приложений Битрикс24. При установке приложения (такого, как наше) на портале лишь создается где-то запись об установке, запоминаются URL-ы к приложению и все. Таким образом, на разных порталах могут размещаться самые разные версии одного приложения. И, если при создании новой, вы создаете еще один экземпляр, при этом меняется URL, то вы вынуждены сохранять и экземпляр предыдущей версии, поскольку обновление приложения на портале не происходит автоматически. Он лишь сообщает о выходе новой версии, но только пользователь может дать команду на обновление. Создавать отдельные хранилища под каждую версию - это, конечно, идиотизм, который при смене версии приведет к необходимости перетаскивать данные из одного в другое. Таким образом, хранилище для всех версий одно и то же. Но что, если в новой версии вы добавили не существовавший ранее функционал и поля данных под него, а старая версия ничего о нем и них не знает? Она запустит обработку очереди сообщений и обработает и те, что были созданы уже новой версией, без дополнительного нового функционала. Вот для этого и VERSION, чтобы каждая версия занималась только своими данными.
И еще одно важное замечание по поводу версий. Во всех местах программы, где вы указываете путь к приложению, а это URL обработчика событий, это URL для атрибута action формы настроек, это URL отправки тестового СМС из фронта в бэк, всюду URL должен формироваться динамически, исходя из текущего расположения приложения. Иначе при выпуске новой версии вам придется лазить по всему коду и заменять. Даже, если вынесете эти URL-ы в конфигурационный файл, всегда можно что-то пропустить. Динамическое формирование URL-ов самое правильное.
Теперь REFRESH_DATE_END в таблице пользователей. Токен, с которым мы стучимся на портал, живет лишь один час, а затем требует обновления через refresh_token, но у того самого (пока еще) есть собственный lifetime размером в 30 дней. Чтобы не потерять возможность делать запросы от лица каждого пользователя, мы обязаны отслеживать момент окончания валидности и делать обновление. По данному полю мы определяем такую необходимость. Вот поэтому я и вынес авторизацию пользователей в отдельное хранилище, поскольку по нему придется периодически пробегать, обновляя токены. Ну и с точки зрения построения баз данных это правильнее. И еще замечание по токенам. Если приложение размещается не на вашем сервере, а может, даже и в этом случае, токены следует хранить в зашифрованном виде.
Итак, после перечисления всех данных мы обнаруживаем, что список наших действий необходимо дополнить пунктом 16.
16. Обновление refresh_token-ов, у которых срок жизни приближается к 30 дням, раз в сутки.
Ну вот, теперь и действия все прописаны и данные описаны. Можно переходить к следующему шагу и рассмотреть каждую точку входа подробнее. Примечание, я не стану говорить об архитектуре приложения, поскольку тут многое зависит и от языка программирования, и от сложившейся практики у конкретных разработчиков. Речь только о построении приложения без специфических языковых особенностей.
Продолжение следует...
