Просмотров: 38066
Дата последнего изменения: 25.01.2024
Сложность урока:
4 уровень - сложно, требуется сосредоточиться, внимание деталям и точному следованию инструкции.
1
2
3
4
5
Универсальный механизм отправки сообщений
Битрикс24 умеет отправлять SMS не только из бизнес-процессов и роботов CRM, но и из карточки CRM (которая доступна везде, включая бесплатный тариф без бизнес-процессов). Для решения этой задачи есть соответствующий специальный REST для служб сообщений. В первую очередь его используют для интеграции с SMS, но вообще это универсальный механизм и в дальнейшем его можно использовать для отправки сообщений в произвольные источники.
Авторам интеграций с SMS-провайдерами рекомендуется перевести свои приложения на новый REST, чтобы у пользователей не было проблем с установкой на бесплатном тарифе. И, несмотря на прозрачность вызовов существующих провайдеров для бизнес-процессов и роботов CRM, лучше работать с методами REST для службы сообщений. Тем более, что только эти методы позволят не только отправлять SMS, но и сообщать Битрикс24 о статусе отправленных сообщений. Этот статус пользователи видят прямо в карточке CRM (а в будущем увидят и в отчетах инструментов CRM-маркетинга).
Рассмотрим практический пример того, как можно быстро сделать интеграцию с SMS-провайдером.
Внимание! Данный пример работает на основе SDK CRest. Перед использованием примера необходимо открыть через браузер файл checkserver.php и проверить корректность настроек вашего сервера. Для реального тиражного приложения необходимо пронаследовать класс CRest, переопределив методы getSettingData/setSettingData, которые занимается получением/сохранением токенов авторизации в текстовый файл. Эти методы не предназначены для эксплуатации приложения на нескольких Битрикс24 одновременно. Подробнее.
Скачать архив примера:
Для начала
Чтобы стать технологическим партнером 1С-Битрикс, достаточно заполнить анкету: указать общую информацию, а также данные для дальнейшей авторизации в партнерском кабинете.
Обратите внимание на поле Код партнера - это префикс, который будет подставляться в дальнейшем в символьный код, идентифицирующий ваши решения в нашем каталоге. Если взять в качестве примера решение по интеграции со Stripe https://www.bitrix24.ru/apps/?app=integrations24ru.stripe, то integrations24ru является как раз этим кодом партнера (разработчика решения), а код stripe является кодом конкретного решения, который вы укажите в дальнейшем при заполнении формы регистрации решения.
Поэтому желательно, чтобы код партнера был связан с названием вашей компании или продукта. Поменять его потом не получится, отнеситесь к его формированию вдумчиво и ответственно.
После заполнения анкеты вы сразу получите доступ в кабинет разработчика решений. Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Битрикс24.Маркет, необходимо открыть
Добавить приложение
, далее выбрать регион публикации. В открывшейся форме необходимо
выбрать или добавить
версию приложения:
Заполните доступные разделы системы (1) для данного примера значением "Сервис сообщений". Битрикс24 в этом случае будет сам вызывать наш провайдер из нужных точек в интерфейсе: из бизнес-процессов, из роботов CRM, из карточки CRM и так далее. Ознакомьтесь с правилами публикации (2). Это необходимо для понимая требований, которые накладываются на тиражные решения.
В отличие от локальных приложений, тиражные решения состоят из версий. Каждая версия в дальнейшем подается на модерацию. (При модерации версии проверяется и карточка приложения). На этапе разработки и тестирования модерация не нужна, вы сами занимаетесь разработкой и доведением своего решения до полнофункционального состояния, включая
тестовые установки
на своих Битрикс24, и только потом подаете решение на модерацию.
После добавления версии приложения необходимо заполнить название (1) код приложения (2), категории (3), описание приложения (4), ценовую политику (5) и протестировать (6):
Описание обязательных полей (Нажмите на плюсик)
Смысл части обязательных полей понятен из названия, поясним то, что может вызвать затруднения.
В отличие от локальных приложений, у каждого тиражного решения необходимо задать уникальный символьный код. Код состоит из двух частей: вашего уникального символьного кода партнера (указывается в партнерской карточке) и части, которую вы присваиваете конкретному создаваемому приложению (2 на рис. выше).
Примечание: с самого начала задавайте вменяемые значения кода. Именно этот символьный код в дальнейшем будет присутствовать в публичном адресе вашего решения в каталоге Битрикс24.Маркет и заменить его в дальнейшем уже не получится.
Для простоты стоит указать, что приложение бесплатное (5). Перед подачей на модерацию вы сможете поменять этот и другие описательные параметры своего приложения.
Заполните описание решения на необходимых языках (4) и заполните обязательные поля с описаниями, а также прикрепить логотип решения и хотя бы один скриншот. На этапе разработки не обязательно вносить реальные и подробные описания, а также реальные скриншоты приложения. Но в дальнейшем, когда вы решите подавать готовое отлаженное решение на модерацию для публикации в каталоге, эти поля необходимо будет заполнить актуальной и полной информацией.
Можно сразу привязать его к нужной категории решений (3). Эти категории служат для навигации пользователей по
каталогу решений
.
Про URL приложения
Прежде, чем заполнять форму новой версии, обратимся к архиву с примером. В архиве - несколько файлов, которые в целом показывают возможную архитектуру интеграции с SMS-провайдером. Распакуйте этот архив на своем веб-сервере, который доступен из WWW и на котором установлен нормальный SSL. (Без SSL не приходится говорить ни о каком тиражном решении для каталога Битрикс24.Маркет.) Допустим, скрипты примера доступны по адресу https://mydomain.ru/sms/. В этом случае:
в поле Установочное приложение устанавливаем https://mydomain.ru/sms/install.php. Данный скрипт вызывается и выводится во фрейме в интерфейсе Битрикс24 один раз, когда пользователь будет устанавливать решение. Здесь, как правило, реализуют сценарии предварительной настройки или подключения к внешним сервисам.
Сохраните карточку приложения, заполнив все необходимые поля. Первый шаг сделан - фактически, вы подготовили описательную часть вашего будущего приложения. Теперь необходимо сформировать ту часть, которая отвечает за техническую реализацию.
Общая логика приложения
Приложение регистрирует в конкретном Битрикс24 некий обработчик. Когда пользователь (или автоматический процесс) на стороне Битрикс24 хочет отправить SMS, он дергает этот обработчик и передает в него текст и номер телефона получателя. Обработчик (зная параметры вызова API SMS-оператора) отправляет SMS. Вот такая простая схема:
В нашем примере, скрипт install.php запросит у пользователя параметры для подключения API SMS-оператора и сохраняет их на своей стороне в привязке к конкретному Битрикс24. В таблице БД, например. Этот же скрипт регистрирует так называемый "провайдер сообщений" в Битрикс24, обращаясь к соответствующему методу REST. Фактически, это и будет регистрацией обработчика, который реализуется в примере в файле handler.php по адресу https://mydomain.ru/sms/handler.php. Если регистрация прошла успешно, install.php должен завершить установку.
В дальнейшем приложение ожидает, когда Битрикс24 обратится к нему:
Обращение произойдет, если пользователь, допустим, решит отправить SMS из карточки CRM. В этом случае, handler.php получит целую кучу данных в массиве $_REQUEST:
внутренний идентификатор сообщения message_id, который потребуется для того, чтобы в дальнейшем отдельно сообщать в Битрикс24 о статусе доставки,
параметры авторизации в массиве auth для работы с REST Битрикс24.
Обработчик, получив данные о сообщении, должен:
обратиться к API SMS провайдера, чтобы отправить сообщение,
запомнить id-сообщения и привязку к конкретному Битрикс24 где-то у себя в некой очереди.
Можно и не запоминать, но тогда приложение не сможет во всей полноте реализовать хорошие пользовательские сценарии. Так как статус доставки SMS-сообщения становится известным только через некоторое время (иногда это могут быть часы), мы не сможем прямо из handler.php тут же сообщить в Битрикс24 о результате доставки. Приложению придется делать это отдельно, и для этого в архиве примера есть файл statuses.php. Подразумевается, что какой-то менеджер заданий обращается к этому файлу с некой периодичностью и этот скрипт «смотрит» на очередь отправленных SMS и по каждому из них пытается узнать статус доставки, обращаясь к API SMS-провайдера:
О результатах он сообщает в Битрикс24, и удаляет из очереди обработанные сообщения.
Отладка
Для тестирования приложения, необходимо открыть
Тестировать в версии приложения
или
Протестировать в приложении
:
После нажатия "Установить" откроется указанный Битрикс24 на странице установки приложения.
Установите приложение
.
При установке в интерфейсе Битрикс24 будет вызван install.php, который выведет интерфейс для ввода некого ключа API. В зависимости от конкретного SMS-провайдера параметры авторизации будут отличаться, так что в своем приложении интерфейс вам нужно будет подзаточить под конкретный случай.
Нажмите “Save”, приложение будет считаться установленным (о техническом завершении - ниже), и Битрикс24 автоматически откроет уже основной интерфейс приложения index.php. В архиве примера этот интерфейс не сильно отличается от интерфейса установки и должен «подхватывать» сохраненные параметры авторизации SMS-провайдера. Но, поскольку это просто «заготовка» для приложения, а не работающая интеграция с конкретным провайдером, то мы увидим просто форму для ввода ключа.
Волшебный код
Начнем с install.php. Когда Битрикс24 показывает во фрейме скрипт приложения (это касается как скрипта установки, так и основного скрипта приложения), то он передает в массив $_REQUEST все необходимые для OAuth 2.0 параметры авторизации. Следовательно, мы их можем схватить и сохранить на стороне приложения для дальнейшего использования. Именно это и происходит в коде при формировании hidden-полей:
Далее, мы делаем обработчик onsubmit, который позволит перехватить нажатие на кнопку "Save".
$('#sms-settings').submit(function(e){
e.preventDefault();
// 1. сохраняем данные авторизации на стороне приложения, чтобы в
// дальнейшем использовать их для отправки смс
// 2. прописываем обработчик для провайдера
var params = {
CODE: 'fastsms',
TYPE: 'SMS',
HANDLER: 'https://mydomain.ru/sms/handler.php',
NAME: 'Provider FastSms',
DESCRIPTION: 'Description sms provider'
};
BX24.callMethod(
'messageservice.sender.add',
params,
function(result)
{
if(result.error())
{
alert("Error: " + result.error());
}
else
{
// Обработчик для провайдера прописан успешно
// 3. заканчиваем процедуру установки на стороне Битрикс24
BX24.installFinish();
}
}
);
});
В этом обработчике можно прописать свой механизм сохранения нужных параметров. А далее зарегистрируйте тот самый обработчик, обращаясь для этого к методу messageservice.sender.add. Если регистрация прошла успешно, мы вызываем метод installFinish, который сообщает Битрикс24 об успешном завершении установки.
Обратите внимание, что мы в данном случае обращаемся к REST Битрикс24 из JavaScript как для добавления провайдера сообщений, так и для завершения процедуры установки. Со статусами сообщений мы в дальнейшем будем работать, обращаясь к REST API из PHP.
В index.php все то же самое, та же форма настроек, та же обработка события onsubmit, в которой вам придется писать свой код сохранения настроек и параметров авторизации. Но тут уже нет никакого installFinish, потому что приложение уже установлено:
$('#sms-settings').submit(function(e){
e.preventDefault();
// сохраняем данные авторизации на стороне приложения, чтобы в
// дальнейшем использовать их для отправки смс
});
Код в handler.php. В примере просто сохраняется то, что нам передает Битрикс24 в лог:
Но вы можете здесь обращаться к API провайдера SMS, инициируя отправку SMS теми средствами, которые вам предоставит оператор. Пример содержимого массива $_REQUEST есть выше.
Самое сложое находится в файле statuses.php. Подразумевается, что этот файл будет вызываться с некой периодичностью и он должен уметь обращаться к некой очереди, которую вы должны сделать самостоятельно. И получая из этой очереди информацию об отправленных SMS-сообщениях, он должен дергать API SMS-провайдера, получать от него статус доставки и передавать его обратно в Битрикс24. Для этого придется в очереди запоминать как ID-сообщения, который присылает Битрикс24, так и соответствующий ему ID-сообщения на стороне SMS-оператора. Посмотрим на код:
require_once(__DIR__ . '/crest.php');
/**
* message_id полученный в handler.php
*/
$messageId = '520108d3dabbe6e98586549f467cab8d';
/**
* sms status: delivered, undelivered, failed
*/
$status = 'delivered';
$result = CRest::call(
'messageservice.message.status.update',
[
'CODE' => 'fastsms',
'message_id' => $messageId,
'status' => $status,
]
);
echo "<pre>"; print_r($result); echo "</pre>";
if (isset($result['error'])) {
// что-то пошло не так, анализируем ошибку и реагируем на нее
}
Представим, что на каждом шаге цикла обработки очереди мы получили из очереди $messageId , потом вытащили оттуда же название домена Битрикс24 и токены, которые передадим в getSettingData/setSettingData переопределив методы для работы с несколькими Битрикс24. Домен и access_token нам нужны, чтобы обратиться к REST Битрикс24. Это простой HTTP-запрос, в котором указывается домен Битрикс, название нужного метода (в нашем случае это метод messageservice.message.status.update для обновления статуса доставки), параметры метода и токен авторизации access_token.
Для автоматического продления токенов необходимо заполнить константы: C_REST_CLIENT_ID (1) и C_REST_CLIENT_SECRET (2). Значения для
этих констант
Такая пара ключей действует на всех Битрикс24, на которых потом будет устанавливаться ваше приложение.
вам нужно взять из карточки приложения:
Используйте функцию CRest::call(). Она получает название нужного метода REST, параметры для этого метода и токены авторизации из методов getSettingData/setSettingData.
Используйте стандартную заготовку в виде архива примера, адаптируйте к реальному оператору SMS и публикуйте решения в каталоге Битрикс24.Маркет.