Для пользователей

Маркетинг

Трекинг посетителей сайта

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

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

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

Скопировано

Содержание

1. Начало работы: объект ocapi
2. Отправка событий
3. Типы событий и их параметры

В данной статье описывается, как взаимодействовать с трекером событий RetailCRM с помощью JavaScript API.

1. Начало работы: объект `ocapi`

Для взаимодействия с трекером используется JS API, доступный через глобальный объект ocapi.

Важно!

Объект ocapi и его методы становятся доступны только после полной загрузки страницы (событие window.load). Поэтому весь код для работы с трекером должен выполняться внутри обработчика этого события.

Пример: Установка внешнего ID клиента для связывания его профиля на сайте с профилем в CRM.

window.addEventListener('load', () => {
  // Предполагается, что переменная externalId уже определена
  ocapi.setCustomerSiteId(externalId);
});

Метод setCustomerSiteId принимает внешний ID клиента из интернет-магазина (customer.externalId). Метод setCustomerSystemId используется для внутреннего числового ID клиента в RetailCRM.

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

2. Отправка событий

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

Синтаксис:

ocapi.event('eventName', { /* параметры события */ });

eventName (string) — название события. Обязательный параметр.
parameters (object) — объект с параметрами события. Необязательный параметр.

2.1. Автоматически передаваемые данные

При каждом вызове ocapi.event() трекер автоматически собирает и передает следующие данные:

Текущая страница, на которой находится пользователь.
URL страницы, с которой был совершен переход (Referrer), включая UTM-метки.
Cookie клиента из Google Analytics (если используется).

2.2. Создание нового клиента при отправке события

Вы можете создать нового клиента в CRM прямо в момент отправки события, добавив в объект с параметрами флаг create_customer: true.

Для успешного создания должны выполняться следующие условия:

В параметрах события не должен быть указан system_customer_id.
Должен быть выполнен один из вариантов:
- в параметрах события указан system_external_customer_id;
- в параметрах события указаны create_customer_by_email: true и customer_email.
В параметрах должен присутствовать хотя бы один из следующих идентификаторов клиента: customer_firstname, customer_lastname, customer_patronymic, customer_email или customer_phone.

Клиента можно создать по email без внешнего ID.

Пример создания клиента по E-Mail без ID на сайте:

ocapi.event('register', {
  create_customer_by_email: true,
  create_customer: true,
  customer_email: 'test@example.com'
});

Для преднастраиваемых событий поведение зависит от настройки «Создавать клиента по email»:

если опция отключена, сохраняются только события пользователей, у которых есть ID на сайте;
если опция включена, можно сохранять события пользователей без ID на сайте, если у них указан хотя бы E-Mail.

E-Mail для преднастраиваемого события задаётся как обычный параметр события. Его можно передать из значения элемента на странице, например через селектор.

Создание клиента по email не присоединяет к новой карточке ранее записанные анонимные визиты и корзину. Чтобы связать последующие события с клиентом, передайте его постоянный внешний ID через setCustomerSiteId или внутренний ID RetailCRM через setCustomerSystemId. После идентификации повторно отправьте актуальное состояние корзины.

2.3. Использование параметров в сегментации

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

3. Типы событий и их параметры

Ниже представлен полный список событий, которые можно отслеживать, с описанием их параметров и примерами использования.

3.1. Просмотр страницы (`page_view`)

Фиксирует, какие страницы или товары просматривал клиент. Это позволяет точнее определить его интересы и сделать более релевантные предложения.

Параметры:

offer_id (int): внутренний ID торгового предложения в CRM.
offer_external_id (string): внешний ID торгового предложения.
offer_xml_id (string): ID торгового предложения из складской системы.
offer_brand (string): бренд товара.

Чтобы корректно связать просмотр с товаром в системе, передайте хотя бы один из идентификаторов: offer_id, offer_external_id или offer_xml_id. Если передано несколько, они обрабатываются в следующем порядке: offer_id, offer_external_id, offer_xml_id.

Примеры:

Просмотр обычной страницы (без привязки к товару):
```
ocapi.event('page_view');
```

Просмотр страницы товара с указанием всех идентификаторов:

ocapi.event('page_view', {
  offer_id: 1,
  offer_external_id: '1ext',
  offer_xml_id: '1xml_id',
  offer_brand: 'Mark 42'
});

Просмотр с указанием только offer_external_id:
```
ocapi.event('page_view', {
  offer_external_id: 'product-123'
});
```

3.2. Клик по элементу (`click`)

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

Параметры:

el (string): селектор или текстовое описание элемента, по которому был клик.
leaving (bool): true, если клик приводит к переходу на внешний сайт.

Примеры:

Простой клик без указания элемента:
```
ocapi.event('click');
```

Клик по кнопке "Помощь":

ocapi.event('click', {
  el: 'Помощь'
});

Клик по ссылке на внешний ресурс:

ocapi.event('click', {
  el: 'Партнерский сайт',
  leaving: true
});

3.3. Регистрация (`register`)

Позволяет в реальном времени получить данные нового клиента в CRM, не дожидаясь плановой выгрузки с сайта.

Параметры:

customer_first_name (string): имя.
customer_last_name (string): фамилия.
customer_patronymic (string): отчество.
customer_email (string): email.
customer_phone (string): номер телефона.
subscriptions (array): массив объектов с информацией о подписках.
- channel (string): канал подписки ('email', 'sms', 'waba').
- subscription (string): информация о подписке (например, название рассылки).
- active (bool): флаг активности подписки.

Важно!

При передаче подписки в массиве subscriptions необходимо явно указывать флаг active: true. Если его не указать, подписка будет считаться неактивной (false по умолчанию).

Примеры:

Регистрация со всеми данными:

ocapi.event('register', {
  customer_first_name: 'Иван',
  customer_last_name: 'Иванов',
  customer_patronymic: 'Иванович',
  customer_email: 'test@example.com',
  customer_phone: '79559990101',
  subscriptions: [
    {
      channel: 'email',
      subscription: 'Новости и акции',
      active: true
    }
  ]
});

Простая регистрация (факт события без данных):
```
ocapi.event('register');
```

3.4. Вход в аккаунт (`login`)

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

Параметры:

customer_email (string): email пользователя, выполнившего вход.

Примеры:

// Без параметров
ocapi.event('login');

// С указанием email
ocapi.event('login', {
  customer_email: 'test@example.com'
});

3.5. Запрос консультации (`consult`)

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

Параметры:

customer_email (string): email пользователя для связи.

Примеры:

// Без параметров
ocapi.event('consult');

// С указанием email
ocapi.event('consult', {
  customer_email: 'test@example.com'
});

3.6. Открытие корзины (`open_cart`)

Позволяет определить, как часто клиенты просматривают содержимое корзины, но не переходят к оформлению заказа.

Параметры:

customer_email (string): email пользователя.

Примеры:

// Без параметров
ocapi.event('open_cart');

// С указанием email
ocapi.event('open_cart', {
  customer_email: 'test@example.com'
});

3.7. Отправка формы обратной связи (`contact`)

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

Параметры:

channel (string): тип канала ('email', 'waba', 'sms').

Примеры:

// Без параметров
ocapi.event('contact');

// С указанием канала
ocapi.event('contact', {
  channel: "waba"
});

3.8. Изменение состояния корзины (`cart`)

Передаёт актуальный состав корзины в RetailCRM. Состав используется в карточке клиента и сценариях работы с брошенными корзинами.

Параметры:

cart_id (string): (обязательный) актуальный идентификатор корзины на сайте.
items (array): (обязательный) список товаров в корзине.
- id (int): внутренний ID торгового предложения.
- external_id (string): внешний ID торгового предложения.
- xml_id (string): ID из складской системы.
- price (float): цена за единицу товара. Если не передать, используется цена из каталога CRM.
- quantity (int): (обязательный) количество товара.

Для каждого товара в items необходимо передать хотя бы один из идентификаторов (id, external_id, xml_id). Порядок их обработки: id, external_id, xml_id.

Примеры:

ocapi.event('cart', {
  cart_id: 'ext_id_12345',
  items: [
    {
      id: 1, // Идентификатор из CRM
      external_id: 'ext_1',
      xml_id: 'xml_id_1',
      price: 159.00,
      quantity: 2
    },
    {
      external_id: 'product-abc', // Другой товар
      quantity: 1
      // Цена не указана, будет взята из системы
    }
  ]
});

После авторизации или регистрации посетителя выполняйте действия в следующем порядке:

передайте внешний ID клиента через setCustomerSiteId или внутренний ID RetailCRM через setCustomerSystemId;
повторно отправьте событие cart с актуальным составом;
при оформлении создайте заказ через REST API и передайте isFromCart: true.

Значение isFromCart: true означает, что заказ оформлен из отслеживаемой корзины. Если связанная корзина найдена, CRM завершает её. При значении false или без параметра CRM не ищет корзину по совпадению состава товаров.

Событие order из следующего раздела фиксирует оформление в визитах клиента, но не создаёт заказ в CRM.

3.9. Оформление заказа (`order`)

Фиксирует факт создания заказа на сайте.

Обратите внимание: На данный момент это событие только регистрирует факт оформления заказа в визитах клиента. Сам заказ и его состав не передаются в RetailCRM через этот метод.

Все параметры являются необязательными.

Параметры:

order_number (string): номер заказа на сайте.
order_external_id (string): внешний ID заказа в системе.
total (float): итоговая стоимость заказа с доставкой.
delivery_price (float): стоимость доставки.
items (array): список товаров (структура аналогична событию cart).

Примеры:

Простая фиксация события:
```
ocapi.event('order');
```

Передача с номером заказа:

ocapi.event('order', {
  order_number: '100-C',
  order_external_id: '100_E'
});

3.10. Подписка на рассылку (`subscription`)

Отслеживает подписки на маркетинговые рассылки, помогая определить наиболее популярные каналы оповещения.

Параметры:

channel (string): канал подписки ('email', 'waba', 'sms').
subscription (string): информация о подписке.
active (bool): флаг активности подписки.

Важно!

Как и в событии register, если вы указываете channel, необходимо явно передавать active: true для активации подписки.

Примеры:

// Простой факт подписки
ocapi.event('subscription');

// Подписка на конкретную рассылку по email
ocapi.event('subscription', {
  channel: 'email',
  subscription: 'Рассылка новой коллекции',
  active: true
});

3.11. Начало заполнения формы (`form_start`)

Фиксирует момент, когда пользователь начинает взаимодействовать с формой. В связке с form_submit помогает выявить проблемы: если событий form_start много, а form_submit — мало, возможно, форма слишком сложная.

Параметры:

form_selector (string): CSS-селектор формы.

Примеры:

// Без параметров
ocapi.event('form_start');

// С указанием селектора формы
ocapi.event('form_start', {
  form_selector: 'form.checkout-form'
});

3.12. Отправка формы (`form_submit`)

Фиксирует успешную отправку формы. Ценное событие для анализа конверсии и эффективности различных форм на сайте.

Параметры:

form_selector (string): CSS-селектор отправленной формы.

Примеры:

// Без параметров
ocapi.event('form_submit');

// С указанием селектора
ocapi.event('form_submit', {
  form_selector: '#form-checkout'
});

3.13. Скачивание файла (`file_download`)

Помогает определить, какой загружаемый контент (например, прайс-листы, инструкции, электронные книги) наиболее популярен среди пользователей.

Параметры:

file_name (string): имя скачиваемого файла.

Примеры:

// Простой факт скачивания
ocapi.event('file_download');

// Скачивание конкретного файла
ocapi.event('file_download', {
  file_name: 'price-list-2025.pdf'
});

3.14. Обновление избранных товаров (`favorite_product`)

Фиксирует изменения списка избранных товаров у клиента. При наличии настроенной связи событий с клиентом в системе список избранного синхронизируется с этим клиентом.

Параметры:

offer_id (int): внутренний ID торгового предложения в CRM.
offer_external_id (string): внешний ID торгового предложения.
offer_xml_id (string): ID торгового предложения из складской системы.
removed (bool): true, если товар был удалён из избранного, false, если товар был добавлен в избранное.

Чтобы корректно связать торговое предложение с избранным, необходимо передать хотя бы один из идентификаторов: offer_id, offer_external_id или offer_xml_id. Если передано несколько, они учитываются вместе (у торгового предложения должны совпадать все переданные идентификаторы).

Примеры:

Товар добавлен в избранное:

ocapi.event('favorite_product', {
  offer_external_id: '1ext',
});

Товар добавлен в избранное, связь по XML ID и внутреннему идентификатору торгового предложения в системе:
```
ocapi.event('favorite_product', {
  offer_id: 1,
  offer_xml_id: '1xml_id',
});
```

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

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

Нет

Да

Предыдущая статья

Настройка событий трекинга посетителей

Настройка событий для отслеживания визитов, просмотры страниц, клики и другие события на сайте без необходимости дополнительной интеграции с Google Analytics 4 и Яндекс.Метрикой.

Следующая статья

Подключение трекера к сайту без готового модуля CMS: порядок действий и отладка

Инструкция для случаев, когда трекер подключается к сайту со сторонней CMS или кастомной разработкой: базовая настройка, выбор способа отправки событий и проверка корректной передачи данных.

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

Содержание

1. Начало работы: объект ocapi

2. Отправка событий

2.1. Автоматически передаваемые данные

2.2. Создание нового клиента при отправке события

2.3. Использование параметров в сегментации

3. Типы событий и их параметры

3.1. Просмотр страницы (page_view)

3.2. Клик по элементу (click)

3.3. Регистрация (register)

3.4. Вход в аккаунт (login)

3.5. Запрос консультации (consult)

3.6. Открытие корзины (open_cart)

3.7. Отправка формы обратной связи (contact)

3.8. Изменение состояния корзины (cart)

3.9. Оформление заказа (order)

3.10. Подписка на рассылку (subscription)

3.11. Начало заполнения формы (form_start)

3.12. Отправка формы (form_submit)

3.13. Скачивание файла (file_download)

3.14. Обновление избранных товаров (favorite_product)

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

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

Скопировано

1. Начало работы: объект `ocapi`

3.1. Просмотр страницы (`page_view`)

3.2. Клик по элементу (`click`)

3.3. Регистрация (`register`)

3.4. Вход в аккаунт (`login`)

3.5. Запрос консультации (`consult`)

3.6. Открытие корзины (`open_cart`)

3.7. Отправка формы обратной связи (`contact`)

3.8. Изменение состояния корзины (`cart`)

3.9. Оформление заказа (`order`)

3.10. Подписка на рассылку (`subscription`)

3.11. Начало заполнения формы (`form_start`)

3.12. Отправка формы (`form_submit`)

3.13. Скачивание файла (`file_download`)

3.14. Обновление избранных товаров (`favorite_product`)