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. In case troubleshooting is needed, open the Logbook page which exposes processing statuses 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 Code Examples 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.

Integration Examples

The sensor accepts six mandatory and ten 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. To affirm requests processing statuses, refer to the Logbook page.

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”).

Attention

The maximum length of all request parameters is 100 characters, except the following: 2047 characters for url and httpReferer, 511 characters for userAgent, 255 for pageTitle and browserLanguage and 19 characters for phoneNumber.

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

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': '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': 'Tirreno',

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

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

    # Type of HTTP request from list (string)
    'httpMethod': 'POST',

    # 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.

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.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'        => '',

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

    // 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);

send-event.py

import requests
from urllib.parse import urlencode

url = '<Sensor URL>'
key = '<Sensor API key>'

headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Api-Key': key,
}

# Replace each key value with actual info
data = {
    ########### 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': '',

    # Type of HTTP request from list (string)
    'httpMethod': '',

    # User browser language (string)
    'browserLanguage': '',

    # Type of user action from event types list (string)
    'eventType': '',
}

response = 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.

send-event-node.js

const axios = require('axios');
const qs = require('qs');       // You might need to install 'qs'

const url = '<Sensor URL>';
const key = '<Sensor API key>';
const headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Api-Key': key,
};

// Replace each key value with actual info
const data = {
    /////////// 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: '',

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

    // User browser language (string)
    browserLanguage: '',

    // Type of user action from event types list (string)
    eventType: '',
};

axios.post(url, qs.stringify(data), { headers: headers });

send-event.rb

require 'net/http'
require 'uri'
require 'cgi'

url = URI.parse('<Sensor URL>')
key = '<Sensor API key>'
headers = {
    'Content-Type' => 'application/x-www-form-urlencoded',
    'Api-Key' => key,
}
# Replace each key value with actual info
data = {
    ########### 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': '',

    # Type of HTTP request from list (string)
    'httpMethod': '',

    # User browser language (string)
    'browserLanguage': '',

    # Type of user action from event types list (string)
    'eventType': '',
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true if url.scheme == 'https'
request = Net::HTTP::Post.new(url, headers)
request.body = URI.encode_www_form(data)
response = http.request(request)