Техническое задание: Реализация GCLID

Спецификация интеграции отслеживания рекламных кликов на фронтенде (Next.js) и бэкенде (PHP + DLE) с передачей в источник сделки amoCRM.

1. Захват GCLID из URL и запись в сессию

amocrm-crmpro-uz/src/components/global/gclid-tracker.tsx

Компонент, отслеживающий появление параметра gclid в URL-адресе и сохраняющий его в sessionStorage.

"use client";

import { useSearchParams } from "next/navigation";
import { useEffect } from "react";

export default function GclidTracker() {
  const searchParams = useSearchParams();

  useEffect(() => {
    const gclid = searchParams.get("gclid");
    if (gclid) {
      sessionStorage.setItem("google_gclid", gclid);
    }
  }, [searchParams]);

  return null;
}

2. Обновление API клиента

amocrm-crmpro-uz/src/api/create-contact.api.ts

Расширяем тело запроса к бэкенду для передачи накопленного идентификатора клика.

export const createContact = (
	tag: CreateContactTag,
	body: CreateOfferDetailBody,
) => {
	return http.post<ResponseType<unknown>>("engine/ajax/crmpro.php", {
		json: {
			_m: "createLead",
			params: {
				name: body.name,
				phone: body.phone.replace("+", ""),
				domain: body.domain,
				title: body.title,
				tag: CreateContactTag[tag],
				gclid: body.gclid, // <-- Передаем GCLID в API-метод
			},
		},
		prefix: "https://mcrm.uz",
	});
};

3. Чтение сессии при отправке формы

amocrm-crmpro-uz/src/components/global/lead/lead-form.tsx

Считываем google_gclid из сессии пользователя в браузере при отправке формы.

const onSubmit = (values: LeadAmocrmSchema) => {
	startTransition(async () => {
		try {
			// 1. Получаем сохраненный клик-код из сессии браузера
			const gclid = typeof window !== "undefined" ? sessionStorage.getItem("google_gclid") : null;

			// 2. Передаем его в API-клиент
			const { ok } = await createContact(tag, {
				name: values.name,
				phone: values.phone,
				domain: window.location.hostname,
				title: "amoCRM",
				gclid: gclid, // <-- Передаем в запрос
			});
			// ...
		} catch (error) {
			console.error(error);
		}
	});
};

1. AJAX-обработчик Next.js запросов

amocrm-uzbekistan-uz/engine/ajax/crmpro.php

Принимаем переменную GCLID из тела AJAX-запроса от Next.js приложения.

function createLead(array $data): array
{
    extract($data);
    
    // Получаем и очищаем GCLID, если он передан в AJAX-запросе
    $gclid = isset($data['gclid']) ? clear($data['gclid']) : null;

    if (
        !is_string(clear($name)) ||
        !is_string(clear($title)) ||
        !is_string(clear($tag)) ||
        !is_string(clear($domain)) ||
        !is_string(clear($phone))
    ) throw new \Exception('Bad request', 400);

    // Передаем $gclid 6-м параметром
    createLeadAndLinkToCompanyAndContact($name, $phone, $title, $tag, $domain, $gclid);

    return [];
}

2. Передача GCLID как источника сделки в amoCRM

amocrm-uzbekistan-uz/engine/ajax/crmpro-amocrm-api.php

Отправляем оффлайн-идентификатор клика в блок _embedded.source.external_id при формировании запроса к amoCRM API v4.

function createLeadAndLinkToCompanyAndContact(
    string $fullname, 
    string $phone, 
    string $type, 
    string $tag, 
    string $domain,
    ?string $gclid = null
): bool
{
    // ...
    $leadData = [
        "name" => $leadName,
        "status_id" => (int) $lead_status_id,
        "pipeline_id" => (int) $lead_pipeline_id,
        "_embedded" => [
            'contacts' => [['id' => (int) $contactId]],
            "tags" => [["name" => $tag]]
        ]
    ];

    // КРИТИЧЕСКИЙ БЛОК: Запись GCLID в источник сделки amoCRM
    if (!empty($gclid)) {
        $leadData["_embedded"]["source"] = [
            "external_id" => $gclid
        ];
    }

    $response = performCurlRequest($leadsApiUrl, 'POST', [$leadData]);
    // ...
}

3. Модификация форм сайта DLE (PHP)

amocrm-uzbekistan-uz/engine/modules/mod/amocrm-api.php

Добавляем аналогичную поддержку для лидов, создаваемых напрямую через DLE-сайт.

// 1. В обработчике отправки:
$gclid = isset($_POST['gclid']) ? trim($_POST['gclid']) : null;
$dealId = createLeadComplex($firstname, $phone, $secondname, $middlename, $email, $telegram, $gclid);

// 2. В теле функции createLeadComplex:
if (!empty($gclid)) {
    $leadData["_embedded"]["source"] = [
        "external_id" => $gclid
    ];
}