.. index:: single: API Integration .. _api-integration: API Integration =============== In this chapter, we review how to enable monitoring of a :term:`client` platform. We assume that the :ref:`Installation Instructions ` have been completed at this stage. .. admonition:: Good news! :tirreno:`Tirreno` can be used by practically any digital system. Enabling integration with :tirreno:`Tirreno` requires minimal :term:`client` platform resources. To start gathering :term:`user` activity information (:term:`events`), add an :term:`integration script` to each monitored page of a :term:`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 :ref:`Code Examples ` below. * On the :ref:`API ` page of the account’s :term:`console`. At the top of the :ref:`Send Event ` code example, insert the :term:`tracking code` and :term:`sensor` URL values required for API communication. The :term:`tracking code` authorizes access to the API, while the :term:`sensor` URL is the API endpoint that accepts HTTP POST requests containing :term:`event` data. Both values are available on the :ref:`API ` page of the :term:`console`. Then, fill in :term:`event` details with the values obtainable in the :term:`client` platform. For a practical example of the parameters and values to send, see the :ref:`Event Data ` subsection. In general, :term:`event` details include basic :term:`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 :ref:`Parameters ` section below. Now, add the finalized :term:`integration script` to the pages visited by identifiable (i.e., logged-in) :term:`users`. To verify that API communication is established, check the account’s :ref:`Console `. The :term:`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 :ref:`Logbook` page, which exposes the processing status of the recent API requests. .. _integration-outline: 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 :term:`client` platform in the :ref:`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 :term:`client` platform page that must be monitored. 4. Verify established API communication at the :tirreno:`Tirreno` :term:`console`. .. _parameters: Parameters ---------- The :term:`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 :term:`sensor` always responds with the code ``204``, even when receiving non-valid data. Therefore, this only enables monitoring the :term:`sensor`’s availability. To confirm the processing status of requests, refer to the :ref:`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. .. index:: single: Required Parameters .. _required-parameters: Required Parameters ^^^^^^^^^^^^^^^^^^^ ``userName`` A :term:`user` identifier. It must be a unique value assigned to a :term:`user` by a :term:`client` platform. It serves to distinguish one :term:`user` from another and is employed by :tirreno:`Tirreno` to recognize individual users. ``emailAddress`` An email address associated with a :term:`user`. ``ipAddress`` An IP address associated with an :term:`event`. It can be retrieved from HTTP request headers. ``url`` A URL path of a :term:`resource` requested on a :term:`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 :term:`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: Optional Parameters ^^^^^^^^^^^^^^^^^^^ ``firstName`` A :term:`user`’s first name. ``lastName`` A :term:`user`’s last name. ``fullName`` A :term:`user`’s whole name. ``pageTitle`` A title of a visited :term:`resource`. ``phoneNumber`` A :term:`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. .. index:: single: Event Type .. _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 :term:`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: Code Examples ------------- .. _event-data: Event Data ^^^^^^^^^^ This subsection demonstrates how to build an associative array with :term:`event` details. The full code examples of API requests for sending :term:`event` data in different programmer languages are presented in the :ref:`Send Event ` subsection. .. tabs:: .. tab:: PHP .. literalinclude:: /examples/event-data.php :language: php :linenos: :caption: event-data.php .. tab:: Python .. literalinclude:: /examples/event-data.py :language: python :linenos: :caption: event-data.py .. tab:: Node.js .. literalinclude:: /examples/event-data.js :language: javascript :linenos: :caption: event-data.js .. tab:: Ruby .. literalinclude:: /examples/event-data.rb :language: ruby :linenos: :caption: event-data.rb .. _send-event: Send Event ^^^^^^^^^^ In the following code snippet, replace ```` with the corresponding Tirreno tracking code value. It can be obtained on the :ref:`API ` page of the :term:`console`. .. tabs:: .. tab:: PHP .. literalinclude:: /examples/post-event.php :language: php :linenos: :caption: send-event.php .. tab:: Python .. literalinclude:: /examples/post-event.py :language: python :linenos: :caption: send-event.py .. tab:: Node.js This code snippet is intended to work starting Node.js version 10.0. Earlier versions require another approach. .. literalinclude:: /examples/post-event-node.js :language: javascript :linenos: :caption: send-event-node.js .. tab:: Ruby .. literalinclude:: /examples/post-event.rb :language: ruby :linenos: :caption: send-event.rb