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

Маркетинг

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

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

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

Скопировано

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

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

Важно!

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

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

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

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

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

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

Синтаксис:

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметры:

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

Примеры:

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

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

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

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

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

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

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

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

Параметры:

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

Примеры:

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

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

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

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

Параметры:

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

Примеры:

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

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

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

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

Параметры:

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

Примеры:

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

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

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

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

Параметры:

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

Примеры:

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

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

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
      // Цена не указана, будет взята из системы
    }
  ]
});

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

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

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

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

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

Параметры:

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

Примеры:

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

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

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

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

Параметры:

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

Примеры:

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

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

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

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

Нет

Да

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

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

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

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

Оглавление

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Скопировано

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

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

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

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

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

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

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

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

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

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

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

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

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

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