JavaScript API

Введение

Пользователи CoMagic могут использовать JavaScript API для решения следующих задач:

Для реализации дополнительных возможностей на сайте:

• открытие форм связи онлайн-консультанта (чат, обратный звонок, заявка) из любого места сайта пользователя.

Получение дополнительной информации о посетителях сайта:

• присвоение свойств (например, посетителю, открывшему личный кабинет, присвоено свойство “действующий клиент”, открывшему тарифы - “потенциальный” и т.д.).

Получение дополнительных данных в отчетах:

• данные о любом пользовательском событии на сайте (чтение книги, просмотр тарифов, открытие личного кабинете и т.д);
• информация с любой формы заявки пользователя.

Работа с событиями

Отправка пользовательского события

Для отправки пользовательского события используется следующий метод:

Comagic.trackEvent(category, action, name, value);

Параметры:

Пример использования:

Comagic.trackEvent('Offer', 'DownloadBook', 'CallTrackingBook', 'value');

Получение ID посетителя

Для получения ID посетителя используется следующий метод:

Comagic.getVisitorId();

Работа с баннером

Проверка наличия операторов онлайн

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

Comagic.getOperatorStatus();

Метод возвращает true, если есть хотя бы один доступный оператор, иначе false.

Форма заявки

Для открытия формы заявки используется метод:

Comagic.openSiteRequestPanel();

Пользовательская форма заявки

Данные, полученные при использовании пользовательской формы заявки на сайте, можно отправить в CoMagic с помощью следующего метода:

Comagic.addOfflineRequest(req, callback);

Параметры:

{
  "name": myName,
  "email": myEmail,
  "phone": myPhone,
  "message": myMessage,
  "is_sale": mySale,
  "sale_cost": myCost
}

{
  "success": <Boolean>,
  "result": {
      "code": <String>
  }
}

Пример

1. Обычная заявка:

Comagic.addOfflineRequest({
  name: 'Дмитрий',
  email: 'dmitry@comagic.ru',
  phone: '79123456789',
  message: 'Текст заявки...'
});

2. Заявка, приведшая к продаже:

Comagic.addOfflineRequest({
  name: 'Дмитрий',
  email: 'dmitry@comagic.ru',
  phone: '79123456789',
  message: 'Онлайн заказ...',
  is_sale: true,
  sale_cost: '9999'
});

3. Пример с использованием параметра callback:

Comagic.addOfflineRequest({"name": "My Name Is"}, function(o) {console.log(o);});

после успешного сохранения заявки в консоль браузера будет выведен результат:

Object {success: true, result: null}

Альтернативный способ отправки пользовательской заявки

1. Перед отправкой заявки нужно получить аутентификационные данные виджета CoMagic, используя метод JS API Comagic.getCredentials(). Метод возвращает объект:

{
  "site_key": "VcB4qqpO1WPSopO670cAbXwAH9Ryaw75",
  "visitor_id": 17258569,
  "hit_id": 546833568748,
  "session_id": 255544855,
  "consultant_server_url": "https://server.comagic.ru/" //базовая часть URL
}

2. Передать полученные данные вместе с остальным данными формы.

3. В серверном обработчике заявки сделать HTTP-запрос к сервису CoMagic для добавления заявки.

POST https://server.comagic.ru/api/add_offline_message/
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Form Data //данные отформатированы для наглядности
site_key=VcB4qqpO1WPSopO670cAbXwAH9Ryaw75
&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
}

Пример использования альтернативного способа отправки пользовательской заявки

Вариант с перезагрузкой страницы

Будем исходить из того, что на сайте уже установлен код вставки CoMagic, подключена библиотека 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>

Для того, чтобы отправить заявку в CoMagic, код формы нужно доработать: добавить служебные поля и обработчик на кнопку "Отправить":

<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='site_key'/>
    <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 (field in credentials) {
        if (credentials.hasOwnProperty(field)){
            $('[name='+field+']').val(credentials[field]);
        }
    }
    $('#myform').submit();
}

Этот код получает служебную информацию от CoMagic, сохраняет ее в невидимые служебные поля формы и отправляет форму на сервер.

Далее, нужно модифицировать код, который отвечает за обработку заявки на сервере. В нашем случае этот код находится в файле send.php:

<? /* Здесь код по умолчанию, связанный с обработкой заявки на серверной стороне. Например, отправка писем, или сохранение в базу данных. */ ?>
<?
    $url = $_POST['consultant_server_url'].'api/add_offline_message/';
          $data = array(
            'site_key' => $_POST['site_key'], //Значение без изменений из служебного поля site_key
            '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 'Произошла непредвиденная ошибка';
    }
?>

Для того, чтобы отправить заявку в CoMagic в случае отправки заявки AJAX-запросом, модифицировать HTML-форму не нужно. Нужно модифицировать JS-код таким образом, чтобы получение служебной информации CoMagic происходило перед отправкой запроса:

function sendAjaxSubmit() {
    /* Здесь может быть проверка заполненных обязательных полей, валидация номера телефона и
    другие проверки. */
    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(
            'site_key' => $_POST['site_key'], //Значение без изменений из служебного поля site_key
            '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]) {
            /* Обработка случая, если отправка заявки в CoMagic завершилась ошибкой. */
        } else {
            print 'Заявка успешно сохранена.';
        }
    } else {
        print 'Произошла непредвиденная ошибка';
    }
?>

Форма обратного звонка

Для открытия нашей стандартной формы обратного звонка используется метод:

Comagic.openSitePhonePanel();

Капча для формы обратного звонка

Comagic.Captcha.get_captcha(callback);

Параметры:

Comagic.Captcha.get_captcha(function(resp){console.log(resp)});

Пользовательская форма обратного звонка

Помимо стандартных виджетов CoMagic можно использовать любую свою форму обратного звонка на сайте.

Для этого необходимо встроить вызов метода обратного звонка в свою форму с помощью JS API:

Comagic.sitePhoneCall({captcha_key: <идентификатор капчи>, captcha_val: <решение капчи>, phone:<номер телефона>}, callback);

Параметры:

{
  "success": <Boolean>,
  "result":{
    status: <Integer>,
    code: <String>
  }
}

Возможные статусы:

Пример использования:

Comagic.sitePhoneCall({captcha_key: 'jwgtGYZDYTA...4pBEWRx', captcha_val: '8315', phone:'79101234567'}, function(resp){console.log(resp)});

Форма сайтфона

Для открытия стандартной формы сайтфона используется метод:

ComagicWidget.openSitePhonePanel();

Форма чата

При вызове следующего метода, если есть операторы online, открывается форма чата:

Comagic.openChatWindow();

Работа со свойствами

Добавление свойства посетителю

Для присвоения свойства или его значения используется следующий метод:

Comagic.setProperty(name, value);

Параметры:

Свойство тип посетителя со значением Потенциальный устанавливается следующим образом:

Comagic.setProperty('Тип посетителя', 'Потенциальный');

Свойство Действующий клиент (без значения) устанавливается следующим образом:

Comagic.setProperty('Действующий клиент');

Проверка наличия свойства у посетителя

Для проверки наличия свойства у посетиетля используется следующий метод:

Comagic.hasProperty(name, callback);

Параметры:

{
  "success": <Boolean>,
  "result": <Boolean>,
}

Пример:

Comagic.hasProperty('Действующий клиент', callback);
Comagic.hasProperty('Действующий клиент', function(resp){console.log(resp)});

Получение значения свойства посетителя

Для получения значения свойства у посетителя используется следующий метод:

Comagic.getProperty(name, callback);

Параметры:

{
  "success": <Boolean>,
  "result": <value>,
}

Пример:

Comagic.getProperty('Тип клиента', callback);
Comagic.getProperty('Действующий клиент', function(resp){console.log(resp)});

Удаление свойства посетителя

Для удаления свойства, заданного посетителю, используется следующий метод:

Comagic.deleteProperty(name);

Параметры:

Пример:

Comagic.deleteProperty('тип посетителя');

Подмена номера

Подмена номера в динамических блоках

Для того, чтобы включить подмену номера в динамически добавляемых блоках, в код вставки необходимо добавить дополнительную строку:

__cs.push(["setDynamicalReplacement", true]);

или

Comagic.push(["setDynamicalReplacement", true]);

Управление подменой номера

В случае, когда подмена номера нужна только при выполнении определенных условий, например, только для посетителей Москвы, нужно переопределить функцию, управляющую подменой номера, window.__cs_onReplacePhones(phones). Она работает следующим образом:

• если возвращает true, то подмена будет выполнена так, как если бы функция не была переопределена,
• если возвращает false, то подмена не будет выполнена.

Функция создается в момент инициализации сервисного кода CoMagic и по умолчанию имеет вид:

window.__cs_onReplacePhones = function(phones) {
    return true;
};

Если управлять подменой не требуется, то функцию переопределять не нужно.

Если номера нужно подменять только при определенных условиях, то эту функцию надо переопределить, дописав в тело необходимые условия подмены.

Также данная функция позволяет не только управлять подменой, но и выполнять её самостоятельно. Для этого в функцию передается массив phones:

[
  {
    id: "#comagic_phone", // идентификатор
    img: "/path/to/image", // адрес картинки (если используется подмена картинками)
    text: "+7 (495) 926-86-86", // номер, отформатированный в соответствии с настройками пользователя
    raw: "74959268686" // номер без форматирования
  },
  ...
]

Получение номеров, выданных посетителю

Если клиенту необходимо получить список всех номеров, выданных посетителю сайта, можно воспользоваться следующей функцией:

Comagic.getPhones();

В ответ вернется массив объектов, аналогичный списку phones в __cs_onReplacePhones.

Пример:

[
  {
    id: '#comagic_phone', // идентификатор элемента
    img: null || 'path/to/img', // адрес картинки (если используется подмена картинкой)
    text: null || '+7(495)999-99-99', // отформатированный номер
    raw: '74959999999' // номер без форматирования
  },
  ...
]

Параметры:

Получение зарезервированных под посетителя номеров ДТ

Если клиенту необходимо получить список зарезервированных номеров динамического трекинга под посетителя, можно воспользоваться следующей функцией:

Comagic.getDTPhones();

Эта функция вернет null в случае, когда под посетителя не зарезервировано ни одного номера динамического трекинга.

Если зарезервированные номера есть, то вернется массив объектов, аналогичный списку phones в __cs_onReplacePhones.

Пример:

[
  {
    id: '#comagic_phone', // идентификатор элемента
    img: null || 'path/to/img', // адрес картинки (если используется подмена картинкой)
    text: null || '+7(495)999-99-99', // отформатированный номер
    raw: '74959999999' // номер без форматирования
  },
  ...
]

Параметры:

Кастомизация виджетов

Widget API CoMagic – это методы, с помощью которых можно:

• изменять внешний вид виджета (полностью или частично);
• изменять настройки виджета для конкретной страницы (можно делать разные виджеты для разных страниц, скрывать виджеты на страницах и т.д.);
• гибко управлять логикой показа и функционалом виджета (отключать ненужный функционал)

Например, вы можете полностью изменить внешний вид виджета онлайн-консультант.

Переработать под стиль сайта окно чата.

Изменить форму генератора звонка.