Для разработчиков

API

Consultant и Tracker JS API

Практическое руководство по работе с JS API

Практическое руководство по работе с JS API

Скопировать ссылку на статью

Скопировано

Содержание

Введение
- Начало работы с JS API: onOcapiReady
- Настройка внешнего вида виджета
Подписка на события
Общие методы взаимодействия
- Проверка активности виджета и трекера
- Установка системного и внешнего ID клиента
Взаимодействие с виджетом
Взаимодействие с трекером
- Запуск трекера
- Отправка события трекера
Отладка в production
- Установка скрипта
- Расшифровка сообщений

JS API (Consultant & Tracker JS API) предоставляет интерфейс для взаимодействия кода вашего сайта с виджетом Консультанта и трекером.

Примечание

Не путать с JS API для JS-модулей.

Для удобства в этой статье Consultant & Tracker JS API будет упоминаться в сокращенном виде - JS API.

Введение

JS API позволяет выполнять следующие действия:

Подписываться на события;
Открывать и закрывать виджет;
Изменять приветственное сообщение виджета;
Заполнять контактную и оффлайн-формы виджета;
Отключать виджет;
Скрывать и показывать кнопку виджета;
Проверять активность виджета и трекера;
Запускать трекер (если он был остановлен);
Отправлять события трекера;
Устанавливать системный ID клиента;
Устанавливать внешний ID клиента (ID на сайте);
Использовать callback для выполнения действий после загрузки API, но до отрисовки кнопки или отправки событий.
Программно настраивать внешний вид виджета.

Доступные события:

load — вызывается после загрузки настроек и onOcapiReady, но до первой отрисовки виджета. Не содержит параметров.
open — срабатывает при открытии виджета (программно или вручную).
close — срабатывает при закрытии виджета (программно или вручную).
before_contact_form — срабатывает перед отправкой контактной формы, но после валидации. Позволяет повлиять на отправку.
before_offline_form — срабатывает перед отправкой оффлайн-формы, но после валидации. Позволяет повлиять на отправку.
contact_form — срабатывает после отправки контактной формы. Позволяет узнать статус отправки.
offline_form — срабатывает после отправки оффлайн-формы. Позволяет узнать статус отправки.
first_user_message — вызывается при первом сообщении пользователя на сайте.
first_message — вызывается при первом сообщении пользователя в текущей вкладке.

Важно!

Событие load означает, что настройки загружены, API готово к работе, а виджет ещё не показан. На момент вызова обработчика внутренняя инициализация виджета ещё не завершена: в частности, сообщения ещё не загружены, а соединение для их получения ещё не настроено.

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

Начало работы с JS API: onOcapiReady

API определяет свойство ocapi у объекта window. Перед началом работы необходимо убедиться, что API полностью инициализировано. Для корректной и надёжной работы с API, особенно для выполнения действий до появления кнопки виджета, следует использовать функцию onOcapiReady, определённую в window.

Функция будет вызвана после загрузки настроек и определения доступности виджета и трекера, но до события load и первого показа виджета. Для взаимодействия с API до загрузки виджета следует использовать именно её.

function onOcapiReady () {
    const api = window.ocapi;

    // Делаем что-то с API.
}

Настройка внешнего вида виджета

Метод configureWidgetAppearance(settings) принимает объект с частью настроек внешнего вида. Переданные значения имеют приоритет над настройками, полученными от сервера.

Вложенные объекты объединяются по отдельным полям. Например, если передан только bottomMargin, значение sideMargin продолжает браться из настроек Консультанта. При повторном вызове изменяются только переданные поля, поэтому метод можно использовать при переходах внутри SPA.

function onOcapiReady () {
    const api = window.ocapi;

    api.configureWidgetAppearance({
        behavior: {
            sideMargin: '30px',
            bottomMargin: '30px',
            placement: 'right'
        }
    });
}

Настройки также можно применить в обработчике load. Если одно поле переопределено и в onOcapiReady, и в load, используется значение из обработчика load.

Поддерживается следующий объект настроек:

{
    style: {
        title: 'Title',
        color: '#FFF',
        invertColor: true,
        elements: 'rounded' | 'regular',
        icon: 'standart' | 'https://example.com/icon.png',
        iconStretchToWidth: false,
        mode: 'light' | 'dark'
    },
    behavior: {
        initialState: 'minimized' | 'opened' | 'delayedAutoOpened',
        autoOpenDelay: '10',
        openOnNewMessages: true,
        showInMobileBrowsers: true,
        operatorDisplayMode: 'normal' | 'custom',
        customOperator: {
            name: 'Operator',
            avatar: 'https://example.com/avatar.png'
        },
        sideMargin: '30px',
        bottomMargin: '30px',
        placement: 'right' | 'left'
    }
}

Подписка на события

Подписка на события позволяет реагировать на различные этапы жизненного цикла Консультанта.

function onOcapiReady() {
    window.ocapi.on('load', () => {
        console.log('Consultant has been loaded!');
    });
}

Если событие передаёт параметры, функция обратного вызова (колбек) может с ними взаимодействовать. Например, можно заблокировать отправку формы, если email не соответствует определённым критериям.

// Блокируем отправку контактной формы с E-Mail от Proton Mail.
function onOcapiReady() {
    const protonExpr = /protonmail\.com$|proton\.me$|pm\.me$/i

    window.ocapi.on('before_contact_form', (event) => {
        const data = event.data

        if (data.email && protonExpr.test(data.email)) {
            event.error('Извините, Proton Mail в данный момент не поддерживается.')
        }
    });
}

События с параметрами и без

События, передающие контекст и позволяющие повлиять на результат:
- before_contact_form
- before_offline_form
События, передающие информацию о происходящем, но без возможности повлиять на него:
- contact_form
- offline_form
- first_user_message
- first_message

События форм

Все события, связанные с формами, принимают на вход объект со следующими свойствами и методами:

done — true, если форма уже отправлена, иначе false.
err — содержит экземпляр Error, если отправка не удалась из-за ошибки, или null, если ошибок не было.
prevent() — предотвращает отправку формы. Доступен только для событий с префиксом before_.
error(String) — предотвращает отправку формы и выводит указанный текст ошибки. Если передано falsy-значение, используется стандартный текст. Доступен только для событий с префиксом before_.
data — содержит данные отправляемой формы.

Формат поля data следующий:

interface IFormUser {
    name?: string,
    email?: string,
    phone?: string
}

Пример проверки данных в поле data:

function onOcapiReady() {
    window.ocapi.on('before_offline_form', (event) => {
        const data = event.data

        if (data.name && data.name === 'Сталин') {
            alert('Ленин!')
            event.prevent()
        }
    });
}

События сообщений

К этой категории относятся события first_user_message и first_message.

Разница между ними заключается в том, что first_user_message вызывается только один раз для первого сообщения пользователя с конкретным ID, включая предыдущие сессии. Событие first_message вызывается при написании первого сообщения после открытия виджета в новой вкладке (или после перезагрузки страницы).

Пример подписки на событие first_user_message для отправки данных в Google Analytics 4:

function onOcapiReady() {
    const api = window.ocapi;

    api.on('first_user_message', (event) => {
        const eventParams = {
            event_category: 'User Messages',
            event_label: event.content,
            message_id: event.id,
            from_me: event.fromMe,
            message_status: event.status,
            message_type: event.type,
            message_time: event.time,
            data_id: event.data.id,
            data_time: event.data.time,
            data_updated_at: event.data.updatedAt,
            data_status: event.data.status
        };

        // Событие Google Analytics 4
        gtag('event', 'first_user_message', eventParams);
    });
}

Формат параметра event:

interface Message {
    id: string;
    content: string;
    fromMe: boolean;
    status: string;
    type: string;
    time: string; // Строка даты в формате ISO 8601.
    data: {
        id: string;
        time: string; // Строка даты в формате ISO 8601.
        updatedAt: string; // Строка даты в формате ISO 8601.
        status: string;
    };
}

Пример содержимого event:

{
    "id": "uid1761070046528",
    "content": "Hello!",
    "fromMe": true,
    "status": "sent",
    "type": "text",
    "time": "2025-10-21T18:07:26.540608958Z",
    "data": {
        "id": "146",
        "time": "2025-10-21T18:07:26.540608958Z",
        "updatedAt": "2025-10-21T18:07:26.540608958Z",
        "status": "sent"
    }
}

Общие методы взаимодействия

Эти методы влияют как на виджет, так и на трекер.

Проверка активности виджета и трекера

function onOcapiReady() {
    const api = window.ocapi;

    api.hasWidget(); // true, если виджет доступен, иначе false.
    api.hasTracker(); // true, если трекер доступен, иначе false.
}

Важно!

После вызова метода полного отключения виджета disableWidget() результат hasWidget() всегда будет false, независимо от фактической доступности виджета в момент загрузки.

Установка системного и внешнего ID клиента

function onOcapiReady() {
    const api = window.ocapi;

    // Указываем customer.id в системе.
    api.setCustomerSystemId(1);

    // Указываем customer.externalId в системе.
    api.setCustomerSiteId('external_1');
}

Нюансы работы методов:

setCustomerSystemId и setCustomerSiteId могут принимать число, строку или функцию.
Функция, передаваемая в setCustomerSystemId, должна возвращать число.
Функция, передаваемая в setCustomerSiteId, должна возвращать строку.
При передаче функции в setCustomerSiteId, она ведёт себя по-разному для виджета и трекера:
- Для виджета функция вызывается один раз, и результат сохраняется.
- Трекер вызывает функцию каждый раз, когда ему требуется получить customer.externalId.
setCustomerSiteId влияет и на виджет, и на трекер.
setCustomerSystemId влияет только на трекер.

Важно!

Рекомендуется использовать именно setCustomerSiteId или передавать customer.externalId в _rcco.

Если внешний ID одновременно передан в _rcco.customer.customer_id и установлен через setCustomerSiteId внутри onOcapiReady, после завершения onOcapiReady будет применено значение из _rcco.customer.customer_id. Чтобы избежать неоднозначности, используйте только один из этих способов установки внешнего ID.

Взаимодействие с виджетом

Эти методы предназначены для управления только виджетом.

Открытие и закрытие виджета

function onOcapiReady() {
    const api = window.ocapi;

    if (!api.hasWidget()) {
        return;
    }

    // Открывает виджет.
    api.openWidget();

    // Закрывает виджет.
    api.closeWidget();
}

Примечание

Проверять наличие виджета через hasWidget() необязательно. Если виджет недоступен, эти методы просто ничего не сделают.

Смена приветственного сообщения

Метод setWelcomeMessage позволяет установить или убрать приветственное сообщение в виджете. Поддерживается только текст.

function onOcapiReady() {
    const api = window.ocapi;

    // Устанавливает приветственное сообщение.
    api.setWelcomeMessage('Привет!')

    // Убирает приветственное сообщение.
    api.setWelcomeMessage(null)
}

Заполнение контактной и оффлайн-формы

Метод setWelcomeFormUser позволяет заранее заполнить поля контактной и оффлайн-формы. Метод не отправляет форму автоматически, давая клиенту возможность проверить и при необходимости изменить данные.

function onOcapiReady() {    
    window.ocapi.setWelcomeFormUser({
        name: 'Артур',
        email: 'arthur@example.com',
        phone: '78000000000'
    })
}

Особенности работы метода:

Заполнение срабатывает как для контактной, так и для оффлайн-формы.
Метод только дополняет существующие данные и не позволяет очищать уже заполненные поля.

Полное отключение виджета

Метод disableWidget полностью отключает виджет на странице. В результате скрипт переходит в режим "только трекер" или полностью прекращает работу, если трекер также недоступен.

function onOcapiReady() {
    const currentPage = window.location.pathname;

    const isOrderPage = currentPage.includes('/order') || currentPage.includes('/cart');
    const isCheckoutPage = currentPage.includes('/checkout');

    if (isOrderPage || isCheckoutPage) {
        window.ocapi.disableWidget();
    }
}

Скрытие и отображение кнопки виджета

function onOcapiReady() {
    const api = window.ocapi;

    if (!api.hasWidget()) {
        return;
    }

    // Скрывает кнопку виджета.
    api.hideWidgetButton();

    // Показывает кнопку виджета.
    api.showWidgetButton();
}

Взаимодействие с трекером

Эти методы предназначены для управления только трекером.

Запуск трекера

Функция startTracking полезна при использовании форм получения согласия (например, cookie-баннеров для соблюдения GDPR). Если в настройках активирована поддержка таких форм, трекер не будет отправлять события до тех пор, пока пользователь не даст своё согласие.

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

function onOcapiReady() {
    const api = window.ocapi;

    api.on('load', () => {
        if (confirm('Вы согласны на сбор анонимизированной телеметрии?')) {
            api.startTracking();
        }
    });
}

Отправка события трекера

Для отправки кастомных событий в трекер используется метод event.

function onOcapiReady() {
    const api = window.ocapi;

    api.on('load', () => {
        api.event('page_view');
    });
}

Более подробные примеры отправки событий и список типов событий с параметрами доступны в статье Руководство по JS API для отслеживания событий на сайте.

Отладка в production

Для отладки работы с событиями трекера и отслеживания вызовов API-методов можно использовать специальный юзерскрипт. Он добавляет в консоль браузера логирование всех вызовов к API, аналогично отладчику GTM.

Важно!

Юзерскрипт следует отключать после использования, чтобы он не активировался на всех посещаемых сайтах.

Установка скрипта

Установите менеджер юзерскриптов для вашего браузера:
- Chrome: Tampermonkey
- Firefox: Violentmonkey, Greasemonkey
- Microsoft Edge: Tampermonkey
- Opera: Tampermonkey
- Safari: Userscripts
Установите отладочный юзерскрипт по этой ссылке или скопируйте его содержимое и установите вручную.
Если потребуется, следуйте инструкциям менеджера (например, Tampermonkey может запросить включение режима разработчика).

Для браузеров на базе Chromium (Chrome, Microsoft Edge, Brave и другие): при использовании Tampermonkey может потребоваться дополнительно разрешить выполнение пользовательских скриптов:

Перейдите в список установленных расширений браузера (как правило, Настройки → Расширения).
В правом верхнем углу включите переключатель «Режим разработчика».
Найдите в списке расширение Tampermonkey и нажмите «Сведения» на его карточке.
Найдите переключатель «Разрешить пользовательские скрипты» и включите его.
Перезапустите браузер.

После этого юзерскрипты начнут выполняться корректно.

После установки на всех сайтах с JS API будет вестись логгирование его работы в консоли браузера.

Расшифровка сообщений

Все сообщения отладчика имеют префикс [OCAPI], по которому их можно отфильтровать во вкладке Console.

window.ocapi detected, verbose logging has been enabled. API обнаружен, скрипт активирован.
window.ocapi not found after 30000ms API на этом сайте не обнаружен.
_rcct was not defined as window property but rather as a global scope variable... Указанная переменная (_rcct или _rcco) объявлена не в window, а в глобальной области видимости (например, через const или let). Это может нарушать работу Консультанта. Рекомендуется изменить объявление на var.
Found site token in window._rcct: 0 Выводит значение токена сайта, который будет использоваться виджетом/трекером.
Found widget settings in window._rcco: {} Выводит содержимое window._rcco.
_rcco has non-falsy customer.customer_id but it was NOT set in the tracker. В window._rcco был указан customer_id, но он не установился в скрипт трекера. Это означает, что события НЕ будут связываться с клиентами.
Incorrect onOcapiReady definition, should be available on window: Некорректно определена функция onOcapiReady.
dispatched event 'load' Вызывается событие, на которое можно подписаться через ocapi.on. Может содержать контекст.
tracker event 'page_view' Отправлено событие трекера (включая стандартные). Сообщение можно раскрыть, чтобы увидеть данные события.
flushing tracker events Происходит отправка накопленных событий. Сообщение можно раскрыть, чтобы увидеть данные отправляемых событий.

Остальные сообщения — это логи вызовов методов ocapi. Среди них наиболее полезны:

on() — подписка на событие.
event() — программная отправка события трекера.

Большинство сообщений выводятся в свёрнутом виде. Их можно развернуть, кликнув на них в консоли браузера.

Благодарим за отзыв.

Была ли статья полезна?

Нет

Да

Практическое руководство по работе с JS API Скопировать ссылку на статью Скопировано