Contentful Personalization & Analytics

API Client

The Contentful Optimization API Client Library provides methods for interfacing with Contentful's Experience API and Insights API, 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 this 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

Insights API Options

Configuration method signatures:

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

Experience API Options

Working With the APIs

Experience API

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

{
  "profile": {
    /* User profile data */
  },
  "selectedOptimizations": [
    {
      /* Optimization/Experience API configuration for the associated profile */
    }
  ],
  "changes": [
    {
      /* Custom Flag changes associated with the evaluated profile */
    }
  ]
}
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 API 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 Construction

Event-construction helpers (EventBuilder) are part of @contentful/optimization-core and environment SDKs that build on top of it. This package focuses on API transport and request/response validation.