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.
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:
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.
In the code snippet, insert account-unique and platform obtainable values.
Add the prepared code to every client platform page that must be monitored.
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
andhttpReferer
: 2047 characters.userAgent
: 511 characters.pageTitle
andbrowserLanguage
: 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
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
orUNLINK
.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.
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);
1import requests
2from urllib.parse import urlencode
3
4url = '<Sensor URL>'
5key = '<Sensor Tracking Code>'
6
7headers = {
8 'Content-Type': 'application/x-www-form-urlencoded',
9 'Api-Key': key,
10}
11
12# Replace each key value with actual info
13data = {
14 ########### Required fields ###########
15 # Unique value that allows identification of a user. Ex: alice54 (string)
16 'userName': '',
17
18 # User email (string)
19 'emailAddress': '',
20
21 # User IP address (string)
22 'ipAddress': '',
23
24 # URL path of visited page (string)
25 'url': '',
26
27 # User-agent of user request (string)
28 'userAgent': '',
29
30 # Event UTC timestamp ('Y-m-d H:i:s.v' string)
31 'eventTime': '',
32
33 ########### Optional fields ###########
34 # User first name (string)
35 'firstName': '',
36
37 # User last name (string)
38 'lastName': '',
39
40 # User full name (string)
41 'fullName': '',
42
43 # Title of visited page (string)
44 'pageTitle': '',
45
46 # User phone number (string)
47 'phoneNumber': '',
48
49 # Referer of visited page (string)
50 'httpReferer': '',
51
52 # Status code for page visit (string)
53 'httpCode': '',
54
55 # Type of HTTP request from list (string)
56 'httpMethod': '',
57
58 # User browser language (string)
59 'browserLanguage': '',
60
61 # Type of user action from event types list (string)
62 'eventType': '',
63}
64
65response = requests.post(url, data=urlencode(data), headers=headers)
This code snippet is intended to work starting Node.js version 10.0. Earlier versions require another approach.
1const axios = require('axios');
2const qs = require('qs'); // You might need to install 'qs'
3
4const url = '<Sensor URL>';
5const key = '<Sensor Tracking Code>';
6const headers = {
7 'Content-Type': 'application/x-www-form-urlencoded',
8 'Api-Key': key,
9};
10
11// Replace each key value with actual info
12const data = {
13 /////////// Required fields ///////////
14 // Unique value that allows identification of a user. Ex: alice54 (string)
15 userName: '',
16
17 // User email (string)
18 emailAddress: '',
19
20 // User IP address (string)
21 ipAddress: '',
22
23 // URL path of visited page (string)
24 url: '',
25
26 // User-agent of user request (string)
27 userAgent: '',
28
29 // Event UTC timestamp ('Y-m-d H:i:s.v' string)
30 eventTime: '',
31
32 /////////// Optional fields ///////////
33 // User first name (string)
34 firstName: '',
35
36 // User last name (string)
37 lastName: '',
38
39 // User full name (string)
40 fullName: '',
41
42 // Title of visited page (string)
43 pageTitle: '',
44
45 // User phone number (string)
46 phoneNumber: '',
47
48 // Referer of visited page (string)
49 httpReferer: '',
50
51 // Status code for page visit (string)
52 httpCode: '',
53
54 // Type of HTTP request from list (string)
55 httpMethod: '',
56
57 // User browser language (string)
58 browserLanguage: '',
59
60 // Type of user action from event types list (string)
61 eventType: '',
62};
63
64axios.post(url, qs.stringify(data), { headers: headers });
1require 'net/http'
2require 'uri'
3require 'cgi'
4
5url = URI.parse('<Sensor URL>')
6key = '<Sensor Tracking Code>'
7headers = {
8 'Content-Type' => 'application/x-www-form-urlencoded',
9 'Api-Key' => key,
10}
11# Replace each key value with actual info
12data = {
13 ########### Required fields ###########
14 # Unique value that allows identification of a user. Ex: alice54 (string)
15 'userName': '',
16
17 # User email (string)
18 'emailAddress': '',
19
20 # User IP address (string)
21 'ipAddress': '',
22
23 # URL path of visited page (string)
24 'url': '',
25
26 # User-agent of user request (string)
27 'userAgent': '',
28
29 # Event UTC timestamp ('Y-m-d H:i:s.v' string)
30 'eventTime': '',
31
32 ########### Optional fields ###########
33 # User first name (string)
34 'firstName': '',
35
36 # User last name (string)
37 'lastName': '',
38
39 # User full name (string)
40 'fullName': '',
41
42 # Title of visited page (string)
43 'pageTitle': '',
44
45 # User phone number (string)
46 'phoneNumber': '',
47
48 # Referer of visited page (string)
49 'httpReferer': '',
50
51 # Status code for page visit (string)
52 'httpCode': '',
53
54 # Type of HTTP request from list (string)
55 'httpMethod': '',
56
57 # User browser language (string)
58 'browserLanguage': '',
59
60 # Type of user action from event types list (string)
61 'eventType': '',
62}
63
64http = Net::HTTP.new(url.host, url.port)
65http.use_ssl = true if url.scheme == 'https'
66request = Net::HTTP::Post.new(url, headers)
67request.body = URI.encode_www_form(data)
68response = http.request(request)