API Integration

Tirreno can be used by practically any digital system. The only requirement is to start sending user activity information (events data) to Tirreno for further processing.

Good news!

This also means enabling integration with Tirreno hardly costs any client platform resources.

This is done by sending an HTTP POST request with event details to the Tirreno’s API.

In general, event details consist of basic user information for building their identity profiles (such as email address, IP address, phone number, etc.) and request data (such as time of event, URL requested, user agent, etc.). For an applied illustration of the fields and values to send, go to the Event Data Example subsection.

The complete list of the mandatory and optional fields accepted by the API is given below, in the Integration Examples section. The section also gives practical examples of API integration scripts in different programming languages with a number of assisting instructions.

A similar set of the ready-made examples can be found on the API Key page of the account’s Console. These examples include an account-unique API key and sensor URL, which are requisites for each API communication. Observe that the API key must be sent in the header of a request.

To accomplish the integration, fill in the mandatory and selected optional fields in the integration script with the values obtainable in the client platform. Then add the script to the pages visited by identifiable (i.e., logged-in) users.

To verify that the API communication is established, proceed to 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.

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 Code Examples 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.

Attention

If you need help with the API integration, contact us for support.

Integration Examples

The sensor accepts six mandatory and nine optional parameters. Each parameter is expected to be a string. The parameters must be passed as URL-encoded POST request data.

Note

It is highly recommended to pass as many parameters as possible. Sending more data results in more exhaustive reports and comprehensive analysis.

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

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 (for example, “2024-10-03 17:05:08”).

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.

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.

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

Event Data Example

This subsection demonstrates how to build an associative array with event details. The code snippet is written in Python programming language.

The full code examples of API requests for sending event data in different programmer languages (including Python) are presented in the Code Examples subsection.

data = {
    ########### Required fields ###########
    # Unique value that allows identification of a user (string)
    'userName': 'tirreno42',

    # User email (string)
    'emailAddress': '[email protected]',

    # 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' string)
    'eventTime': '2024-06-06 14:20:01',

    ########### Optional fields ###########
    # User first name (string)
    'firstName': 'Tirreno',

    # User last name (string)
    'lastName': '',

    # User full name (string)
    'fullName': '',

    # Title of visited page (string)
    'pageTitle': 'Home page',

    # User phone number (string)
    'phoneNumber': '+33000000000',

    # 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',
}

Code Examples

In the following code snippets, replace <Sensor URL> and <Sensor API key> with the corresponding account-unique values. They can be obtained on the API Key page of the console.

PHPPythonNode.jsRuby

send-event.php

<?php

$url = '<Sensor URL>';
$apiKey = '<Sensor API key>';

// 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' 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'       => '',
);

// 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();
curl_setopt_array($ch, array(
    CURLOPT_URL            => $url,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $dataString,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_TIMEOUT_MS     => 1000,
    CURLOPT_HTTPHEADER     => $headers
));

$response = curl_exec($ch);

curl_close($ch);