Трекинговая аналитика

Как это работает

Трекинговая аналитика позволяет собирать и агрегировать события, генерируемые пользователем, для оценки эффективности программы и количества рефералов. Полученные данные используются в качестве дополнительного способа привлечения аффилированных сетей — наличие статистики повышает вероятность взятия программы.

Поддерживается обработка следующих типов событий:

  • переход на сайт;
  • переход в магазин с сайта.

Как настроить

Для интеграции трекинговой аналитики:

  1. Получите JSON Web Token (JWT).
  2. Сохраните tracking_id из параметра запроса в cookie вашего сайта. Пример запроса с tracking_id: https://playnewz.com?utm_source=n6LI9yVu&utm_campaign=5b9bff5f9d31b&tracking_id=19e2DLjNTk2YOdXA4d8J3NReNkXNafhC.
  3. После создания нового пользователя отправьте user_id и tracking_id с помощью метода Отправка события регистрации.
    • Рекомендуется использовать асинхронную отправку запросов, это позволит не прерывать регистрацию новых пользователей на время ожидания ответа Xsolla Tracking API.
    • Вы также можете использовать timeout вместо асинхронной отправки запросов. Обратите внимание, что Xsolla не сможет отследить новых пользователей, если ожидание ответа Xsolla Tracking API превысит заданные временные рамки.
  4. Для создания и управления кастомными событиями добавьте следующие методы Tracking API: создание, инициализация и отправка событий.
  5. Добавьте трекинговый скрипт на ваш сайт.

Получение токена

HTTP-ЗАПРОС

Copy
Full screen
Small screen
1POST https://tracking-api.xsolla.com/v1/tokens
ЗаголовокОписание
ContentTypeapplication/json
AuthorizationЗаголовок базовой HTTP-аутентификации в формате Authorization: Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара ID продавца:ключ API, закодированная по стандарту Base64. Значения параметров вы можете найти в Личном кабинете:Обязательный.
Внимание

Подробная информация о работе с ключами API приведена в справочнике API.

Основные рекомендации:

  • Сохраните созданный ключ API на вашей стороне. Вы можете посмотреть ключ API в Личном кабинете только один раз при его создании.
  • Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
  • Ключ API должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.

Если необходимый метод API не включает в себя path-параметр project_id, используйте для авторизации ключ API, который действует во всех проектах.

ПараметрОписание
sourceTypeНазвание источника данных. Может принимать следующие значения:
  • client. Является недоверенным источником, все события в хранилище будут помечены свойством trusted: false.
  • server. Является доверенным источником, все события в хранилище будут помечены свойством trusted: true.
sourceNameНазвание источника данных.
projectIdID проекта.
ПРИМЕР
Copy
Full screen
Small screen

http

  • http
  • php
 1POST https://tracking-api.xsolla.com/v1/tokens
 2
 3Headers:
 4Content-Type: application/json
 5Authorization: Basic 12kj3hlk1j2hlkjhlk1j2h3lkj
 6
 7Body:
 8{
 9  "sourceType": "client",
10  "sourceName": "landing",
11  "projectId": 1
12}
13
14HTTP/1.1 201 Token created
15{
16  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2 g_dj1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1du"
17}
 1<?php
 2
 3$curl = curl_init();
 4
 5$merchantId = 1;
 6$projectId = 2;
 7$apiKey = '<apiKey>';
 8
 9$payload = [
10    'sourceType' => 'server',
11    'sourceName' => 's1',
12    'projectId' => $projectId,
13];
14
15curl_setopt($curl, CURLOPT_USERPWD, $merchantId . ":" . $apiKey);
16
17
18curl_setopt_array($curl, array(
19    CURLOPT_URL => "https://tracking-api.xsolla.com/v1/tokens",
20    CURLOPT_RETURNTRANSFER => true,
21    CURLOPT_ENCODING => "",
22    CURLOPT_MAXREDIRS => 10,
23    CURLOPT_TIMEOUT => 30,
24    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
25    CURLOPT_CUSTOMREQUEST => "POST",
26    CURLOPT_POSTFIELDS => json_encode($payload),
27    CURLOPT_HTTPHEADER => [
28        "Content-type: application/json"
29    ],
30));
31
32
33$response = curl_exec($curl);
34$err = curl_error($curl);
35
36curl_close($curl);
37
38if ($err) {
39    echo "cURL Error #:" . $err;
40} else {
41    echo $response;
42}
Код ответаОписание
201Токен успешно создан
400Query-параметры недействительны
401Ключ проекта недействителен

Отправка события регистрации

Для выполнения команды необходим токен.

HTTP-ЗАПРОС

Copy
Full screen
Small screen
1POST https://tracking-api.xsolla.com/v1/events

Во время выполнения метода:

  1. Конечный пользователь переходит по трекинговой ссылке из определенного источника трафика (трансляция инфлюенсера, рекламный сайт и прочее). Переходу присваивается Click ID.
  2. На стороне Proxy page формируется Tracking ID, который передается в параметре на сайт игры.
  3. Пользователь переходит на сайт игры и регистрируется.
  4. Игровой разработчик отправляет событие о регистрации через Tracking API, передавая в параметре Tracking ID и ID пользователя.

ЗаголовокОписание
AuthorizationТокен, полученный по запросу.
ПараметрТипОписание
typeСтроковыйТокен, полученный по запросу.
traitsОбъектИдентификационные данные пользователя:
  • trackingId — Tracking ID пользователя, который Xsolla передает в параметре запроса после редиректа на сайт игры.
  • userId — user ID, переданный при получении токена.
contextОбъектДолжен быть пустым.
propertiesОбъектДолжен быть пустым.
ПРИМЕР
Copy
Full screen
Small screen

http

  • http
  • php
 1POST https://tracking-api.xsolla.com/v1/events
 2
 3Headers:
 4Content-Type: application/json
 5Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_d j1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1yU
 6
 7Body:
 8{
 9  "type": "registration",
10  "traits": {
11    "trackingId": "19e2DLjNTk2YOdXA4d8J3NReNkXNafhC",
12    "userId": "20181126"
13  },
14  "properties": {
15  },
16  "context": {
17  }
18}'
 1<?php
 2
 3$curl = curl_init();
 4
 5$token  = '<token>';
 6
 7$payload = [
 8    'type' => 'registration',
 9    'traits' => [
10        'trackingId' => "19e2DLjNTk2YOdXA4d8J3NReNkXNafhC",
11        'userId' => "20181126",
12    ],
13    'properties' => [],
14    'context' => [],
15];
16
17curl_setopt_array($curl, array(
18    CURLOPT_URL => "https://tracking-api.xsolla.com/v1/events",
19    CURLOPT_RETURNTRANSFER => true,
20    CURLOPT_ENCODING => "",
21    CURLOPT_MAXREDIRS => 10,
22    CURLOPT_TIMEOUT => 30,
23    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
24    CURLOPT_CUSTOMREQUEST => "POST",
25    CURLOPT_POSTFIELDS => json_encode($payload,JSON_FORCE_OBJECT),
26    CURLOPT_HTTPHEADER => [
27        "Authorization: Bearer {$token}",
28        "Content-type: application/json"
29    ],
30));
31
32$response = curl_exec($curl);
33$err = curl_error($curl);
34
35curl_close($curl);
36
37if ($err) {
38    echo "cURL Error #:" . $err;
39}

Создание события

Для выполнения команды необходим токен.

HTTP-ЗАПРОС

Copy
Full screen
Small screen
1POST https://tracking-api.xsolla.com/v1/events
ЗаголовокОписание
AuthorizationТокен, полученный по запросу.
ПараметрТипОписание
typeСтроковыйТип события.
traitsОбъектИдентификационные данные пользователя: телефон, email, ID в игре и т. д.
contextОбъектКонтекстные данные.
propertiesОбъектСвойства события.
createdAtДатаФормат: RFC 3339 или ISO 8601.
ПРИМЕР СОБЫТИЯ: ПЕРЕХОД НА САЙТ
Copy
Full screen
Small screen
 1POST https://tracking-api.xsolla.com/v1/events
 2
 3Headers:
 4Content-Type: application/json
 5Authorization: Bearer
 6eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_d j1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1yU 
 7
 8Body:
 9{
10  "type": "landing_visit",
11  "traits":{
12    },
13  "properties":{
14    },
15  "context": {
16    "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36", "user_locale":"ru"
17  }
18}

ПРИМЕР СОБЫТИЯ: ПЕРЕХОД В ПЛАТЕЖНЫЙ ИНТЕРФЕЙС

Copy
Full screen
Small screen
 1POST https://tracking-api.xsolla.com/v1/events
 2
 3Headers:
 4Content-Type: application/json
 5Authorization: Bearer
 6eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_d j1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1yU 
 7
 8Body:
 9{
10  "type": "buy_btn",
11  "traits":{
12    },
13  "properties":{
14    "pkg_type":"bronze"
15    },
16  "context": {
17    "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36", "user_locale":"ru"
18  }
19}
Код ответаОписание
204Событие успешно добавлено
400Событие недействительно
401Токен недействителен

Инициализация события

Для выполнения команды необходим токен.

Copy
Full screen
Small screen
1xnt("init", YOUR_TOKEN);

Отправка события

Copy
Full screen
Small screen
1xnt("sendEvent", EVENT_TYPE, EVENT_PROPERTIES);
ПараметрОписание
EVENT_TYPEНазвание события (string). Например, landing_visit.
EVENT_PROPERTIESСвойства события (JS object).
ПРИМЕР
Copy
Full screen
Small screen
1xnt("sendEvent", "landing_visit");
2xnt("sendEvent", "buy_btn", { pkg_type: $(this).data('id') });

ПАРАМЕТРЫ СОБЫТИЯ

ПараметрОписание
sourceИсточник события (paystation, landing_page и т. д.).
typeТип события (user_visit, hit и т. д.).
traitsДанные о пользователе (email, user_id, nickname и т. д.).
contextДанные о контексте события (ip, gaClientId и т. д.).
propertiesСвойства самого события (sum, levelup и т. д.).
createdAtВремя события, переданное источником.
timestampВремя получения сообщения системой.
Чтобы дополнить событие параметрами в частях context и traits, необходимо воспользоваться следующими методами:
Copy
Full screen
Small screen
1xnt("putContext", CONTEXT_OBJECT);
2xnt("putTraits", TRAITS_OBJECT);
ПараметрОписание
CONTEXT_OBJECTКонтекст события (JS object).
TRAITS_OBJECTДанные пользователя (JS object).
Примечание
userAgent и userLocale для Context будут встроены автоматически. Данные, добавленные этими методами, будут объединены с данными события.

Подключение скрипта

Подключите на сайт игры следующий скрипт:

Copy
Full screen
Small screen
1<script>
2(function(i,s,o,g,r,a,m){i['XsollaNetworkTrackingObject']=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(ar guments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.inse rtBefore(a,m)})(window,document,'script','https://cdn.xsolla.net/network/xtracking-0.1.js','xnt');
3xnt("init", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_ dj1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1du");
4xnt("sendEvent", "buy_btn", { pkg_type : "gold" });
5</script>
Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Последнее обновление: 22 апреля 2025

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!
Не получилось отправить ваш комментарий
Попробуйте еще раз позже или напишите нам на doc_feedback@xsolla.com.