Настройка серверной передачи конверсий из Keitaro в Яндекс.Метрику (2025)

В этой статье я расскажу, как настроить серверную передачу данных о конверсиях (лидах и продажах) из трекера Keitaro в Яндекс.Метрику с использованием CDP Events API. Это решение позволяет связать офлайн-конверсии с конкретными посетителями сайта, используя их ClientID из Яндекс.Метрики, что обеспечивает высокую точность аналитики.

Описание файлов

Для реализации вам понадобятся три основных файла:

config.php — файл конфигурации, содержащий настройки для Яндекс.Метрики:

YM_COUNTER_ID — ID вашего счетчика в Яндекс.Метрике.
YM_OAUTH_TOKEN — OAuth-токен с правами metrika:write_cdp_data.

handler.php — основной скрипт, который принимает S2S-постбэки от Keitaro и отправляет события в Яндекс.Метрику, используя ClientID для привязки.
index.php — файл для просмотра логов, читающий данные из yandex_log.txt и отображающий их в удобном веб-интерфейсе.

Схема работы

Система работает следующим образом:

Пользователь заходит на ваш прелендинг, где срабатывает счетчик Яндекс.Метрики и JavaScript-код.
JavaScript получает ClientID пользователя (_ym_uid) и добавляет его к ссылкам на Keitaro в виде параметра sub_id_16.
Keitaro сохраняет sub_id_16 (ClientID) и перенаправляет пользователя на оффер партнерской сети.
После совершения конверсии партнерская сеть отправляет S2S-постбэк в Keitaro.
Keitaro вызывает handler.php, передавая данные о конверсии, включая ClientID.
Скрипт handler.php отправляет событие в Яндекс.Метрику через CDP Events API.

Установка и настройка

Шаг 1: Размещение файлов

Скопируйте файлы config.php, handler.php и index.php в папку вашего локального лендинга в Keitaro. Например, если ваш лендинг имеет ID 2, путь будет:

/var/www/keitaro/landers/2/

Шаг 2: Настройка прелендинга

Добавьте следующий JavaScript-код на прелендинг перед закрывающим тегом </body>:

<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function () {
    const ymCounterId = 12345678; // Замените на ваш ID счетчика Яндекс.Метрики
    const clientIdParam = 'sub_id_16';

    function appendClientIdToLinks(clientId) {
        const links = document.querySelectorAll('a.keitaro-link'); // Добавьте класс keitaro-link к ссылкам на Keitaro
        links.forEach(function(link) {
            try {
                const url = new URL(link.href);
                url.searchParams.set(clientIdParam, clientId);
                link.href = url.toString();
            } catch (e) {
                // Игнорируем ошибки для невалидных URL
            }
        });
    }

    if (typeof ym === 'function') {
        ym(ymCounterId, 'getClientID', function(clientId) {
            if (clientId) {
                appendClientIdToLinks(clientId);
            }
        });
    }
});
</script>

Замените 12345678 на ваш ID счетчика Яндекс.Метрики.
Убедитесь, что ссылки на Keitaro имеют класс keitaro-link, или измените селектор в коде.

Шаг 3: Настройка config.php

Откройте config.php и укажите ваши данные:

<?php
/**
 * Configuration File for the Yandex.Metrika CDP API Handler.
 * v7.0 Yandex-Only, Corrected Edition
 */

// ID вашего счетчика в Яндекс.Метрике.
define('YM_COUNTER_ID', '12345678'); // Замените на ваш ID счетчика

// OAuth-токен для доступа к API с правами: metrika:write_cdp_data
define('YM_OAUTH_TOKEN', 'y0_ВАШ_ТОКЕН_ИЗ_ЯНДЕКСА'); // Замените на ваш токен

Как получить OAuth-токен:

Перейдите в Яндекс.OAuth.
Создайте приложение с правами metrika:write_cdp_data.
Получите токен для вашего приложения.

Шаг 4: Настройка постбэков в Keitaro

В кампании Keitaro настройте S2S-постбэки:

Для лидов:http://127.0.0.1/landers/2/handler.php?status=lead&yclid={yclid}&sub_id_16={sub_id_16}
Для продаж:http://127.0.0.1/landers/2/handler.php?status=sale&payout={payout}&currency={currency}&yclid={yclid}&sub_id_16={sub_id_16}

Если Keitaro и скрипт находятся на разных серверах, замените 127.0.0.1 на ваш домен.

Логирование

Логи записываются в файл yandex_log.txt в той же папке, где находятся скрипты.
Для просмотра логов откройте в браузере: http://ВАШ_ДОМЕН/landers/2/index.php.
Логи содержат:

Входящие данные от Keitaro.
Отправленные данные в Яндекс.
Ответы от API Яндекса (успешный ответ включает "uploading_status": "OK").

Возможные проблемы и решения

"ClientID is missing":

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

Ошибка 403 (Forbidden):

Проверьте валидность YM_OAUTH_TOKEN.
Убедитесь, что токен имеет права metrika:write_cdp_data.

Ошибка 400 (Bad Request):

Проверьте правильность YM_COUNTER_ID.
Убедитесь, что данные в запросе соответствуют формату API.

Заключение

Забрать готовые скрипты можно отсюда (работоспособность гарантируется только на момент написания статьи). Настройка серверной передачи данных из Keitaro в Яндекс.Метрику позволяет точно отслеживать конверсии, связывая их с визитами пользователей. Это улучшает аналитику и помогает оптимизировать рекламные кампании. Регулярно проверяйте логи и тестируйте настройку с тестовыми конверсиями для уверенности в ее работе.