Руководство по интеграции и отслеживанию конверсий

Полное руководство по интеграции Simple TDS с вашими источниками трафика и партнерскими сетями, включая все методы отслеживания конверсий.

Структура URL трафика

Формат базового URL

Весь трафик в кампании Simple TDS следует этому шаблону URL:

https://yourdomain.com/{campaign_token}/

Пример:

https://track.example.com/abc123def456/

Где:

Передача параметров в целевой URL

Вы можете передать любые параметры запроса через URL трафика, и они будут автоматически перенаправлены в целевой URL вместе с системным click_id.

Пример:

https://track.example.com/abc123def456/?utm_source=facebook&utm_campaign=summer2024&sub1=adset123

Все параметры (utm_source, utm_campaign, sub1) будут переданы в конечный URL назначения.

Доступные макросы в целевых URL

При настройке целевых URL в Simple TDS вы можете использовать макросы, которые будут динамически заменены фактическими значениями:

Системные макросы

Макрос Описание Пример значения
{click_id} Уникальный идентификатор клика (для отслеживания конверсий) a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5
{timestamp} Текущая временная метка Unix в миллисекундах 1704067200000
{random} Случайное число (0-999999) 742839
{date} Текущая дата (формат YYYY-MM-DD) 2025-01-01
{time} Текущее время (формат HH:MM:SS) 14:30:45
{CLICK_ID} Уникальный идентификатор клика (псевдоним для {click_id}, для URL рекламодателей) a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5
{SOURCES} Домен реферера — домен источника трафика (пусто при прямом заходе) facebook.com
{GEO} Код страны посетителя (ISO 3166-1 alpha-2) US
{CAMPAIGN_ID} Числовой ID текущей кампании 42
{referrer} Полный URL реферера (пустая строка при прямом трафике) https://facebook.com/ads/123

Макросы параметров запроса

Любой параметр, переданный в URL трафика, может использоваться как макрос:

Макрос Описание Пример
{utm_source} Источник трафика из URL Из ?utm_source=facebookfacebook
{utm_campaign} Название кампании из URL Из ?utm_campaign=summersummer
{sub1} - {sub9} Пользовательские sub-ID Из ?sub1=123123

Пример целевого URL с макросами:

https://offer.example.com/lp?source={utm_source}&campaign={utm_campaign}&clickid={click_id}&ts={timestamp}

Результат (когда трафик приходит с ?utm_source=google&utm_campaign=promo):

https://offer.example.com/lp?source=google&campaign=promo&clickid=a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5&ts=1704067200000

Пользовательские параметры Sub-ID (std1-std9)

Simple TDS автоматически отслеживает 9 пользовательских параметров sub-ID: std1, std2, std3, ... std9

Они полезны для отслеживания пользовательских данных:

Пример:

https://track.example.com/abc123def456/?std1=placement_A&std2=creative_001&std3=audience_25-34

Эти значения:

Методы отслеживания конверсий

Simple TDS поддерживает три метода отслеживания конверсий. Все методы требуют click_id, который автоматически добавляется к целевым URL.

Метод 1: Постбек URL (Server-to-Server)

Рекомендуется для: Партнерских сетей, прямых офферов с серверным отслеживанием

Формат URL

GET https://yourdomain.com/c/postback

Параметры

Параметр Обязательный Тип Описание
click_id Да* String Уникальный идентификатор клика (формат UUID)
campaign_id Да* Integer ID кампании (если click_id недоступен)
conversion_type Нет String Тип конверсии (по умолчанию: confirmed)
conversion_value Нет Number Сумма дохода/выплаты
external_id Нет String Внешний ID транзакции/конверсии

*Требуется либо click_id, либо campaign_id. Использование click_id настоятельно рекомендуется для точного отслеживания.

Примеры постбек URL

Базовая конверсия:

https://track.example.com/c/postback?click_id={clickid}

Конверсия с доходом:

https://track.example.com/c/postback?click_id={clickid}&conversion_value=25.50

Конверсия с типом и внешним ID:

https://track.example.com/c/postback?click_id={clickid}&conversion_type=sale&conversion_value=99.99&external_id=ORDER-12345

Интеграция с популярными партнерскими сетями

MaxBounty:

https://track.example.com/c/postback?click_id=[SUBID]&conversion_value=[PAYOUT]

CrakRevenue:

https://track.example.com/c/postback?click_id=[s1]&conversion_value=[payout]&external_id=[transaction_id]

ClickDealer:

https://track.example.com/c/postback?click_id={clickid}&conversion_value={payout}

CPALead:

https://track.example.com/c/postback?click_id=[subid]&conversion_value=[payout]

Примечание: Замените заполнители макросов (например, [SUBID], {clickid}) на фактические макросы, используемые вашей партнерской сетью.

Ответ

Успех:

{
  "success": true,
  "conversion_id": 12345
}

Обновлена существующая конверсия:

{
  "success": true,
  "conversion_id": 12345,
  "updated": true
}

Ошибка:

{
  "success": false,
  "message": "Click not found"
}

Метод 2: Пиксельное отслеживание (изображение)

Рекомендуется для: Лендингов, страниц благодарности, страниц подтверждения

Формат URL

<img src="https://yourdomain.com/c/pixel.gif?click_id={clickid}" width="1" height="1" />

Параметры

Те же, что и в методе постбека, но поддерживает устаревшие имена параметров:

Параметр Псевдоним Тип Описание
click_id - String Уникальный идентификатор клика
conversion_value amount Number Сумма дохода
conversion_type status String Статус конверсии
external_id transaction_id String Внешний ID

Пример реализации

Базовый пиксель (прозрачное изображение 1x1):

<!DOCTYPE html>
<html>
<head>
    <title>Спасибо!</title>
</head>
<body>
    <h1>Спасибо за вашу покупку!</h1>
    <p>Ваш заказ подтвержден.</p>

    <!-- Пиксель отслеживания конверсий -->
    <img src="https://track.example.com/c/pixel.gif?click_id=a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5"
         width="1" height="1" style="display:none;" />
</body>
</html>

Пиксель с отслеживанием дохода:

<img src="https://track.example.com/c/pixel.gif?click_id=a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5&conversion_value=49.99&conversion_type=sale"
     width="1" height="1" style="display:none;" />

Когда использовать пиксельное отслеживание

Преимущества:

Ограничения:

Метод 3: JavaScript трекер

Рекомендуется для: Расширенного отслеживания, динамических значений конверсий, клиентских приложений

Формат URL

<script src="https://yourdomain.com/c/js?click_id={clickid}"></script>

Базовая реализация

<!DOCTYPE html>
<html>
<head>
    <title>Подтверждение</title>
</head>
<body>
    <h1>Спасибо!</h1>

    <!-- JavaScript трекер конверсий -->
    <script>
        var clickId = 'a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5'; // Получено из URL или cookie
        var conversionValue = 29.99;
        var conversionType = 'sale';

        var script = document.createElement('script');
        script.src = 'https://track.example.com/c/js?click_id=' + clickId +
                     '&conversion_value=' + conversionValue +
                     '&conversion_type=' + conversionType;
        document.head.appendChild(script);
    </script>
</body>
</html>

Расширенное использование: Динамическое отслеживание конверсий

<script>
// Получить click_id из параметра URL
function getClickId() {
    const urlParams = new URLSearchParams(window.location.search);
    return urlParams.get('click_id');
}

// Отследить конверсию с динамическим значением
function trackConversion(value, type, externalId) {
    const clickId = getClickId();
    if (!clickId) {
        console.error('Click ID не найден');
        return;
    }

    const params = new URLSearchParams({
        click_id: clickId,
        conversion_value: value,
        conversion_type: type || 'confirmed',
        external_id: externalId || ''
    });

    const script = document.createElement('script');
    script.src = 'https://track.example.com/c/js?' + params.toString();
    document.head.appendChild(script);
}

// Пример: Отслеживание при отправке формы
document.getElementById('purchaseForm').addEventListener('submit', function(e) {
    e.preventDefault();

    const amount = document.getElementById('amount').value;
    const orderId = document.getElementById('orderId').value;

    trackConversion(amount, 'sale', orderId);

    // Продолжить отправку формы
    this.submit();
});
</script>

Когда использовать JavaScript трекер

Работа с Click ID

Что такое Click ID?

click_id - это уникальный идентификатор (формат UUID v4), автоматически генерируемый Simple TDS для каждого клика. Он необходим для отслеживания конверсий.

Пример click_id:

a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5

Почему Click ID важен

  1. Уникальная идентификация: Связывает конверсии с конкретными кликами
  2. Точная атрибуция: Отслеживает, какая кампания/поток/таргет сгенерировал конверсию
  3. Предотвращение дубликатов: Гарантирует, что конверсии не учитываются несколько раз
  4. Статистика: Обеспечивает детальную отчетность по конверсиям

Передача Click ID на лендинги

Simple TDS автоматически добавляет click_id к целевым URL. Вам не нужно ничего делать, если вы используете поведение по умолчанию.

Поток трафика:

Пользователь кликает → https://track.example.com/abc123def456/?utm_source=facebook
              ↓
Simple TDS обрабатывает фильтры и выбирает таргет
              ↓
Редирект на → https://landing.example.com/?click_id=a3f8b2c1d4&utm_source=facebook

Если вы используете макросы в конфигурации целевого URL:

Целевой URL: https://landing.example.com/?id={click_id}&source={utm_source}
Результат:   https://landing.example.com/?id=a3f8b2c1d4&source=facebook

Сохранение Click ID для отслеживания конверсий

Метод 1: Параметр URL (Рекомендуется)

Сохраните click_id из URL и используйте его позже для отслеживания конверсий.

Пример JavaScript:

// Получить click_id из URL
function getClickId() {
    const urlParams = new URLSearchParams(window.location.search);
    return urlParams.get('click_id');
}

// Сохранить в sessionStorage
const clickId = getClickId();
if (clickId) {
    sessionStorage.setItem('tds_click_id', clickId);
}

// Позже: Получить для отслеживания конверсий
const storedClickId = sessionStorage.getItem('tds_click_id');

Метод 2: Хранение в Cookie

Сохранить в cookie для отслеживания на нескольких страницах.

Пример JavaScript:

// Установить cookie с click_id
function setClickIdCookie(clickId) {
    const expiryDays = 30;
    const date = new Date();
    date.setTime(date.getTime() + (expiryDays * 24 * 60 * 60 * 1000));
    const expires = "expires=" + date.toUTCString();
    document.cookie = "tds_click_id=" + clickId + ";" + expires + ";path=/";
}

// Получить click_id из URL и сохранить в cookie
const urlParams = new URLSearchParams(window.location.search);
const clickId = urlParams.get('click_id');
if (clickId) {
    setClickIdCookie(clickId);
}

// Получить из cookie
function getClickIdFromCookie() {
    const name = "tds_click_id=";
    const decodedCookie = decodeURIComponent(document.cookie);
    const ca = decodedCookie.split(';');
    for (let i = 0; i < ca.length; i++) {
        let c = ca[i];
        while (c.charAt(0) == ' ') {
            c = c.substring(1);
        }
        if (c.indexOf(name) == 0) {
            return c.substring(name.length, c.length);
        }
    }
    return null;
}

Метод 3: Скрытое поле формы

Передать click_id через формы.

Пример HTML:

<form id="signupForm" action="/process" method="POST">
    <input type="text" name="email" placeholder="Email" required>
    <input type="password" name="password" placeholder="Пароль" required>

    <!-- Скрытое поле с click_id -->
    <input type="hidden" name="click_id" id="clickIdField" value="">

    <button type="submit">Зарегистрироваться</button>
</form>

<script>
// Заполнить скрытое поле click_id из URL
const urlParams = new URLSearchParams(window.location.search);
const clickId = urlParams.get('click_id');
if (clickId) {
    document.getElementById('clickIdField').value = clickId;
}
</script>

Типичные сценарии интеграции

Сценарий 1: Прямая ссылка (без лендинга)

Настройка:

Источник трафика → Simple TDS → Партнерский оффер

Конфигурация:

  1. Создать кампанию в Simple TDS
  2. Добавить поток с соответствующими фильтрами
  3. Добавить таргет с URL партнерского оффера

Пример целевого URL:

https://affiliate-network.com/offer?affid=12345&clickid={click_id}

Постбек URL (настроить в партнерской сети):

https://track.example.com/c/postback?click_id=[SUBID]&conversion_value=[PAYOUT]

Замените [SUBID] и [PAYOUT] на макросы сети.

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

Настройка:

Источник трафика → Simple TDS → Ваш лендинг → Оффер

Конфигурация:

Создать кампанию и поток в Simple TDS

Настроить целевой URL на ваш лендинг:

https://yourlanding.com/?offer_id=123&click_id={click_id}&source={utm_source}

На вашем лендинге сохраните click_id:

<script>
// Сохранить click_id из URL
const urlParams = new URLSearchParams(window.location.search);
const clickId = urlParams.get('click_id');
if (clickId) {
    sessionStorage.setItem('tds_click_id', clickId);
}
</script>

Когда пользователь отправляет форму, отследите конверсию:

<script>
document.getElementById('leadForm').addEventListener('submit', function(e) {
    e.preventDefault();

    const clickId = sessionStorage.getItem('tds_click_id');
    if (clickId) {
        // Отследить конверсию пикселем
        const pixel = new Image();
        pixel.src = 'https://track.example.com/c/pixel.gif?click_id=' + clickId +
                    '&conversion_type=lead';
        pixel.onload = function() {
            // Перенаправить на оффер после отслеживания
            window.location.href = 'https://offer.example.com/?subid=' + clickId;
        };
    }
});
</script>

Сценарий 3: Многошаговая воронка

Настройка:

Трафик → Simple TDS → Лендинг → Пре-лендинг → Оффер

Реализация:

Лендинг (шаг 1):
<!-- Сохранить click_id в sessionStorage -->
<script>
const urlParams = new URLSearchParams(window.location.search);
const clickId = urlParams.get('click_id');
if (clickId) {
    sessionStorage.setItem('tds_click_id', clickId);
}

// Передать на следующий шаг
function goToNextStep() {
    const clickId = sessionStorage.getItem('tds_click_id');
    window.location.href = '/prelander?click_id=' + clickId;
}
</script>
Пре-лендинг (шаг 2):
<!-- Получить и сохранить click_id -->
<script>
const urlParams = new URLSearchParams(window.location.search);
let clickId = urlParams.get('click_id');

// Резервный вариант из sessionStorage, если нет в URL
if (!clickId) {
    clickId = sessionStorage.getItem('tds_click_id');
} else {
    sessionStorage.setItem('tds_click_id', clickId);
}

function goToOffer() {
    const clickId = sessionStorage.getItem('tds_click_id');
    window.location.href = 'https://offer.example.com/?subid=' + clickId;
}
</script>
Страница благодарности (после конверсии):
<!-- Отследить конверсию -->
<script>
const clickId = sessionStorage.getItem('tds_click_id');
if (clickId) {
    const pixel = new Image();
    pixel.src = 'https://track.example.com/c/pixel.gif?click_id=' + clickId +
                '&conversion_value=25.00&conversion_type=sale';
}
</script>

Сценарий 4: Интеграция с партнерской сетью

Настройка:

Настроить постбек в партнерской сети для отслеживания конверсий обратно в Simple TDS

Шаги:

Передать ваш click_id в партнерскую сеть:

В целевом URL Simple TDS:

https://network.com/click?affid=12345&subid={click_id}

Настроить постбек в партнерской сети:

Большинство сетей имеют настройку "Постбек URL" или "Обратный вызов конверсии". Настройте его как:

https://track.example.com/c/postback?click_id=[SUBID]&conversion_value=[PAYOUT]&conversion_type=[STATUS]&external_id=[TRANSACTION_ID]

Замените заполнители на специфичные для сети макросы:

Сеть Макрос SubID Макрос выплаты Макрос статуса
MaxBounty [SUBID] [PAYOUT] [STATUS]
CrakRevenue [s1] [payout] [status]
ClickDealer {clickid} {payout} {status}
A4D {s1} {payout} N/A

Протестировать интеграцию:

Большинство сетей предоставляют функцию тестового постбека. Используйте ее для проверки правильности отслеживания конверсий.

Сценарий 5: S2S постбек в источник трафика (RTB-сети)

Кейс: Вы покупаете трафик в RTB-сети (RTB Panda, ClickBaza, PropellerAds и др.), которая требует постбек конверсии на свой сервер, когда конверсия фиксируется на оффере.

Полный поток данных

RTB-сеть ──[посетитель + ?clickid=XYZ]──→ URL кампании TDS
                                                  │
                                          TDS сохраняет XYZ в click.query_params
                                                  │
                                          TDS редиректит на оффер
                                                  │
Оффер ──[GET /c/postback?click_id={tds_uuid}]──→ TDS
                                                  │
TDS записывает конверсию И отправляет upstream S2S:
TDS ──[GET https://postback.rtbpanda.com/postback?clickid=XYZ&payout=25.00&status=confirmed]──→ RTB-сеть

Шаг 1: Получите шаблон постбек URL от источника трафика

В дашборде RTB Panda / ClickBaza найдите раздел "S2S Postback". Шаблон выглядит так:

https://postback.rtbpanda.com/postback?clickid={CLICK_ID}&payout={PAYOUT}&status={STATUS}

Шаг 2: Переведите названия макросов в TDS-макросы

Источник трафикаИх параметр click IDTDS-макрос
RTB Pandaclickid{clickid}
ClickBazaclickid{clickid}
PropellerAdsclick_id{click_id}

Результат для RTB Panda:

https://postback.rtbpanda.com/postback?clickid={clickid}&payout={payout}&status={status}

Шаг 3: Вставьте URL в Настройки кампании → S2S Postback URL

Шаг 4: Настройте URL кампании в RTB-сети

https://yourdomain.com/{campaign_token}/?clickid={CLICK_ID}

Замените {CLICK_ID} на реальный макрос сети.

Шаг 5: Протестируйте полную цепочку

  1. Откройте тестовый URL: https://yourdomain.com/{token}/?clickid=test123
  2. Запишите TDS click_id (UUID) из логов кликов
  3. Отправьте тестовую конверсию: GET /c/postback?click_id={uuid}&conversion_value=10
  4. Проверьте логи сервера — должна быть строка [S2S] Postback fired

Устранение неполадок

Конверсия не отслеживается

Проблема: Постбек отправлен, но конверсия не записана

Возможные причины:

1. Неправильный формат click_id
  • Проверьте, что click_id является корректным UUID
  • Проверьте на лишние символы или усечение

Решение: Протестируйте с известным click_id из отчетов кликов

2. Click_id не найден в базе данных
  • Клик может быть слишком старым (политика хранения данных)
  • Клик никогда не был записан (бот-трафик отфильтрован)

Решение: Проверьте отчеты кликов, чтобы убедиться, что click_id существует

3. Постбек URL настроен неправильно
  • Неправильный домен
  • Отсутствуют обязательные параметры

Решение: Протестируйте постбек вручную:

curl "https://track.example.com/c/postback?click_id=YOUR_CLICK_ID&conversion_value=10"

Ожидаемый ответ:

{"success": true, "conversion_id": 12345}
4. Брандмауэр сети блокирует постбек
  • Некоторые серверы блокируют исходящие соединения

Решение: Проверьте логи сервера, добавьте IP Simple TDS в белый список при необходимости

Проблема: Пиксель не загружается

Возможные причины:

1. Блокировщик рекламы

Многие блокировщики рекламы блокируют пиксели отслеживания

Решение: Используйте server-to-server постбек для надежного отслеживания

2. Смешанный контент HTTPS/HTTP

Загрузка HTTP пикселя на HTTPS странице

Решение: Всегда используйте HTTPS для URL пикселей

3. Ошибка JavaScript предотвращает загрузку пикселя

Решение: Проверьте консоль браузера на наличие ошибок

Click ID отсутствует

Проблема: click_id отсутствует в целевом URL

Возможные причины:

1. Макрос настроен неправильно

Используется неправильный синтаксис макроса

Решение: Используйте макрос {click_id} в целевом URL или положитесь на автоматическую передачу параметров

2. Целевой URL уже имеет параметр click_id

Simple TDS не будет добавлять дублирующие параметры

Решение: Удалите click_id из шаблона целевого URL, позвольте Simple TDS добавить его

3. Параметр удаляется редиректом

Промежуточные редиректы могут удалять параметры

Решение: Протестируйте полную цепочку редиректов, убедитесь, что все редиректы сохраняют параметры запроса

Проблема: click_id теряется в многостраничном потоке

Решение:

Используйте sessionStorage или cookies для сохранения click_id между страницами:

// Сохранить на первой странице
const urlParams = new URLSearchParams(window.location.search);
const clickId = urlParams.get('click_id');
if (clickId) {
    sessionStorage.setItem('tds_click_id', clickId);
}

// Получить на любой странице
const storedClickId = sessionStorage.getItem('tds_click_id');

Распространенные ошибки

Ошибка: "Either click_id or campaign_id is required"

Причина: Постбек отправлен без обязательных параметров

Решение: Включите параметр click_id:

https://track.example.com/c/postback?click_id=YOUR_CLICK_ID

Ошибка: "Click not found"

Причина: click_id не существует в базе данных

Возможные причины:

  • Click_id неправильный или поврежден
  • Клик старше срока хранения
  • Клик был от бот-трафика (не записан)

Решение:

  • Проверьте формат и значение click_id
  • Проверьте, что клик существует в статистике
  • Используйте свежий click_id для тестирования

Ошибка: "Invalid conversion"

Причина: Проверка конверсии не прошла

Возможные причины:

  • conversion_value не является числом
  • conversion_type не является строкой
  • Запрос с подозрительного IP

Решение:

  • Проверьте типы параметров
  • Протестируйте с корректными значениями
  • Проверьте настройки валидатора конверсий

Ошибка: "Campaign not found"

Причина: Используется параметр campaign_id, но кампания не существует или неактивна

Решение:

  • Проверьте правильность ID кампании
  • Проверьте, что кампания активна
  • Используйте click_id вместо этого для лучшей точности

Тестирование конверсий

Ручное тестирование

Сгенерировать тестовый клик:

  • Посетите URL вашей кампании: https://track.example.com/YOUR_CAMPAIGN_TOKEN/
  • Запишите click_id из перенаправленного URL

Протестировать постбек:

curl "https://track.example.com/c/postback?click_id=YOUR_CLICK_ID&conversion_value=10"

Проверить в Simple TDS:

  • Перейти на страницу конверсий
  • Проверить, записана ли конверсия
  • Проверить значение конверсии и click_id

Автоматизированное тестирование

Создайте тестовый скрипт для проверки отслеживания конверсий:

// test-conversion.js
const fetch = require('node-fetch');

async function testConversion(clickId) {
    const url = `https://track.example.com/c/postback?click_id=${clickId}&conversion_value=25.50&conversion_type=test`;

    const response = await fetch(url);
    const data = await response.json();

    if (data.success) {
        console.log('✓ Конверсия отслежена успешно');
        console.log('  ID конверсии:', data.conversion_id);
    } else {
        console.error('✗ Отслеживание конверсии не удалось');
        console.error('  Ошибка:', data.message);
    }
}

// Тест с вашим click_id
testConversion('a3f8b2c1d4e5f6g7h8i9j0k1l2m3n4o5');

Лучшие практики

  1. Всегда используйте HTTPS для всех URL отслеживания
  2. Предпочитайте server-to-server постбеки вместо пиксельного отслеживания, когда это возможно
  3. Сохраняйте click_id постоянно в sessionStorage или cookies для многостраничных потоков
  4. Тщательно тестируйте перед отправкой живого трафика
  5. Отслеживайте конверсионность для раннего обнаружения проблем отслеживания
  6. Используйте external_id для перекрестной ссылки с вашими собственными ID транзакций
  7. Внедрите резервное отслеживание (например, и постбек, и пиксель)
  8. Документируйте вашу интеграцию для будущих ссылок

Поддержка

По вопросам и проблемам: