Аналитика посетителя

Идентификатор аналитики связывает посетителя сайта с лидом Senler. Это помогает найти лида в отчёте источника воронки, не записывая ClientID в переменную вручную. Для вызова требуется совместимая версия Public API.

Передайте идентификатор

Дождитесь готовности и авторизации виджета. Получите идентификатор через установленный на вашем сайте счётчик, затем передайте его строкой:

await SenlerWidget.setAnalytics({
  provider: "yandex_metrica",
  sourceId: "12345678",
  identifiers: { client_id: "000123456789" },
  visit: { yclid: "CLICK_ID_FROM_CURRENT_VISIT" },
});

Значения в примере демонстрационные. provider — название системы, sourceId — ID счётчика, потока или пикселя, identifiers — идентификаторы посетителя. Не преобразовывайте ID в числа: ведущие нули могут быть значимыми. visit необязателен и содержит данные именно текущего визита, например идентификатор сессии или рекламного клика.

Для GA4 можно передать provider: "google_analytics", sourceId: "G-ABC123", identifiers: { client_id: "123.456" } и visit: { session_id: "1780000000" }. Своя система может использовать provider: "my_analytics" и visitor_id. Для самостоятельно размещённой системы включите её адрес в sourceId, например analytics.example:42, чтобы одинаковые номера разных установок не смешивались.

setAnalytics не загружает счётчик, не создаёт диалог и не отправляет сообщение агенту. Перед запросом, которому нужны эти данные, дождитесь завершения Promise. Обычные сообщения из поля ввода также получают текущий снимок аналитики.

Обновите данные визита

Повторный вызов заменяет данные только пары provider + sourceId в текущем экземпляре. Объекты identifiers и visit заменяются целиком; отсутствие visit очищает прежние данные визита этого источника. Остальные счётчики не меняются.

Чтобы не прикладывать источник к следующим сообщениям:

await SenlerWidget.setAnalytics({
  provider: "yandex_metrica",
  sourceId: "12345678",
  identifiers: {},
});

Это не удаляет сведения из уже сохранённых событий и профиля лида. После новой загрузки страницы, смены посетителя или создания экземпляра передайте актуальные данные заново. Неудачный вызов оставляет прежний снимок. Если аналитика заблокирована или недоступна, обычный чат продолжает работать без неё.

Что сохраняется

У лида накапливаются уникальные идентификаторы с указанием сайта, системы, счётчика и типа. Повторная передача того же ID не создаёт дубль. В API лида они доступны в analytics_identifiers; список может быть пустым. Это не подтверждение личности и не основание автоматически объединять лидов.

Данные визита сохраняются в снимке исходного события: source_context.analytics у сообщения и payload.analytics у подписки. Для конверсии используйте снимок того события, к которому она относится, а не произвольный ClientID из профиля. Очередь и повтор отправки сохраняют исходный снимок сообщения.

Эти данные не входят в инструкцию агента или плашки контекста. В источнике воронки укажите те же систему, счётчик и тип идентификатора. Неоднозначное совпадение с несколькими лидами не создаёт связь.

Цели и конверсии

setAnalytics сохраняет связь, но не отправляет цели и конверсии во внешние системы. Для события открытия или принятого сообщения подпишитесь на события экземпляра. Условия достижения цели и её отправку настраивает сайт.

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

Пример: три цели Яндекс Метрики

Установите счётчик на сайт и создайте цели widget_opened, chat_started, contact_left для отправки через reachGoal. После загрузки совместимого скрипта SDK v3 используйте эту инициализацию вместо прежней; подставьте номер счётчика и channel_id своего виджета:

const counterId = 12345678;
const goal = (name) => window.ym?.(counterId, "reachGoal", name);
const widget = SenlerWidget.create({ channel_id: "CHANNEL_ID" });

widget.on("open", () => goal("widget_opened"));
widget.on("messageSent", ({ source }) => {
  if (source === "widget") goal("chat_started");
});

widget.registerAction("saveContact", {
  description: "Сохранить телефон или email, оставленный посетителем для связи.",
  returnsResult: true,
  payloadSchema: {
    type: "object",
    properties: { phone: { type: "string" }, email: { type: "string" } },
    additionalProperties: false,
  },
  async handler({ payload }) {
    await widget.updateLead({
      phone: typeof payload.phone === "string" ? payload.phone : undefined,
      email: typeof payload.email === "string" ? payload.email : undefined,
    });
    goal("contact_left");
    return { saved: true };
  },
});

open учитывает открытие штатной кнопкой и программное открытие; изначально видимый embedded-виджет не вызывает это событие. messageSent учитывает принятое сервером сообщение, включая очередь; фильтр source исключает программные запросы ask. Для числа людей, начавших переписку, смотрите «Целевые посетители»: «Достижения цели» в этом примере считают сообщения.

saveContact — объявленное сайтом действие агента, а не встроенное событие. Добавьте агенту инструкцию: «Когда посетитель оставляет свой телефон или email для связи, вызови saveContact с этими данными; подтверждай сохранение только после успешного результата». updateLead сохраняет контакт в текущем лиде; при ошибке цель не отправляется. Для формы сайта вызывайте updateLead и цель из её обработчика после проверки данных, без действия агента.

ClientID для этих браузерных целей передавать в виджет не нужно. Для связи с лидом используйте setAnalytics, описанный выше. Обработчик сайта работает, пока страница открыта; для конверсии после её закрытия настройте серверную отправку по снимку аналитики исходного события. Не отправляйте одну конверсию одновременно обоими способами.

Ограничения

В экземпляре допускается до 8 источников; в каждом identifiers и visit — до 8 строковых значений длиной до 256 символов. provider и имена полей начинаются с латинской строчной буквы, затем допускают строчные буквы, цифры и _, всего до 64 символов. sourceId допускает латинские буквы, цифры, ., _, : и -, длина до 128 символов. Не передавайте секреты и токены доступа.