API трекінгу для зовнішніх лендингів

Використовуйте API трекінгу для зовнішніх лендингів, коли ваші лендинги розміщені поза трекером, але ви все одно хочете, щоб трекер записував кліки, ліди та postback-події в один звіт кампанії.

Таке налаштування корисне, коли панель трекера й дані кампаній залишаються на одному сервері, а лендинги розміщуються ближче до джерел трафіку. Наприклад, ви можете тримати трекер на сервері в Європі, а лендинги розмістити в Латинській Америці, Азії, Австралії або Північній Америці, щоб зменшити час завантаження сторінок для відвідувачів у цих регіонах.

Ця інтеграція потребує навичок програмування. Розробник має додати обробку запитів у код лендингу, згенерувати або зберегти click ID і викликати endpoint-и трекера в потрібний момент.

Як це працює

Трекеру потрібне одне спільне значення протягом усього шляху відвідувача: clickId.

Уявіть clickId як номер квитанції для відвідувача. Click endpoint створює цю квитанцію. Lead і postback endpoint-и додають наступні події до тієї самої квитанції.

Огляд endpoint-ів

Усі три endpoint-и приймають додаткові параметри. Трекер зберігає ці параметри разом із подією, тому ви можете передавати назви оголошень, ID оферів, ID джерел трафіку, статуси або інформацію про виплати.

Передумови

Перед початком підготуйте ці дані.

Крок 1: Згенеруйте Click ID

Перед викликом click endpoint згенеруйте один UUID для кожної сесії відвідувача.

Приклад:

8f1b5c6e-7a3d-4d20-a7f1-12a2b8f7a9c1

Використовуйте це саме значення для всіх наступних подій у цьому шляху відвідувача.

Поширені способи зберегти clickId доступним:

Крок 2: Відстежте клік

Викликайте /api/v2/track/click, коли відвідувач доходить до зовнішнього лендингу.

POST /api/v2/track/click HTTP/1.1
Host: dashboard.<your-domain>
Content-Type: application/json

{
  "clickId": "8f1b5c6e-7a3d-4d20-a7f1-12a2b8f7a9c1",
  "campaignId": 42,
  "source": "facebook",
  "campaign_name": "LatAm Ring Campaign",
  "adset_name": "MX Android",
  "ad_name": "video-01"
}

Очікувана відповідь:

201 Created

clickId має бути UUID. campaignId має бути числовим ID кампанії в трекері.

Додаткові поля необовʼязкові. Використовуйте їх для звітного контексту, який ви хочете бачити пізніше разом із кліком.

Крок 3: Відстежте лід

Викликайте /api/v2/track/lead, коли відвідувач надсилає форму або виконує lead-дію на вашому зовнішньому лендингу.

GET-приклад:

https://dashboard.<your-domain>/api/v2/track/lead?clickId=8f1b5c6e-7a3d-4d20-a7f1-12a2b8f7a9c1&offer_id=456&source=landing

POST-приклад:

POST /api/v2/track/lead HTTP/1.1
Host: dashboard.<your-domain>
Content-Type: application/json

{
  "clickId": "8f1b5c6e-7a3d-4d20-a7f1-12a2b8f7a9c1",
  "offer_id": "456",
  "source": "landing"
}

Очікувана відповідь:

201 Created

Використовуйте цей endpoint для подій, які відбуваються безпосередньо на зовнішньому лендингу, наприклад для надсилання форми. Трекер зберігає lead-подію та її додаткові параметри.

Крок 4: Відстежте postback

Налаштуйте рекламодавця, партнерську мережу, CRM або іншу зовнішню систему так, щоб вона повідомляла про конверсію або оновлення статусу на /api/v2/track/postback.

GET-приклад:

https://dashboard.<your-domain>/api/v2/track/postback?clickId=8f1b5c6e-7a3d-4d20-a7f1-12a2b8f7a9c1&status=approved&payout=10&offer_id=456

POST-приклад:

POST /api/v2/track/postback HTTP/1.1
Host: dashboard.<your-domain>
Content-Type: application/json

{
  "clickId": "8f1b5c6e-7a3d-4d20-a7f1-12a2b8f7a9c1",
  "status": "approved",
  "payout": 10,
  "offer_id": "456"
}

Очікувана відповідь:

201 Created

Якщо в кампанії налаштований Status Mapper, трекер використовує параметри postback-запиту, щоб перетворити зовнішній статус на один із внутрішніх статусів ліда: accept, expect, reject або trash.

Наприклад, якщо status mapper кампанії читає параметр status, цей postback:

status=approved

може стати:

accept

Postback-и зі статусами accept і expect також можуть використовувати значення вартості й валюту кампанії для звітів.

Приклад інтеграційного потоку

Використовуйте цей чекліст як порядок впровадження.

1. Створіть або виберіть кампанію в трекері.
2. Скопіюйте campaign ID із трекера.
3. Додайте генерацію UUID у backend зовнішнього лендингу.
4. Збережіть clickId для сесії відвідувача.
5. Викликайте POST /api/v2/track/click, коли лендинг відкрито.
6. Додайте той самий clickId у надсилання lead-форми.
7. Викликайте /api/v2/track/lead після надсилання lead-форми.
8. Передайте той самий clickId рекламодавцю або партнерській мережі, якщо їм потрібно надсилати postback-и.
9. Налаштуйте postback URL рекламодавця або партнерської мережі на виклик /api/v2/track/postback.
10. Відкрийте звіти трекера й перевірте, що кліки, ліди та postback-и зʼявляються в кампанії.

Нотатки щодо реалізації

• Використовуйте HTTPS для всіх API-викликів трекера.
• Генеруйте новий clickId для кожного візиту відвідувача, а не одне спільне значення для всіх відвідувачів.
• Зберігайте той самий clickId у подіях click, lead і postback.
• Передавайте clickId у camelCase. API очікує clickId, а не click_id.
• Передавайте campaignId у camelCase для click tracking. API очікує campaignId, а не campaign_id.
• Використовуйте POST /api/v2/track/click для кліків. Click endpoint не приймає GET-запити.
• Використовуйте GET postback-и лише тоді, коли зовнішня система не може надсилати JSON POST-запити.
• Сприймайте додаткові параметри як метадані події. Трекер зберігає їх, але лише налаштований status mapping керує внутрішнім статусом конверсії.

Усунення проблем

Приклад PHP-лендингу

Різні лендинги можуть використовувати різний код. Приклади нижче показують один практичний варіант реалізації на PHP для розробників, які впевнено редагують PHP-лендинги й обробники submit.php. Адаптуйте назви полів, запит до CPA-мережі, валідацію та обробку помилок під свій лендинг.

Відстежте клік

Приклад нижче записує клік із PHP-лендингу. Він копіює поточні query parameters лендингу, додає clickId і campaignId, надсилає click-подію в трекер і повертає згенерований clickId, щоб лендинг міг використати його для lead- і postback-трекінгу.

Перед використанням прикладу замініть ці значення:

<?php

function generate_click_id()
{
    $click_id = @file_get_contents('/proc/sys/kernel/random/uuid');

    if (!$click_id) {
        exec('uuidgen', $output);
        $click_id = $output[0];
    }

    return trim($click_id);
}

function send_json_request($url, $payload)
{
    $ch = curl_init($url);

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($payload),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 2,
    ]);

    curl_exec($ch);
    curl_close($ch);
}

function track_click()
{
    $query_string = ! empty($_SERVER['QUERY_STRING']) ? $_SERVER['QUERY_STRING'] : '';
    parse_str($query_string, $parameters);

    $parameters['clickId'] = generate_click_id();
    $parameters['campaignId'] = 1;

    send_json_request(
        'https://dashboard.<your-domain>/api/v2/track/click',
        $parameters
    );

    return $parameters['clickId'];
}

$click_id = track_click();

Передайте Click ID через форму

Після трекінгу кліку передайте $click_id разом із order form. У цьому прикладі значення надсилається як sub1, тому що багато CPA-мереж підтримують sub-parameters, наприклад sub1, sub2 або схожі поля.

<form id="order_form" action="submit.php?<?php echo http_build_query($_GET); ?>" method="post">
    <!-- ... -->
    <input type="hidden" name="sub1" value="<?php echo $click_id; ?>" />
    <!-- ... -->
</form>

Одну й ту саму надіслану форму можна використати для двох дій:

1. Надіслати order data в CPA-мережу через вашу звичайну CURL-інтеграцію.
2. Надіслати lead-подію в Bangi CPA Tracker із тим самим click ID.

Відстежте лід із submit.php

У submit.php прочитайте click ID із прихованого поля sub1 і надішліть його в /api/v2/track/lead як clickId.

<?php
// ...
$track_lead_parameters = array_merge($order, [
    'clickId' => $_POST['sub1'],
]);

send_json_request(
    'https://dashboard.<your-domain>/api/v2/track/lead',
    $track_lead_parameters
);

Якщо submit.php є окремим файлом, визначте send_json_request() і там або винесіть її в спільний PHP-файл та підключайте і з лендингу, і з submit.php.

Масив $order має містити поля ліда або замовлення, корисні для ваших звітів: offer ID, назву лендингу, buyer status, країну телефону або дані відповіді CPA-мережі. Не надсилайте чутливі персональні дані, якщо ви не хочете навмисно зберігати їх у metadata події трекера.

Ви все ще можете надсилати $_POST або підготовлений order payload у CPA-мережу через CURL. Важливо, щоб lead-запит до трекера отримав той самий click ID, який був створений під час click tracking.

Для повного шляху зберігайте те саме значення в усіх місцях:

Після впровадження протестуйте повний шлях в одній реальній браузерній сесії та з одним тестовим лідом. Чистий тест має створити одну click-подію і повʼязаний із нею lead або postback під тим самим clickId.