Headless tracking

Websites running in Xperience by Kentico can track visitors as contacts and log their activities. Headless tracking allows you to extend these features to the audience of other content channels, such as mobile apps, external services, single-page applications, etc. Xperience then serves as a central hub where you can monitor contacts and analyze activities for all connected websites and channels.

For example, headless tracking is suitable for applications that retrieve and display content from Xperience through headless channels.

Headless tracking works as a REST API. The Xperience application provides endpoints to which you send HTTP requests from your external applications.

The following steps outline the typical process for setting up headless tracking in an external application:

• Ensure authentication and CORS for your requests
• Display one or more tracking consents from Xperience to your application's users
• Allow users to accept or revoke the consents
• For users who have given a consent agreement to be tracked:
  • Create contacts in Xperience to represent individual users
  • Log activities for the contacts
    • Use the Data input activity to send or update information about contacts
    • You can set up custom activity types for any actions that you wish to track in your application.

Authentication and CORS

To authenticate headless tracking requests, you need to:

1. Set up a headless channel in Xperience.
2. Create at least one API key with the Access type set to Tracking API.

For each tracking API request, add the Authorization⁠ (opens in a new tab) header containing an enabled tracking API key.

Authorization: Bearer <ApiKey>

If sending tracking requests directly from the client-side code of a web application (without additional header processing on a proxy server), you also need to ensure Cross-Origin Resource Sharing (CORS)⁠ (opens in a new tab).

Follow the instructions in Cross-origin resource sharing — the CORS configuration options are shared for headless tracking endpoints and headless channel GraphQL endpoints.

Get the text of consents from Xperience

To comply with data protection regulations, most applications can only collect personal data and track activities for users who explicitly give consent.

Set up your consents in Xperience, and retrieve their text by sending requests:

• HTTP method: GET

• Endpoint: /Kentico.Tracking/consents/{consent_code_name}?languageName={language_code_name}

• URI example: https://domain.com/Kentico.Tracking/consents/TrackingConsent?languageName=en

• Response body: Consent text strings in the shortText and fullText fields

  JSON

  Copy

  {
      "shortText": "...",
      "fullText": "..."
  }

  Consent text format

  The returned consent text strings contain HTML tags – text formatting elements, <p> tags for paragraphs, etc.

Create an appropriate UI in your application that displays the retrieved texts and allows users to give consent agreements.

Create contacts

Your application's users are represented as contacts in Xperience. When a user gives consent to be tracked, you can create a new contact in Xperience by sending the following request:

• HTTP method: POST

• Endpoint: /Kentico.Tracking/contacts

• Response body: GUID of the new contact in the contact field

  JSON

  Copy

  {
      "contact": "06b035b8-6658-4a1b-b1de-5994e4975fb1"
  }

The returned contact GUID is an identifier that you need to store in your application. Link the identifier with any other data that you have about the user. This allows you to keep track of the user in your application, identify them whenever they return, and pair them with the same contact.

The GUID is a required parameter whenever you need to manage the contact's consent agreements or log activities.

Add or revoke a consent agreement

To add or revoke a consent agreement for a contact, send the following request:

• HTTP method: POST

• Endpoint: /Kentico.Tracking/contacts/{contact_guid}/consents/{consent_name}

• URI example: https://domain.com/Kentico.Tracking/contacts/06b035b8-6658-4a1b-b1de-5994e4975fb1/consents/TrackingConsent

• Request headers: The Content-Type⁠ (opens in a new tab) header must be set to application/json.

• Request body: Set the agree field to true (agree) or false (revoke)

  JSON

  Copy

  {
      "agree": true
  }

Check whether a contact has given a consent agreement

To check whether a contact currently has a valid agreement for a consent, send the following request:

• HTTP method: GET

• Endpoint: /Kentico.Tracking/contacts/{contact_guid}/consents/{consent_name}

• URI example: https://domain.com/Kentico.Tracking/contacts/06b035b8-6658-4a1b-b1de-5994e4975fb1/consents/TrackingConsent

• Response body: true or false value in the isAgreed field

  JSON

  Copy

  {
      "isAgreed": true
  }

Log activities

The headless tracking API allows you to log the following types of activities:

• Page visit – represents a single view of a "page" in your application.
• Click – represents a "click" action performed by a user.
• Data input – allows you to update the data of contacts using information submitted by the user.
• Custom activity types – can represent any action that you wish to track.

Log activities by sending the following requests:

• HTTP method: POST
• Endpoint: /Kentico.Tracking/activities
• Request headers: The Content-Type⁠ (opens in a new tab) header must be set to application/json.
• Request body:

  • channel – the GUID identifier of the headless channel under which the activity will be logged.

    • Find the identifier in the Xperience administration: Channel management → edit channel → General → Channel identifier for Tracking API
    • The identifier must match the parent channel of the API key used to authenticate the logging request.

  • contact – the GUID of the contact who performed the activity (see Create contacts).

  • activities – an array of activity objects. You can log any number of activities within a single request. See below to learn about the data structure of activity objects.

For each activity object in the activities array, set the following fields:

• type – the code name of the activity type that you wish to log. Use the following values:

  • pagevisit
  • click
  • datainput
  • <activity type code name> for custom activities

• value – a value logged with the activity. Required for Click and Data input activities.

• url – optional for all activity types (except Page visit). Currently not displayed in the activity log within the Xperience administration.

• referrer – an optional URL referrer⁠ (opens in a new tab) value. Currently not displayed in the activity log within the Xperience administration.

Additionally, individual activity types have additional requirements:

{
    "channel": "a3f4bc8b-6d84-454f-8215-cbec70bfaadd",
    "contact": "06b035b8-6658-4a1b-b1de-5994e4975fb1",
    "activities": [
        {
            "type": "pagevisit",
            "url": "https://example.com/mypage"
        },
        {
            "type": "click",
            "value": "MyClickableElement"
        },
        {
            "type": "datainput",
            "value": "Registration form",
            "contactFields": 
            {
                "ContactFirstName": "Luke",
                "ContactLastName" : "Smith",
                "ContactEmail" : "lsmith@domain.com"
            }
        },
        {
            "type": "custom_loan_calculator",
            "value": "5000"
        }
    ]
}

Activity logging requests return an HTTP 207 Multi-Status⁠ (opens in a new tab) response. The response body contains a results array where you can find the HTTP status code for individual submitted activities.

{
    "results": [
        {
            "status": 202,
        },
        {
            "status": 202
        }
    ]
}