Quick start guide

Table of contents

• Introduction
• Step 1: Create a Contentful account
• Step 2: Create a new space in the Contentful web app
• Step 3: Install and configure Contentful Personalization
• Step 4: Install and integrate the Experience SDK
• Step 5: Enable built-in AI Features for the Analytics Agent

Introduction

This quick start guide walks you through setting up Contentful Analytics from scratch.

It assumes that your application implements Contentful Analytics in a React-based frontend and covers the following steps:

1. Create a Contentful account.

2. Create a new space in the Contentful web app.

3. Install and configure Contentful Personalization.

4. Install and integrate the Experience SDK.

   NOTE: Use version 7.17.6 or later.

5. Enable Built-in AI Features for the Analytics Agent.

Step 1: Create a Contentful account

To create a Contentful account:

1. Open the sign-up form.
2. Enter the required details to set up your account.
3. Select the CAPTCHA check box.
4. Click Sign up. Your account is created.

Step 2: Create a new space in the Contentful web app

To create a new space:

1. Log in to the Contentful web app.
2. Click the environment switcher.
3. Click the organization name, and select Organization settings & subscriptions.
4. Navigate to the "Spaces" tab. The spaces overview page is displayed.
5. Click Add new space. The space configuration page is displayed.
6. Choose a space license for your space, and click Continue.
7. Enter your space details, and click Continue.
8. Review the details, and, if everything is in order, click Confirm and create. Your space is created.

Step 3: Install and configure Contentful Personalization

To install and configure Contentful Personalization:

1. Log in to the Contentful web app.
2. Click Apps, and select Marketplace.
3. Search for Contentful Personalization, and click on its name. The “App details” page is displayed.
4. Click Install. The “Manage app access” modal is displayed.
5. Select the environment in which you want to install the app.
6. Click Authorize access. The Contentful Personalization configuration page is displayed with an overview of the upcoming steps required to correctly configure the app.
7. Click Install. The app is successfully installed and the configuration page is displayed.
8. Select the data bucket you want to connect to: Main or Development. For more information about data buckets, see the Data buckets page in the Help Center.
9. On the "Analytics content types" tab, select the content types you want to extend with Contentful Analytics. Each content type you select will include an additional "Analytics" tab in the entry editor for any entry of that content type.
10. Click Save.

Step 4: Install and integrate the Experience SDK

The fastest way to integrate Contentful Analytics into your application is by using our JavaScript Experience SDK.

The installation and integration can be broken down into four steps:

a. Install the SDK

Install a suitable version of the Experience SDK for your application and install the Insights Plugin.

b. Create a Ninetailed instance

The Experience SDK provides a Ninetailed instance that holds and updates the profile that identifies a user and provides methods to send events to the Experience API. It is instantiated by providing the API key and environment, and can be further configured through optional parameters.

The API key is the Client ID field value displayed under the "SDK Keys" section, on the Optimization tab.

Your environment will be either main or development.

c. Create and send events

In Contentful Analytics, user activities are stored as page, track, and identify events, which the application sends to the Experience API.

Integrate your application with Contentful Analytics by ensuring that the application:

• Sends a page event when a user views a page.
• Sends a track event when a user performs an action that you want to measure.
• Sends an identify event when a user performs an action that identifies them as a user who has visited the application before.
• Sends a component event when a user views a Contentful entry. component events are automatically sent by the SDK.

The Experience SDK provides an <EntryAnalytics /> component for wrapping React components. A wrapped component will automatically send a component event to the Experience API if a user views it.

Sending events directly to the API is possible, but using the Experience SDK is much more convenient. For more information on integrating your application with the Experience SDK, see the Send events section of its documentation.

d. Validate your integration

We recommend using Live Events to validate your setup and confirm that Contentful is receiving the event types required for Analytics.

To access Live Events:

1. Log in to the Contentful web app.
2. Navigate to the “Optimization” tab.
3. In the left sidebar, click Live Events.
4. Enable the Live event streaming toggle.
5. Load a page that contains tracked content, and trigger a user action that sends a track event. For example, clicking a button on the page.
   If your setup is working correctly, you should see at least page, track, and component events displayed in the event stream on the Live Events page.

The Events dashboard displays the type of events that Contentful Analytics receives over time, and the Event streaming log lists individual events. If you want to inspect an event more closely, open its event details and review the JSON payload.

When checking the JSON payload for component events, confirm that the payload identifies the viewed component correctly. If the component was rendered as part of a personalization or experiment, also confirm that the payload includes the associated experience metadata, such as experienceId. This is especially important for sticky variant persistence, where experienceId and variantIndex must be present.

Troubleshoot

If no events appear

If no events appear in Live Events, check that your setup is sending events at all. The most common issues are:

• an incorrect SDK API key
• the wrong environment
• not triggering any events in the application.

Make sure the Live event streaming toggle is enabled, then reload a tracked page and trigger a user action that should send a track event.

If component events are missing

If only page and track events are displayed, but no component events, the most common cause is that your components are not being tracked correctly.

For React-based setups, make sure Contentful entries are wrapped in <EntryAnalytics /> or <Experience />, and that the Insights Plugin is installed since it is required for component events to be generated and sent.

Step 5: Enable built-in AI Features for the Analytics Agent

The Analytics Agent is the AI assistant that allows you to ask contextual questions about your content and instantly receive AI-powered content answers, both as text and visual elements. The Analytics Agent relies on Contentful's AI features, so you must first enable them at the organization level.

To enable AI features at the organization level:

1. Log in to the Contentful web app.
2. Navigate to the “Optimization” tab.
3. In the left sidebar, click Analytics Agent.
4. Click Go to Organization Settings.
5. Click Continue to organization settings.
6. Enable the Built-in AI Features option.
7. Review the pricing and number of approved output words modal, then click Enable.
8. Review Contentful’s AI Terms of Service. If you agree, click Accept terms to enable built-in AI features.