Contentful Personalization & Analytics

API Client

The Contentful Optimization API Client Library provides methods for interfacing with Contentful's Experience and Insights APIs, which serve its Personalization and Analytics products.

Getting Started

Install using an NPM-compatible package manager, pnpm for example:

pnpm install @contentful/optimization-api-client
Copy

Import the API client; both CJS and ESM module systems are supported, ESM preferred:

import { ApiClient } from '@contentful/optimization-api-client'
Copy

Configure and initialize the API Client:

const client = new ApiClient({ clientId: 'abc123' })
Copy

Configuration

Top-level Configuration Options

Fetch Options

Fetch options allow for configuration of both a Fetch API-compatible fetch method and the retry/timeout logic integrated into the Optimization API Client. Specify the fetchMethod when the host application environment does not offer a fetch method that is compatible with the standard Fetch API in its global scope.

Configuration method signatures:

• fetchMethod: (url: string \| URL, init: RequestInit) => Promise<Response>
• onFailedAttempt and onRequestTimeout: (options: FetchMethodCallbackOptions) => void

Analytics Options

Configuration method signatures:

• beaconHandler: (url: string | URL, data: BatchInsightsEventArray) => boolean

Personalization Options

Working With the APIs

Experience API

Experience API methods are scoped to the client's experience member. All singular experience methods return a Promise that resolves with the following data:

{
  "profile": {
    /* User profile data */
  },
  "personalizations": [
    {
      /* Personalization/experience configuration for the associated profile */
    }
  ],
  "changes": [
    {
      /* Similar to `personalizations` but currently used for Custom Flags */
    }
  ]
}
Copy

Get Profile data

const client = new ApiClient({ clientId: 'abc123' })
const { profile } = await client.experience.getProfile('profile-123', { locale: 'de-DE' })
Copy

Create a New Profile

const client = new ApiClient({ clientId: 'abc123' })
const { profile } = await client.experience.createProfile({ events: [...] }, { locale: 'de-DE' })
Copy

Update an Existing Profile

const client = new ApiClient({ clientId: 'abc123' })
const { profile } = await client.experience.updateProfile(
  {
    profileId: 'profile-123',
    events: [...],
  },
  { locale: 'de-DE' }
)
Copy

Upsert a Profile

const client = new ApiClient({ clientId: 'abc123' })
const { profile } = await client.experience.upsertProfile(
  {
    profileId,
    events: [...],
  },
  { locale: 'de-DE' }
)
Copy

Upsert Many Profiles

The upsertManyProfiles method returns a Promise that resolves with an array of user profiles. The events array must contain at least one event. Each event should have an additional anonymousId property set to the associated anonymous ID or profile ID.

const client = new ApiClient({ clientId: 'abc123' })
const profiles = await client.experience.upsertManyProfiles(
  {
    events: [
      {
        anonymousId: 'anon-123',
        // valid Experience event payload fields
      },
    ],
  },
  { locale: 'de-DE' },
)
Copy

Insights API

Insights API methods are scoped to the client's insights member. The batch send method returns a Promise that resolves to boolean.

Send Batch Events

const client = new ApiClient({ clientId: 'abc123' })
await client.insights.sendBatchEvents([
  {
    profile: { id: 'abc-123', ... },
    events: [
      {
        type: 'component',
        componentId: 'hero-banner',
        componentType: 'Entry',
        variantIndex: 0,
        ...,
      },
    ],
  }
])
Copy

Event Builder

The Event Builder is a helper class that assists in constructing valid events for submission to the Experience and Insights APIs.

Event Builder Configuration

Event Builder configuration options assist in adding contextual data to each event created by a builder instance.

The get* functions are most useful in stateful environments. Stateless environments should set the related data directly via Event Builder method arguments.

The channel option may contain one of the following values:

• web
• mobile
• server

Configuration method signatures:

• getLocale: () => string | undefined

• getPageProperties:

  () => {
    path: string,
    query: Record<string, string>,
    referrer: string,
    search: string,
    title?: string,
    url: string
  }
  Copy

• getUserAgent: () => string | undefined

Event Builder Configured Methods

• buildComponentClick: Builds a component click event payload for a Contentful entry-based component
• buildComponentView: Builds a component view event payload for a Contentful entry-based component
• buildFlagView: Builds a component view payload event for a Custom Flag component
• buildIdentify: Builds an identify event payload to associate a user ID with traits
• buildPageView: Builds a page view event payload
• buildScreenView: Builds a screen view event payload
• buildTrack: Builds a track event payload for arbitrary user actions

See the Event Builder documentation for more information regarding arguments and return values.