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

Scope: crm

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

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

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

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

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
}

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

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

Для удаления используйте метод 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];