Как передать данные в сквозную аналитику CRM

Scope: crm

Кто может выполнять методы: пользователь с правом на создание или изменение объекта CRM

Данные сквозной аналитики помогают связать лид, сделку, контакт, компанию или коммерческое предложение с источником обращения и маршрутом клиента. В CRM можно передать только источник через UTM-поля или полный трейс с данными посещений.

Трейс — это набор данных о пути клиента до обращения: источник перехода, посещенные страницы и другие параметры визита. По трейсу CRM понимает, откуда пришел клиент и какие действия он совершил перед созданием объекта.

Чтобы передать данные в аналитику CRM, выберите способ:

Сценарий состоит из четырех шагов.

1. Выбрать, достаточно ли UTM-полей или нужен полный трейс
2. Получить строку TRACE через b24Tracker.guest.getTrace(), если нужно передать полный маршрут клиента
3. Передать TRACE при создании объекта, если метод создания поддерживает это поле, или привязать трейс к готовым объектам методом crm.tracking.trace.add
4. Сохранить идентификатор трейса из result, если его нужно удалить позже методом crm.tracking.trace.delete

Что нужно до началаЧто нужно до начала

• входящий вебхук или локальное приложение со scope crm
• права пользователя на создание или изменение объекта CRM, к которому нужно передать данные сквозной аналитики
• скрипт сквозной аналитики Битрикс24 установлен на страницах сайта, где собирается маршрут клиента
• вызовы REST выполняются на стороне сервера, если используете вебхук: путь вебхука нельзя раскрывать в браузере или публичном репозитории
• идентификаторы уже созданных объектов CRM, если трейс нужно привязать методом crm.tracking.trace.add

1. Передайте UTM-источник1. Передайте UTM-источник

Если для отчета достаточно рекламного источника, передайте UTM_SOURCE при создании объекта CRM. Значение должно совпадать с настроенным источником в сквозной аналитике.

UTM-поля есть у основных объектов CRM. Проверьте список полей в описании метода, которым создаете объект:

• crm.lead.add — лид
• crm.deal.add — сделка
• crm.contact.add — контакт
• crm.company.add — компания
• crm.quote.add — коммерческое предложение

Такой способ подходит, когда нужно передать только канал привлечения: рекламную систему, кампанию, объявление или ключевое слово.

Универсальный метод crm.item.add принимает UTM-поля в camelCase, например utmSource, и сохраняет их в объекте. Но он не формирует путь клиента в сквозной аналитике: трейс не создается, а поля TRACE в методе нет.

Чтобы данные попали в сквозную аналитику, создавайте объект специальными методами CRM или отдельно привяжите трейс через crm.tracking.trace.add.

2. Передайте полный трейс при создании объекта2. Передайте полный трейс при создании объекта

Полный трейс содержит данные о маршруте клиента: источник, страницы сайта и другие параметры посещения. Значение для TRACE можно получить на сайте через JS-код сквозной аналитики Битрикс24:

b24Tracker.guest.getTrace()

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

Если метод создания объекта поддерживает поле TRACE, передайте в него полученную строку. Такой вариант подходит, когда один объект создается сразу после заполнения формы. Например, заявка с сайта создает лид или контакт, а данные сквозной аналитики передаются вместе с основными полями объекта.

Подробные параметры и примеры смотрите в описании метода создания нужного объекта. В практических сценариях показано, как передать TRACE при создании:

• лида
• сделки и контакта

3. Свяжите объекты одним трейсом3. Свяжите объекты одним трейсом

Если сценарий создает несколько связанных объектов, сначала сохраните данные клиента, затем свяжите их с одним трейсом методом crm.tracking.trace.add.

Например, форма на сайте может создать контакт и сделку. После создания объектов передайте в crm.tracking.trace.add:

• TRACE — строку с данными сквозной аналитики
• ENTITIES — список объектов, которые нужно связать с трейсом

Вызовы REST выполняйте на стороне сервера, чтобы не раскрывать вебхук в браузере. Строку TRACE соберите на сайте через b24Tracker.guest.getTrace() и передайте на сервер вместе с данными формы.

// npm install @bitrix24/b24jssdk
import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your-domain.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/')

// contactId и dealId получены при создании объектов, trace — из b24Tracker.guest.getTrace()
const response = await $b24.actions.v2.call.make({
    method: 'crm.tracking.trace.add',
    params: {
        TRACE: trace,
        ENTITIES: [
            { TYPE: 'CONTACT', ID: contactId },
            { TYPE: 'DEAL', ID: dealId },
        ],
    },
    requestId: 'trace-add',
})

if (!response.isSuccess) {
    throw new Error(response.getErrorMessages().join('; '))
}

const traceId = response.getData().result
console.log('Trace ID:', traceId)

$b24.destroy()

# pip install b24pysdk
from b24pysdk import Client, BitrixWebhook
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

client = Client(BitrixWebhook(
    domain="your-domain.bitrix24.ru",
    webhook_token="1/xxxxxxxxxxxxxxxx",
))

try:
    bitrix_response = client.crm.tracking.trace.add(
        trace=trace,
        entities=[
            {"TYPE": "CONTACT", "ID": contact_id},
            {"TYPE": "DEAL", "ID": deal_id},
        ],
    ).response
    trace_id = bitrix_response.result
    print("Trace ID:", trace_id)
except BitrixAPIError as error:
    print(
        "Bitrix API error",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Bitrix SDK error: {error.message}")
except Exception as error:
    print(f"Unexpected error: {error}")

<?php
// composer require bitrix24/b24phpsdk:"^3.0"
require_once 'vendor/autoload.php';

use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('b24');
$log->pushHandler(new StreamHandler('php://stdout'));

$b24 = (new ServiceBuilderFactory(new EventDispatcher(), $log))
    ->initFromWebhook('https://your-domain.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/');

// Метода crm.tracking.* нет среди типизированных сервисов SDK,
// поэтому вызываем его напрямую через ядро: $b24->core->call(...)
$response = $b24->core->call('crm.tracking.trace.add', [
    'TRACE' => $trace,
    'ENTITIES' => [
        ['TYPE' => 'CONTACT', 'ID' => $contactId],
        ['TYPE' => 'DEAL', 'ID' => $dealId],
    ],
]);

// Скалярный результат (ID трейса) ядро оборачивает в массив
$traceId = $response->getResponseData()->getResult()[0];
echo 'Trace ID: ' . $traceId;

Этот способ подходит и для объектов, созданных универсальным методом crm.item.add: трейс к ним можно привязать после создания.

Метод вернет идентификатор созданного трейса. Его можно сохранить на стороне интеграции, если в сценарии нужно позже удалить трейс или очистить привязку.

{
    "result": 341
}

Сохраните значение result. В примере это 341 — идентификатор, который нужно передать в параметр id метода crm.tracking.trace.delete, если трейс нужно удалить.

Удаление трейсаУдаление трейса

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

Для удаления используйте метод crm.tracking.trace.delete. Укажите идентификатор трейса id, который вернул метод crm.tracking.trace.add.

const response = await $b24.actions.v2.call.make({
    method: 'crm.tracking.trace.delete',
    params: { id: traceId },
    requestId: 'trace-delete',
})

if (!response.isSuccess) {
    throw new Error(response.getErrorMessages().join('; '))
}

bitrix_response = client.crm.tracking.trace.delete(traceId).response
result = bitrix_response.result
print(result)

$response = $b24->core->call('crm.tracking.trace.delete', [
    'id' => $traceId,
]);

$isDeleted = $response->getResponseData()->getResult()[0];

При успешном удалении метод вернет null в поле result.

{
    "result": null
}

Проверим результатПроверим результат

Проверка зависит от выбранного способа передачи данных.

Если объект создан, но трейс не привязан, сценарий завершился частично. Проверьте объект перед повторным запуском, чтобы не создать дубликат.

Обработка ошибокОбработка ошибок

Метод crm.tracking.trace.add возвращает код ERROR_CORE в поле error, если не прошла проверка параметров TRACE, ENTITIES или прав на объекты. Конкретная причина приходит в поле error_description.

В последнем сообщении CONTACT и 123 приведены для примера. Метод подставляет фактические тип и идентификатор объекта.

Метод crm.tracking.trace.delete вернет ошибку ERROR_CORE с описанием Parameter `id` required., если не передать идентификатор трейса или передать пустое значение. Проверьте, что id взят из поля result метода crm.tracking.trace.add, и повторите удаление.

Системные REST-ошибки авторизации, прав и лимитов могут иметь другие коды. Если REST-вызов вернул ошибку, не повторяйте весь сценарий сразу: сначала проверьте, какие объекты уже созданы и был ли создан трейс.

Продолжите изучениеПродолжите изучение

• Создать трейс сквозной аналитики crm.tracking.trace.add
• Удалить трейс сквозной аналитики crm.tracking.trace.delete
• Как использовать сквозную аналитику при создании лида
• Как связать контакт и сделку со сквозной аналитикой