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:

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.

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

Code Examples

Event Data

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 Send Event subsection.

 1data = {
 2    ########### Required fields ###########
 3    # Unique value that allows identification of a user (string)
 4    'userName': 'tirreno42',
 5
 6    # User email (string)
 7    'emailAddress': 'team@tirreno.com',
 8
 9    # User IP address (string)
10    'ipAddress': '217.70.184.38',
11
12    # URL path of visited page (string)
13    'url': '/home/account?ref=1',
14
15    # User-agent of user request (string)
16    'userAgent': 'Mozilla/5.0 (Windows NT 6.1; rv:109.0) Gecko/20100101 Firefox/115.0 ',
17
18    # Event UTC timestamp ('Y-m-d H:i:s.v' string)
19    'eventTime': '2024-06-06 14:20:01.283',
20
21    ########### Optional fields ###########
22    # User first name (string)
23    'firstName': 'Tirreno',
24
25    # User last name (string)
26    'lastName': '',
27
28    # User full name (string)
29    'fullName': '',
30
31    # Title of visited page (string)
32    'pageTitle': 'Home page',
33
34    # User phone number (string)
35    'phoneNumber': '+41000000000',
36
37    # Referer of visited page (string)
38    'httpReferer': 'https://tirreno.com/signup',
39
40    # Status code for page visit (string)
41    'httpCode': '200',
42
43    # Type of HTTP request from list (string)
44    'httpMethod': 'POST',
45
46    # User browser language (string)
47    'browserLanguage': 'en-GB,en;q=0.9',
48
49    # Type of user action from event types list (string)
50    'eventType': 'account_registration',
51}

Send Event

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

send-event.php
 1<?php
 2
 3$url = '<Sensor URL>';
 4$key = '<Sensor Tracking Code>';
 5
 6// Replace each key value with actual info
 7$data = array(
 8    /////////// Required fields ///////////
 9    // Unique value that allows identification of a user. Ex: alice54 (string)
10    'userName'        => '',
11
12    // User email (string)
13    'emailAddress'    => '',
14
15    // User IP address (string)
16    'ipAddress'       => '',
17
18    // URL path of visited page (string)
19    'url'             => '',
20
21    // User-agent of user request (string)
22    'userAgent'       => '',
23
24    // Event UTC timestamp ('Y-m-d H:i:s.v' string)
25    'eventTime'       => '',
26
27    /////////// Optional fields ///////////
28    // User first name (string)
29    'firstName'       => '',
30
31    // User last name (string)
32    'lastName'        => '',
33
34    // User full name (string)
35    'fullName'        => '',
36
37    // Title of visited page (string)
38    'pageTitle'       => '',
39
40    // User phone number (string)
41    'phoneNumber'     => '',
42
43    // Referer of visited page (string)
44    'httpReferer'     => '',
45
46    // Status code for page visit (string)
47    'httpCode'        => '',
48
49    // Type of HTTP request from list (string)
50    'httpMethod'      => '',
51
52    // User browser language (string)
53    'browserLanguage' => '',
54
55    // Type of user action from event types list (string)
56    'eventType'       => '',
57);
58
59// Convert the event data to a query string
60$dataString = http_build_query($data);
61
62$headers = [
63    'Api-Key: ' . $key,
64    'Content-Type: application/x-www-form-urlencoded',
65];
66
67// Create a curl request to send the event data to the API
68$ch = curl_init();
69curl_setopt_array($ch, array(
70    CURLOPT_URL            => $url,
71    CURLOPT_POST           => true,
72    CURLOPT_POSTFIELDS     => $dataString,
73    CURLOPT_RETURNTRANSFER => true,
74    CURLOPT_SSL_VERIFYPEER => false,
75    CURLOPT_TIMEOUT_MS     => 1000,
76    CURLOPT_HTTPHEADER     => $headers
77));
78
79$response = curl_exec($ch);
80
81curl_close($ch);