API integration

In this chapter, we review how to enable monitoring of a client platform. We assume that the Installation instructions have been completed at this stage.

Good news!

tirreno can be used by practically any digital system. Enabling integration with tirreno requires minimal client platform resources.

To start gathering user activity information (events), add an integration script to each monitored page of a client platform.

We have prepared a set of code examples in various programming languages, along with accompanying instructions, to help you get started with the script. The examples can be found in two places:

• In the section Code examples below.

• On the API page of the account’s console.

At the top of the Send event code example, insert the tracking code and sensor URL values required for API communication. The tracking code authorizes access to the API, while the sensor URL is the API endpoint that accepts HTTP POST requests containing event data. Both values are available on the API page of the console.

Then, fill in event details with the values obtainable in the client platform. For a practical example of the parameters and values to send, see the Event data subsection.

In general, event details include basic user information for building their identity profiles (such as email address, IP address, phone number, etc.) and request data (such as time of the event, URL requested, user agent, etc.). The complete list of mandatory and optional parameters accepted by the API is given in the Parameters section below.

Now, add the finalized integration script to the pages visited by identifiable (i.e., logged-in) users.

To verify that API communication is established, check the account’s Console. The event processing time is expected to fall in the range of a minute, resulting in close to real-time reporting. In case troubleshooting is needed, open the Logbook page, which exposes the processing status of the recent API requests.

Integration outline

To summarize, the steps to perform for accomplishing an API integration are as follows:

1. Choose a code snippet matching the backend environment of a client platform in the Send event subsection. Or use one of them as a prototype.

2. In the code snippet, insert account-unique and platform obtainable values.

3. Add the prepared code to every client platform page that must be monitored.

4. Verify established API communication at the tirreno console.

Parameters

The sensor accepts six mandatory and ten optional parameters. Each parameter value should be a string. The data must be URL-encoded and sent in a POST request.

Note

We recommend passing as many parameters as possible. Sending more data leads to more detailed reports and thorough analysis.

The sensor always responds with the code 204, even when receiving non-valid data. Therefore, this only enables monitoring the sensor’s availability.

To confirm the processing status of requests, refer to the Logbook page.

Attention

The maximum length of all request parameter values is 100 characters, except the following:

• url and httpReferer: 2047 characters.

• userAgent: 511 characters.

• pageTitle and browserLanguage: 255 characters.

• phoneNumber: 19 characters.

Required parameters

userName

A user identifier. It must be a unique value assigned to a user by a client platform. It serves to distinguish one user from another and is employed by tirreno to recognize individual users.

emailAddress

An email address associated with a user.

ipAddress

An IP address associated with an event. It can be retrieved from HTTP request headers.

url

A URL path of a resource requested on a client platform.

userAgent

A user agent string value. It can be retrieved from the HTTP request’s User-Agent header.

eventTime

A timestamp of an event. It must be passed in the format Y-m-d H:i:s.v (for example, “2024-12-08 18:32:17.397”).

Optional parameters

firstName

A user’s first name.

lastName

A user’s last name.

fullName

A user’s whole name.

pageTitle

A title of a visited resource.

phoneNumber

A user’s phone number.

httpReferer

A value of the Referer HTTP header field.

httpMethod

The type of HTTP request: GET, POST, HEAD, PUT, DELETE, PATCH, TRACE, CONNECT, OPTIONS, LINK or UNLINK.

httpCode

An HTTP response status code the request ended with.

browserLanguage

A detected language of the browser.

eventType

One of the event types listed below.

payload

Associative array of event details, applicable only for account_email_change and page_search event types.

fieldHistory

Array of event details, applicable only for field_edit event type.

Event type

Even though the parameter eventType is optional, consider sending it with the rest of the data. It has proven to be very effective for user behaviour analytics.

The value must be one of the following:

• page_view

• page_edit

• page_delete

• account_login

• account_logout

• account_login_fail

• account_registration

• account_email_change

• account_password_change

• account_edit

• page_search

• page_error

• field_edit

Payload

For page_search event type payload is defined as single associative array with required fields field_id and value and one optional field field_name.

{
    "eventType": "page_search",
    "payload": {
        "value": "Great Br",
        "field_id": 179280,
        "field_name": "Country"
    }
}

For account_email_change event type payload is defined as single associative array with one required field new_value and one optional old_value.

{
    "eventType": "account_email_change",
    "payload": {
        "new_value": "team@tirreno.com",
        "old_value": "ping@tirreno.com"
    }
}

Field history

Filling fieldHistory parameter is required for events with field_edit event type.

Value should be defined as an array of associative arrays, where each associative array represents single field edit. Single field edit requires two fields field_id and new_value, while fields field_name, old_value, parent_id, parent_name are optional.

{
    "eventType": "field_edit",
    "payload": [
        {
            "new_value": "Paris",
            "old_value": "London",
            "field_id": 179283,
            "field_name": "User city"
        },
        {
            "new_value": "France",
            "old_value": "Great Britain",
            "field_id": 943577,
            "field_name": "User country"
        }
    ]
}

Code examples

Event data

This subsection demonstrates how to build an associative array with event details.

The full code examples of API requests for sending event data in different programmer languages are presented in the Send event subsection.

PHPPythonNode.jsRuby

event-data.php

<?php

$data = array(

    /////////// Required fields ///////////

    // Unique value that allows identification of a user. Ex: alice54 (string)
    'userName'        => 'tirreno42',

    // User email (string)
    'emailAddress'    => 'team@tirreno.com',

    // User IP address (string)
    'ipAddress'       => '217.70.184.38',

    // URL path of visited page (string)
    'url'             => '/home/account?ref=1',

    // User-agent of user request (string)
    'userAgent'       => 'Mozilla/5.0 (Windows NT 6.1; rv:109.0) Gecko/20100101 Firefox/115.0',

    // Event UTC timestamp ('Y-m-d H:i:s.v' string)
    'eventTime'       => '2024-06-06 14:20:01.283',

    /////////// Optional fields ///////////

    // User first name (string)
    'firstName'       => 'John',

    // User last name (string)
    'lastName'        => 'Fox',

    // User full name (string)
    'fullName'        => '',

    // Title of visited page (string)
    'pageTitle'       => 'Home page',

    // User phone number (string)
    'phoneNumber'     => '+41000000000',

    // Referer of visited page (string)
    'httpReferer'     => 'https://tirreno.com/signup',

    // Status code for page visit (string)
    'httpCode'        => '200',

    // User browser language (string)
    'browserLanguage' => 'en-GB,en;q=0.9',

    // Type of user action from event types list (string)
    'eventType'       => 'account_registration',

    // Type of HTTP request from list (string)
    'httpMethod'      => 'POST',

    // User created UTC timestamp ('Y-m-d H:i:s' string)
    'userCreated'     => ''
);

Send event

In the following code snippet, replace <Tracking ID> with the corresponding tirreno tracking code value. It can be obtained on the API page of the console.

PHPPythonNode.jsRuby

send-event.php

<?php

// Set the API key for sending events
$apiKey = '<Tracking ID>';

// Replace each key value with actual info
$data = array(

    /////////// Required fields ///////////

    // Unique value that allows identification of a user. Ex: alice54 (string)
    'userName'        => '',

    // User email (string)
    'emailAddress'    => '',

    // User IP address (string)
    'ipAddress'       => '',

    // URL path of visited page (string)
    'url'             => '',

    // User-agent of user request (string)
    'userAgent'       => '',

    // Event UTC timestamp ('Y-m-d H:i:s.v' string)
    'eventTime'       => '',

    /////////// Optional fields ///////////

    // User first name (string)
    'firstName'       => '',

    // User last name (string)
    'lastName'        => '',

    // User full name (string)
    'fullName'        => '',

    // Title of visited page (string)
    'pageTitle'       => '',

    // User phone number (string)
    'phoneNumber'     => '',

    // Referer of visited page (string)
    'httpReferer'     => '',

    // Status code for page visit (string)
    'httpCode'        => '',

    // User browser language (string)
    'browserLanguage' => '',

    // Type of user action from event types list (string)
    'eventType'       => '',

    // Type of HTTP request from list (string)
    'httpMethod'      => '',

    // User created UTC timestamp ('Y-m-d H:i:s' string)
    'userCreated'     => '',

    // Payload, must have `page_search` or `account_email_change` event type (array)
    'payload'         => [],

    // Field history, must have `field_edit` event type (array)
    'fieldHistory'    => [
        [
            'field_name'    => '',      // Name of the field
            'field_id'      => '',      // ID of the field
            'new_value'     => '',      // Field new value
            'old_value'     => '',      // Field old value
            'parent_id'     => ''       // ID of the field parent
        ]
    ],
);

// Convert the event data to a query string
$dataString = http_build_query($data);

// Set up apiKey
$headers = [
    'Api-Key: ' . $apiKey,
    'Content-Type: application/x-www-form-urlencoded',
];

// Create a curl request to send the event data to the API

$ch = curl_init();
// CURLOPT_URL value is sensor URL
curl_setopt_array($ch, array(
    CURLOPT_URL            => 'http://localhost/tirreno/sensor/',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $dataString,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_TIMEOUT_MS     => 1000,
    CURLOPT_HTTPHEADER     => $headers
));

// Send the curl request and capture the response
$response = curl_exec($ch);

// Close the curl request
curl_close($ch);

Blacklist API

After setting up your personalized rules engine and manual or automated user blacklisting you can retrieve information about user status by requesting /api/v1/blacklist/search endpoint wherever your app needs to.

RequestResponse

Blacklist API request

POST /api/v1/blacklist/search HTTP/2
Host: localhost:8585
Content-Type: application/json
Api-Key: <Tracking ID>

{
    "value": "tirreno42"
}