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

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 — вызывается при первом сообщении пользователя в текущей вкладке.

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

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

Эта функция будет вызвана сразу после инициализации API, но до события load.

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

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

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

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

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.

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

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

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

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');
    });
}

Отладка в production

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

Важно!

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

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

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

Оглавление