Посібник з інтеграції та відстеження конверсій

Повний посібник з інтеграції 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

Приклад цільового 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

Методи відстеження конверсій

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

Метод 1: Постбек URL (сервер-сервер)

Рекомендовано для: Партнерських мереж, прямих офферів з серверним відстеженням

Формат 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}

Налаштуйте постбек у партнерській мережі:

Більшість мереж мають налаштування "Postback URL" або "Conversion Callback". Налаштуйте його як:

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

Замініть заповнювачі на макроси конкретної мережі:

Мережа Макрос SubID Макрос Payout Макрос Status
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-макроси

Замініть їхні плейсхолдери на точну назву query-параметра, який джерело використовує при відправці трафіку:

Джерело трафікуЇхній параметр 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. Мережевий фаєрвол блокує постбек
  • Деякі сервери блокують вихідні з'єднання

Рішення: Перевірте логи сервера, додайте Simple TDS IP до білого списку за потреби

Проблема: Піксель не завантажується

Можливі причини:

1. Блокувальник реклами

Багато блокувальників реклами блокують відстежувальні пікселі

Рішення: Використовуйте постбек сервер-сервер для надійного відстеження

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. Віддавайте перевагу постбекам сервер-сервер замість відстеження пікселем, коли це можливо
  3. Зберігайте click_id постійно в sessionStorage або cookies для багатосторінкових потоків
  4. Ретельно тестуйте перед відправкою живого трафіку
  5. Моніторте рівні конверсій для раннього виявлення проблем відстеження
  6. Використовуйте external_id для перехресного посилання з вашими власними ID транзакцій
  7. Впроваджуйте резервне відстеження (наприклад, і постбек, і піксель)
  8. Документуйте вашу інтеграцію для майбутнього використання

Підтримка

З питань або проблем: