Tracking analytics

How it works

Tracking analytics lets you collect and aggregate user-generated events to evaluate program performance and the number of referrals. The obtained data can be used as an additional way to engage affiliate networks, as strong stats make the offer more attractive.

The following events can be processed:

  • Transition to the landing page
  • Transition from the landing page to the store

How to get it

To integrate tracking analytics, do the following:

  1. Get a JSON Web Token (JWT).
  2. Save tracking_id from the request parameter to your website cookies. Example of a request with tracking_id: https://playnewz.com?utm_source=n6LI9yVu&utm_campaign=5b9bff5f9d31b&tracking_id=19e2DLjNTk2YOdXA4d8J3NReNkXNafhC.
  3. After a new user is created, send user_id and tracking_id via the Registration Event Sending method.
    • It’s recommended to send requests asynchronously, so it doesn’t interfere with user registration while awaiting the Xsolla Tracking API response.
    • Otherwise, use timeout. Note that new users won’t be tracked if awaiting the Xsolla Tracking API response takes longer than specified.
  4. To create and manage custom events, implement the following Tracking API methods: create, initialize and send an event.
  5. Implement the tracking script on your website.

Get token

HTTP REQUEST

Copy
Full screen
Small screen
POST https://tracking-api.xsolla.com/v1/tokens
HeaderDescription
ContentTypeapplication/json
AuthorizationThe Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant ID:API key pair, encoded according to the Base64 standard. Go to Publisher Account to find these parameters:
  • Merchant ID is shown:
    • In the Project settings > Webhooks section.
    • In the Company settings > Company section.
    • In the URL in the browser address bar on any Publisher Account page. The URL has the following format: https://publisher.xsolla.com/​merchant ID/Publisher Account section.
  • API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
    • Company settings > API keys
    • Project settings > API keys
Required.
Notice

For more information about working with API keys, see the API reference.

Key recommendations:

  • Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
  • Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
  • The API key must be stored on your server and never in binaries or on the frontend.

ParameterDescription
sourceTypeData source type. It can take the following values:
  • client. This source type is considered non-trusted, and all respective events in the storage have the status trusted: false.
  • server. This source type is considered trusted, and all respective events in the storage have the status trusted: true.
sourceNameData source name.
projectIdProject ID.
EXAMPLE
Copy
Full screen
Small screen

http

  • http
  • php
POST https://tracking-api.xsolla.com/v1/tokens

Headers:
Content-Type: application/json
Authorization: Basic 12kj3hlk1j2hlkjhlk1j2h3lkj

Body:
{
  "sourceType": "client",
  "sourceName": "landing",
  "projectId": 1
}

HTTP/1.1 201 Token created
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2 g_dj1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1du"
}
<?php

$curl = curl_init();

$merchantId = 1;
$projectId = 2;
$apiKey = '<apiKey>';

$payload = [
    'sourceType' => 'server',
    'sourceName' => 's1',
    'projectId' => $projectId,
];

curl_setopt($curl, CURLOPT_USERPWD, $merchantId . ":" . $apiKey);


curl_setopt_array($curl, array(
    CURLOPT_URL => "https://tracking-api.xsolla.com/v1/tokens",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        "Content-type: application/json"
    ],
));


$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response;
}
Response codeDescription
201Token created
400Query parameters are not valid
401Project key is not valid

Registration event sending

You need to first obtain a token to do this.

HTTP REQUEST

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

While sending the method, the following steps are completed:

  1. The end user follows the tracking link they found on the traffic source (influencer’s stream, promo page, etc.). The action is given its Click ID.
  2. Tracking ID is formed on the Proxy page side and passed to the landing page in the parameter.
  3. The user visits the landing page and signs up.
  4. The game developer passes user User ID and Tracking ID in the parameter by sending the registration event via Tracking API.

HeaderDescription
AuthorizationPreviously obtained token.
ParameterTypeDescription
typeStringPreviously obtained token.
traitsObjectUser identification data:
  • trackingId – Tracking ID of the user redirected to the game website. Xsolla sends it in the request parameter after the redirect.
  • userIduser ID assigned upon token creation.
contextObjectMust be empty.
propertiesObjectMust be empty.
EXAMPLE
Copy
Full screen
Small screen

http

  • http
  • php
POST https://tracking-api.xsolla.com/v1/events

Headers:
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_d j1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1yU

Body:
{
  "type": "registration",
  "traits": {
    "trackingId": "19e2DLjNTk2YOdXA4d8J3NReNkXNafhC",
    "userId": "20181126"
  },
  "properties": {
  },
  "context": {
  }
}'
<?php

$curl = curl_init();

$token  = '<token>';

$payload = [
    'type' => 'registration',
    'traits' => [
        'trackingId' => "19e2DLjNTk2YOdXA4d8J3NReNkXNafhC",
        'userId' => "20181126",
    ],
    'properties' => [],
    'context' => [],
];

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://tracking-api.xsolla.com/v1/events",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode($payload,JSON_FORCE_OBJECT),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$token}",
        "Content-type: application/json"
    ],
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
}

Create event

You need to first obtain a token to do this.

HTTP REQUEST

Copy
Full screen
Small screen
POST https://tracking-api.xsolla.com/v1/events
HeaderDescription
AuthorizationPreviously obtained token.
ParameterTypeDescription
typeStringEvent type.
traitsObjectUser identification data: phone, email, in-game ID, etc.
contextObjectContextual data.
propertiesObjectEvent properties.
createdAtDateFormat: datetime per RFC 3339 or ISO 8601.
EXAMPLE EVENT: TRANSITION TO LANDING PAGE
Copy
Full screen
Small screen
POST https://tracking-api.xsolla.com/v1/events

Headers:
Content-Type: application/json
Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_d j1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1yU 

Body:
{
  "type": "landing_visit",
  "traits":{
    },
  "properties":{
    },
  "context": {
    "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"
  }
}

EXAMPLE EVENT: TRANSITION TO PAY STATION

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

Headers:
Content-Type: application/json
Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_d j1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1yU 

Body:
{
  "type": "buy_btn",
  "traits":{
    },
  "properties":{
    "pkg_type":"bronze"
    },
  "context": {
    "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"
  }
}
Response codeDescription
204Event added
400Event is not valid
401Token is not valid

Initialize event

You need to first obtain a token to do this.

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

Send event

Copy
Full screen
Small screen
xnt("sendEvent", EVENT_TYPE, EVENT_PROPERTIES);
ParameterDescription
EVENT_TYPEEvent name (string). E.g., landing_visit.
EVENT_PROPERTIESEvent properties (JS object).
EXAMPLE
Copy
Full screen
Small screen
xnt("sendEvent", "landing_visit");
xnt("sendEvent", "buy_btn", { pkg_type: $(this).data('id') });

EVENT PARAMETERS

ParameterDescription
sourceEvent source (paystation, landing_page, etc.).
typeEvent type (user_visit, hit, etc.).
traitsUser data (email, user_id, nickname, etc.).
contextEvent context (ip, gaClientId, etc.).
propertiesEvent properties (sum, levelup, etc.).
createdAtEvent time, as passed by the source.
timestampTime of event receipt by the system.
To complement the event with context and traits parameters, use the following methods:
Copy
Full screen
Small screen
xnt("putContext", CONTEXT_OBJECT);
xnt("putTraits", TRAITS_OBJECT);
ParameterDescription
CONTEXT_OBJECTEvent context (JS object).
TRAITS_OBJECTUser data (JS object).
Note
Context’s userAgent and userLocale will be added automatically. The data added by these two methods will be combined with the event data.

Implement script

Implement the following script on the landing page:

Copy
Full screen
Small screen
<script>
(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');
xnt("init", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaW5rIjoiaHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g_ dj1kUXc0dzlXZ1hjUSJ9.aVigY6UVY3jgoEKoBv31cZnROL3I6WKtcr5K-Z7B1du");
xnt("sendEvent", "buy_btn", { pkg_type : "gold" });
</script>
Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: January 22, 2024

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!