Справочник JS API
Пользователи могут использовать JavaScript API для решения следующих задач:
Для реализации дополнительных возможностей на сайте:
-
открытие форм связи онлайн-консультанта (чат, заявка) из любого места сайта пользователя. Получение дополнительной информации о посетителях сайта;
-
открытие формы и заказ обратного звонка через сайтфон;
-
присвоение свойств (например, посетителю, открывшему личный кабинет, присвоено свойство “действующий клиент”, открывшему тарифы - “потенциальный” и т.д.).
Получение дополнительных данных в отчетах:
-
данные о любом пользовательском событии на сайте (чтение книги, просмотр тарифов, открытие личного кабинете и т.д);
-
информация с любой формы заявки пользователя.
Работа с событиями
Отправка пользовательского события
Для отправки пользовательского события используется следующий метод:
Comagic.trackEvent(category, action, name, value);
Параметры:
Название | Тип | Описание |
---|---|---|
category | text | категория, обязательный параметр |
action | text | действие, обязательный параметр |
name | text | ярлык, необязательный параметр |
value | text | значение, необязательный параметр |
Пример использования:
Comagic.trackEvent('Offer', 'DownloadBook', 'CallTrackingBook', 'value');
Работа с баннером
Проверка наличия операторов онлайн
Для проверки наличия операторов онлайн используется метод:
Comagic.getOperatorStatus();
Метод возвращает true
, если есть хотя бы один доступный оператор, иначе false
.
Форма заявки
Для открытия формы заявки используется метод:
Comagic.openSiteRequestPanel();
Пользовательская форма заявки
Данные, полученные при использовании пользовательской формы заявки на сайте, можно отправить с помощью следующего метода:
Comagic.addOfflineRequest(req, callback);
Пользоваться данным методом можно лишь в случае отправки формы способом, не приводящим к перезагрузке страницы! Для остальных ситуаций есть альтернативный метод.
Параметры:
Название | Тип | Описание |
---|---|---|
req | object | Параметры заявки |
callback | Функция одного аргумента, которая будет вызвана после того, как сервер пришлет результат сохранения формы. Необязательный параметр. Например function(o) {console.log(o);}
|
Параметры req:
Название | Тип | Описание |
---|---|---|
name |
text | имя посетителя |
email |
text | адрес электронной почты посетителя |
phone |
text | телефон посетителя |
message |
text | текст заявки и остальная информация, для которой нет отдельного поля
|
is_sale |
boolean |
true - если это продажа; false - если не продажа (по умолчанию) |
group_id |
integer | id группы, в которую должна быть передана заявка |
sale_cost |
text | сумма сделки. Если необходимо передать сумму сделки, то обязательно надо передать в параметре is_sale значение true
|
form_name |
text | имя пользовательской заявки |
user_fields |
object | Пользовательские поля заявки |
Примеры:
- Обычная заявка:
Comagic.addOfflineRequest({
name: 'Дмитрий',
email: 'dmitry@comagic.ru',
phone: '79123456789',
message: 'Текст заявки...',
group_id: 1234
});
- Заявка, приведшая к продаже:
Comagic.addOfflineRequest({
name: 'Дмитрий',
email: 'dmitry@comagic.ru',
phone: '79123456789',
message: 'Онлайн заказ...',
is_sale: true,
sale_cost: '9999'
});
- Заявка переданная через определенную форму с передаче доп.параметров
Comagic.addOfflineRequest({
name: 'Дмитрий',
email: 'dmitry@comagic.ru',
phone: '79123456789',
message: 'Онлайн заказ...',
is_sale: true,
sale_cost: '9999',
form_name: 'Тестовая форма',
user_fields: {
"KvartiriMoscow": "Трешка",
"NomeraKvartirvMoscow": "10"
}
});
- Заявка с использованием параметра callback:
Comagic.addOfflineRequest({
"name": "My Name Is"
}, function(o) {console.log(o);
});
после успешного сохранения заявки в консоль браузера будет выведен результат:
Object {success: true, result: null}
Альтернативный способ отправки пользовательской заявки
- Перед отправкой заявки нужно получить аутентификационные данные виджета, используя метод JS API
Comagic.getCredentials()
. Метод возвращает объект:
{
"site_key": "VcB4qqpO1WPSopO670cAbXwAH9Ryaw75",
"key": "u8N4wqLtywFKSaxGOUCreGKD0zglE2s0",
"uri": "https://server.comagic.ru/",
"visitor_id": 17258569,
"hit_id": 546833568748,
"session_id": 255544855,
"consultant_server_url": "https://server.comagic.ru/" //базовая часть URL
}
- Передать полученные данные вместе с остальным данными формы.
- В серверном обработчике заявки сделать HTTP-запрос к сервису для добавления заявки.
Базовую часть URL жестко прописывать нельзя. Ее необходимо взять из данных п.1. Она может меняться.
POST https://server.comagic.ru/api/add_offline_message/
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Form Data //данные отформатированы для наглядности
key=u8N4wqLtywFKSaxGOUCreGKD0zglE2s0
&uri=https://server.comagic.ru/
&visitor_id=17258569
&hit_id=546833568748
&session_id=255544855
&name=John Smith
&email=no@email.adr
&phone=+79251234567
&text=Hello, world!
&is_sale=true
&sale_cost=10000
В ответ придет флаг успешности добавления заявки (application/json
):
{
"success": true
}
Пример использования альтернативного способа отправки пользовательской заявки
Вариант с перезагрузкой страницы
Будем исходить из того, что на сайте уже установлен код вставки, подключена библиотека jQuery и есть форма обратной связи. Код простейшей формы обратной связи выглядит, примерно, так:
<form id='myform' action="/send.php" method="POST">
<input type="text" name='name' value='' placeholder="Введите имя" /><br>
<input type="text" name='phone' value='' placeholder="Введите номер телефона" /><br>
<input type="text" name='email' value='' placeholder="Введите e-mail" /><br>
<textarea name="text"></textarea><br>
<input type='submit' />
</form>
Для того, чтобы отправить заявку, код формы нужно доработать: добавить служебные поля и обработчик на кнопку "Отправить":
<form id='myform' action="/send.php" method="POST">
<input type="text" name='name' value='' placeholder="Введите имя" /><br>
<input type="text" name='phone' value='' placeholder="Введите номер телефона" /><br>
<input type="text" name='email' value='' placeholder="Введите e-mail" /><br>
<textarea name="text"></textarea><br>
<input type='button' value='Отправить' onclick="formSubmit()"/>
<input type="hidden" name='key'/>
<input type="hidden" name='uri'/>
<input type="hidden" name='visitor_id'/>
<input type="hidden" name='hit_id'/>
<input type="hidden" name='session_id'/>
<input type="hidden" name='consultant_server_url'/>
</form>
В коде страницы или в отдельном JS-файле нужно написать функцию formSubmit()
, которая будет вызываться каждый раз при клике на кнопку "Отправить":
function formSubmit() {
var credentials = Comagic.getCredentials();
for (var field in credentials) {
if (credentials.hasOwnProperty(field)){
$('[name='+field+']').val(credentials[field]);
}
}
$('#myform').submit();
}
Этот код получает служебную информацию, сохраняет ее в невидимые служебные поля формы и отправляет форму на сервер.
Далее, нужно модифицировать код, который отвечает за обработку заявки на сервере. В нашем случае этот код находится в файле send.php:
<? /* Здесь код по умолчанию, связанный с обработкой заявки на серверной стороне. Например, отправка писем, или сохранение в базу данных. */ ?>
<?
$url = $_POST['consultant_server_url'].'api/add_offline_message/';
$data = array(
'key' => $_POST['key'], //Значение без изменений из служебного поля key
'uri' => $_POST['uri'], //Значение без изменений из служебного поля uri
'visitor_id' => $_POST['visitor_id'], //Значение без изменений из служебного поля visitor_id
'hit_id' => $_POST['hit_id'], //Значение без изменений из служебного поля hit_id
'session_id' => $_POST['session_id'], //Значение без изменений из служебного поля session_id
'name' => $_POST['name'], //Имя клиента
'email' => $_POST['email'], //E-mail
'phone' => $_POST['phone'], //Номер телефона
'text' => $_POST['text'], //Текст заявки
'is_sale' => true, //true, если это продажа
'sale_cost' => 10000 //Сумма сделки. Если нужно передать сумму сделки, то is_sale обязательно равно true
);
/* Если все поля в html-разметке формы называются так же, как этого требует CoMagic, можно написать "$data = $_POST".
В противном случае потребуются дополнительные преобразования. */
$options = array( 'http' =>
array(
'header' => "Content-type: application/x-www-form-urlencoded; charset=UTF-8",
'method' => "POST",
'content' => http_build_query($data)
)
);
print $options['http']['content'];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$resultArray = json_decode($result, true);
if ($result === false or $resultArray['success'] === false) {
/* Здесь могут быть действия на тот случай, если отправка заявки завершилась ошибкой. */
}
?>
Вариант с AJAX-запросом
HTML-разметка простейшей формы:
<form id='myform2'>
<input type="text" name='name' value='' placeholder="Введите имя" /><br>
<input type="text" name='phone' value='' placeholder="Введите номер телефона" /><br>
<input type="text" name='email' value='' placeholder="Введите e-mail" /><br>
<textarea name="text"></textarea><br>
<input type='button' value='Отправить' onclick="sendAjaxSubmit()"/>
</form>
JS-код отправки AJAX-запроса:
function sendAjaxSubmit() {
/* Здесь может быть проверка заполненных обязательных полей, валидация номера телефона и другие проверки. */
$.ajax({
url: 'sendAjax.php',
method: 'POST',
data: $('#myform2').serialize(),
complete: function(response) {
if (response.readyState === 4 && response.status === 200) {
alert(response.responseText);
}
},
})
}
PHP-код обработки полученного запроса:
<?
/* Код для обработки пришедших данных, сохранение в БД или отправка заявки на почту. */
$success = true; /* Переменная определяет, удалось ли сохранить заявку. */
if ($success) {
print 'Заявка успешно отправлена';
} else {
print 'Произошла непредвиденная ошибка';
}
?>
Для того, чтобы отправить заявку в случае отправки заявки AJAX-запросом, модифицировать HTML-форму не нужно. Нужно модифицировать JS-код таким образом, чтобы получение служебной информации происходило перед отправкой запроса:
function sendAjaxSubmit() {
/* Здесь может быть проверка заполненных обязательных полей, валидация номера телефона и
другие проверки. */
$.ajax({
url: '/sendAjax.php',
method: 'POST',
data: $('#myform2').serialize(),
complete: function(response) {
if (response.readyState === 4 && response.status === 200) {
alert(response.responseText);
}
},
beforeSend: function(jqXHR, settings) {
var credentials = Comagic.getCredentials();
settings.data += '&' + $.param(credentials);
}
})
}
Код, который нужно выполнить на сервере. В данном случае он находится в файле sendAjax.php:
<?
/* Здесь код по умолчанию, связанный с обработкой заявки на серверной стороне. Например, отправка писем, или сохранение в базу данных. */
?>
<?
$success = true; /* Проверка того, что все выполнено корректно. */
if ($success) {
$url = $_POST['consultant_server_url'].'api/add_offline_message/';
$data = array(
'key' => $_POST['key'], //Значение без изменений из служебного поля key
'uri' => $_POST['uri'], //Значение без изменений из служебного поля uri
'visitor_id' => $_POST['visitor_id'], //Значение без изменений из служебного поля visitor_id
'hit_id' => $_POST['hit_id'], //Значение без изменений из служебного поля hit_id
'session_id' => $_POST['session_id'], //Значение без изменений из служебного поля session_id
'name' => $_POST['name'], //Имя клиента
'email' => $_POST['email'], //E-mail
'phone' => $_POST['phone'], //Номер телефона
'text' => $_POST['text'], //Текст заявки
'is_sale' => true, //true, если это продажа
'sale_cost' => 10000 //Сумма сделки. Если нужно передать сумму сделки, то is_sale обязательно равно true
);
/* Если все поля в html-разметке формы называются так же как этого требует comagic, можно написать "$data = $_POST".
В противном случае потребуются дополнительные преобразования. */
$options = array(
'http' => array(
'header' => "Content-type: application/x-www-form-urlencoded; charset=UTF-8",
'method' => "POST",
'content' => http_build_query($data)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$resultArray = json_decode($result, true);
if ($result === false or $resultArray['success' === false]) {
/* Обработка случая, если отправка заявки завершилась ошибкой. */
} else {
print 'Заявка успешно сохранена.';
}
} else {
print 'Произошла непредвиденная ошибка';
}
?>
Форма сайтфона
Для открытия нашей стандартной формы сайтфона используется метод:
ComagicWidget.openSitePhonePanel();
Капча для формы сайтфона
Comagic.Captcha.get_captcha(callback);
Параметры:
Название | Тип | Описание |
---|---|---|
callback | {key: myKey, url: myURL} |
Возвращаемый ответ: myKey - ключ капчи, myURL - адрес картинки. |
Пример:
Comagic.Captcha.get_captcha(function(resp){console.log(resp)});
Замена маски номера для формы сайтфона
Для того чтобы заменить стандартную маску ввода номера в сайтфоне и разрешить вводить номера в других форматах, в код вставки необходимо добавить строку:
__cs.push(["setUIPhoneMaskFormat", '1 () __-__']);
Вторым параметром необходимо передавать формат маски, которая должна отображаться в сайтфоне.
Пользовательская форма сайтфона
Помимо стандартных виджетов можно использовать любую свою форму для обратного звонка на сайте.
Для этого необходимо встроить вызов метода обратного звонка в свою форму с помощью JS API:
ComagicWidget.sitePhoneCall({captcha_key: <идентификатор капчи>, captcha_value: <решение капчи>, phone:<номер телефона>, delayed_call_time:<время звонка>, group_id:<id группы>}, callback);
Параметры:
Название | Тип | Описание |
---|---|---|
captcha_key | text | Идентификатор капчи. Обязательный, если в настройках обратного звонка включена капча. |
captcha_value | text | Решение капчи (то, что ввел посетитель на форме): взять результат myURL из метода Captcha.get_captcha() , перейти по ссылке, увидеть 4 цифры. Обязательный, если в настройках обратного звонка включена капча. |
phone | text | Номер телефона посетителя. Обязательный. |
delayed_call_time | text | Время совершения звонка в миллисекундах по UTC. |
group_id | text | ID группы сотрудников, в которую будет направлен звонок. |
callback | {"success": <Boolean>, "result":{status: <Integer>, code: <String>}} |
Возвращаемый ответ, необязательный (но желательный). Если его не задать, то функция отработает аналогично вызову из стандартной формы сайтфона и покажет всплывающее уведомление с результатом. Параметры: success: true - успешно, false - не успешно; result - результат вызова: status - статус вызова. |
Возможные статусы:
Код | Значение |
---|---|
0 | успешно, звонок отправлен на платформу |
1 | капча введена неверно |
2 | не задан сценарий обработки обратного звонка |
3 | ошибка платформы |
4 | исчерпан лимит на количество вызовов в минуту (не более 10 звонков) |
Пример использования:
ComagicWidget.sitePhoneCall({captcha_key: 'jwgtGYZDYTA...4pBEWRx', captcha_value: '8315', phone:'79101234567', delayed_call_time: 1508927547000 , group_id: '16587'}, function(resp){console.log(resp)});
Форма чата
При вызове следующего метода, если есть операторы online, открывается форма чата:
Comagic.openChatWindow();
Если ни одного оператора нет online, то открывается форма заявки.
Работа с посетителем
Получение ID посетителя
Для получения ID посетителя используется следующий метод:
Comagic.getVisitorId();
Получение ID сессии посетителя
Для получения ID сессии посетителя используется следующий метод:
Comagic.getSessionId()
Добавление информации о посетителе
Для добавлении информации о посетителе используется следующий метод:
Comagic.addVisitorInfo({name:'myName', phone:'myPhone', email:'myEmail'});
Пользоваться данным методом можно лишь в случае отправки формы способом, не приводящим к перезагрузке страницы! Для остальных ситуаций есть альтернативный метод.
Для успешного вызова метода должен быть заполнен хотя бы один параметр.
Все другие параметры будут проигнорированы
Параметры:
Название | Параметры | Описание |
---|---|---|
req | {name: myName, email: myEmail, phone: myPhone} |
myName - тип text - имя посетителя (перезаписываемый)
myEmail - тип text - адрес электронной почты посетителя (добавляется уникальный)
myPhone - тип text - телефон посетителя (добавляется уникальный)
|
callback | "success": <Boolean> |
Функция одного аргумента, которая будет вызвана после того, как сервер пришлет результат сохранения формы. Необязательный параметр. |
Пример:
Comagic.addVisitorInfo({name:'Test', phone:'79000000000', email:'myemail@axample.com'},function(resp){console.log(resp)})
Альтернативный способ добавления информации о посетителе
Будем исходить из того, что на сайте уже установлен код вставки, подключена библиотека jQuery
- Перед отправкой информации о посетителе нужно получить аутентификационные данные, используя метод JS API
Comagic.getCredentials()
.
Метод возвращает объект:
{
"site_key": "VcB4qqpO1WPSopO670cAbXwAH9Ryaw75",
"key": "u8N4wqLtywFKSaxGOUCreGKD0zglE2s0",
"uri": "https://server.comagic.ru/",
"visitor_id": 17258569,
"hit_id": 546833568748,
"session_id": 255544855,
"consultant_server_url": "https://server.comagic.ru/" // Этот URL нам не нужен
}
- Передать полученные данные вместе с остальным данными формы.
Параметры:
url - https://tracker.comagic.ru/vc/s/
параметры из запроса Comagic.getCredentials():
k=key
ur=uri
ci=comagic_id
hi=hit_id
vp=телефон
vn=имя
ve=емейл
s=1 убирает вывод системных полей в ответе (возвращается только success: true)
Пример
https://tracker.comagic.ru/vc/s/?sk=nS5lMAgURPyUQXVyBgguFy0AvIRdbfdy&ci=2032047566.3117192853.1555675484&hi=9228054013&vn=new_user
Добавление свойства посетителю
Для присвоения свойства или его значения используется следующий метод:
Comagic.setProperty(name, value);
Параметры:
Название | Тип | Описание |
---|---|---|
name | text | Имя свойства, которое должно быть присвоено посетителю |
value | text | Значение свойства (необязательный параметр) |
Примеры:
Свойство тип посетителя со значением Потенциальный устанавливается следующим образом:
Comagic.setProperty('Тип посетителя', 'Потенциальный');
Свойство Действующий клиент (без значения) устанавливается следующим образом:
Comagic.setProperty('Действующий клиент');
Проверка наличия свойства у посетителя
Для проверки наличия свойства у посетиетля используется следующий метод:
Comagic.hasProperty(name, callback);
Параметры:
Название | Тип | Описание |
---|---|---|
name | text | Имя свойства, которое должно быть присвоено посетителю |
callback | {"success": <Boolean>,"result": <Boolean>,} |
Возвращаемый ответ. success: true - метод обработан успешно, false - ошибка; result: true - свойство name установлено false - свойство name не установлено |
Пример:
Comagic.hasProperty('Действующий клиент', callback);
Comagic.hasProperty('Действующий клиент', function(resp){console.log(resp)});
Получение значения свойства посетителя
Для получения значения свойства у посетителя используется следующий метод:
Comagic.getProperty(name, callback);
Параметры:
Название | Тип | Описание |
---|---|---|
name | text | Имя свойства, которое должно быть присвоено посетителю |
callback | {"success": <Boolean>, "result": <value>,} |
Возвращаемый ответ. success: true - метод обработан успешно, false - ошибка; result: value - значение свойства name , false - свойство name не установлено |
Пример:
Comagic.getProperty('Тип клиента', callback);
Comagic.getProperty('Действующий клиент', function(resp){console.log(resp)});
Удаление свойства посетителя
Для удаления свойства, заданного посетителю, используется следующий метод:
Comagic.deleteProperty(name);
Параметры:
Название | Тип | Описание |
---|---|---|
name | text | Имя свойства, которое должно быть удалено |
Пример:
Comagic.deleteProperty('тип посетителя');
Подмена номера
Подмена номера в динамических блоках
Для того, чтобы включить подмену номера в динамически добавляемых блоках, в код вставки необходимо добавить дополнительную строку:
__cs.push(["setDynamicalReplacement", true]);
или
Comagic.push(["setDynamicalReplacement", true]);
Управление подменой номера
В случае, когда подмена номера нужна только при выполнении определенных условий, например, только для посетителей Москвы, нужно переопределить функцию, управляющую подменой номера, window.__cs_onReplacePhones(phones)
. Она работает следующим образом:
-
если возвращает
true
, то подмена будет выполнена так, как если бы функция не была переопределена, -
если возвращает
false
, то подмена не будет выполнена.
Функция создается в момент инициализации сервисного кода и по умолчанию имеет вид:
window.__cs_onReplacePhones = function(phones) {return true;};
Если управлять подменой не требуется, то функцию переопределять не нужно.
Если номера нужно подменять только при определенных условиях, то эту функцию надо переопределить, дописав в тело необходимые условия подмены.
Получение номеров, выданных посетителю
Если клиенту необходимо получить список всех номеров, выданных посетителю сайта, можно воспользоваться следующей функцией:
Comagic.getPhones();
В ответ вернется массив объектов, аналогичный списку phones в __cs_onReplacePhones
.
Пример:
[
{
id: '#comagic_phone', // идентификатор элемента
img: null || 'path/to/img', // адрес картинки (если используется подмена картинкой)
text: null || '+7(495)999-99-99', // отформатированный номер
raw: '74959999999' // номер без форматирования
},
...
]
Параметры:
Тип заменяемого идентификатора | Пример возвращаемого значения поля id |
---|---|
id | #comagic_phone |
class | .comagic_phone |
name | [name=comagic_phone] |
number | number=XXXXXXXXXXX |
Получение зарезервированных под посетителя номеров ДТ
Если клиенту необходимо получить список зарезервированных номеров динамического трекинга под посетителя, можно воспользоваться следующей функцией:
Comagic.getDTPhones();
Эта функция вернет null
в случае, когда под посетителя не зарезервировано ни одного номера динамического трекинга.
Если зарезервированные номера есть, то вернется массив объектов, аналогичный списку phones в __cs_onReplacePhones
.
Пример:
[
{
id: '#comagic_phone', // идентификатор элемента
img: null || 'path/to/img', // адрес картинки (если используется подмена картинкой)
text: null || '+7(495)999-99-99', // отформатированный номер
raw: '74959999999' // номер без форматирования
},
...
]
Параметры:
Тип заменяемого идентификатора | Пример возвращаемого значения поля id |
---|---|
id | #comagic_phone |
class | .comagic_phone |
name | [name=comagic_phone] |
Получение массива фактически подмененных номеров
Эта функция возвращает массив объектов с фактически подменными номерами, т.е. номера которыми была выполнена подмена.
Параметры:
Тип подмены | Принимаемые значения функцией |
---|---|
type | null, "static", "dynamic" |
Параметр необязателен.
Пример использоавния без параметров:
Comagic.getReplacedPhones();
Пример ответа:
{
"number=84872751404": "74951825168"
}
Пример использования c параметром dynamic:
Comagic.getReplacedPhones("dynamic");
Пример ответа:
{
"74951825168": [
"number=84872751404"
]
}
Эмуляция перехода между страницами сайта
Эта функция эмулирует поведение нашего кода вставки во время перехода пользователя между страницами(хит) сайта. Основное применение: эмуляция перехода между страницами на SPA-сайтах.
Comagic.reinitTrackView();