Class ExperienceApiClient

Client for interacting with the Experience API.

Remarks

This client is responsible for reading and mutating Ninetailed profiles using the Experience API.

Example

const client = new ExperienceApiClient({
  clientId: 'org-id',
  environment: 'main',
})

const profile = await client.getProfile('profile-id')

Extends ApiClientBase.

Hierarchy

ApiClientBase
- ExperienceApiClient

Index

Constructors

constructor

new ExperienceApiClient(config: ExperienceApiClientConfig): ExperienceApiClient
Creates a new ExperienceApiClient instance.
Parameters
- config: ExperienceApiClientConfig
  Configuration for the Experience API client.
Returns ExperienceApiClient
Overrides ApiClientBase.constructor
- Defined in api-client/src/experience/ExperienceApiClient.ts:186

Properties

`Protected` `Readonly`baseUrl

baseUrl: string

Base URL used for Experience API requests.

`Protected` `Readonly`clientId

clientId: string

Client identifier used for authentication or tracking.

`Protected` `Readonly`environment

environment: string

Contentful environment associated with this client.

`Protected` `Readonly`fetch

fetch: FetchMethod

Protected fetch method used by the client to perform HTTP requests.

`Protected` `Readonly`name

name: string

Name of the API client, used in log messages and as the apiName for fetch.

Methods

createProfile

createProfile(
params: CreateProfileParams,
options?: ExperienceApiClientRequestOptions,
): Promise<OptimizationData>
Creates a profile and returns the resulting optimization data.
Parameters
- params: CreateProfileParams
  Parameters containing the events to aggregate into the profile.
- options: ExperienceApiClientRequestOptions = {}
  Optional request options.
Returns Promise<OptimizationData>
The optimization data for the newly created profile.
Remarks
The returned profile ID can be used for subsequent update requests.
Example
```
const data = await client.createProfile({
  events: [{ type: 'identify', userId: 'user-123' }],
})
```
- Defined in api-client/src/experience/ExperienceApiClient.ts:292

getProfile

getProfile(
    id: string,
    options?: Omit<
        ExperienceApiClientRequestOptions,
        "preflight"
        | "plainText",
    >,
): Promise<OptimizationData>
Retrieves a profile by ID.
Parameters
- id: string
  The profile ID to retrieve.
- options: Omit<ExperienceApiClientRequestOptions, "preflight" | "plainText"> = {}
  Optional request options. preflight and plainText are not allowed here.
Returns Promise<OptimizationData>
The current optimization data for the profile.
Throws
Error Thrown if id is missing or the underlying request fails.
Example
```
const profile = await client.getProfile('profile-id', {
  locale: 'en-US',
})
```
- Defined in api-client/src/experience/ExperienceApiClient.ts:217

`Protected`logRequestError

logRequestError(error: unknown, options: { requestName: string }): void
Logs errors that occur during API requests with standardized messages.
Parameters
- error: unknown
  The error thrown by the underlying operation.
- options: { requestName: string }
  Additional metadata about the request.
  - requestName: string
    Human-readable name of the request operation.
Returns void
Remarks
Abort errors are logged at warn level and other errors at error level. The log message includes the client name for better debugging context.
Inherited from ApiClientBase.logRequestError
- Defined in api-client/src/ApiClientBase.ts:132

updateProfile

updateProfile(
params: UpdateProfileParams,
options?: ExperienceApiClientRequestOptions,
): Promise<OptimizationData>
Updates an existing profile with the given profile ID.
Parameters
- params: UpdateProfileParams
  Parameters including the profile ID and events.
- options: ExperienceApiClientRequestOptions = {}
  Optional request options.
Returns Promise<OptimizationData>
The updated optimization data for the profile.
Throws
Error Thrown if profileId is missing or the underlying request fails.
Example
```
const data = await client.updateProfile({
  profileId: 'profile-id',
  events: [{ type: 'track', event: 'viewed_video' }],
})
```
- Defined in api-client/src/experience/ExperienceApiClient.ts:345

upsertManyProfiles

upsertManyProfiles(
    params: BatchUpdateProfileParams,
    options?: ExperienceApiClientRequestOptions,
): Promise<
    | {
        audiences: string[];
        id: string;
        location: {
            city?: string;
            continent?: string;
            coordinates?: { latitude: number; longitude: number };
            country?: string;
            countryCode?: string;
            postalCode?: string;
            region?: string;
            regionCode?: string;
            timezone?: string;
        };
        random: number;
        session: {
            activeSessionLength: number;
            averageSessionLength: number;
            count: number;
            id: string;
            isReturningVisitor: boolean;
            landingPage: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
        };
        stableId: string;
        traits: Record<string, JSONType>;
    }[]
    | undefined,
>
Sends multiple events to the Ninetailed Experience API to upsert many profiles.
Parameters
- params: BatchUpdateProfileParams
  Parameters containing the batch of events.
- options: ExperienceApiClientRequestOptions = {}
  Optional request options.
Returns Promise<
    | {
        audiences: string[];
        id: string;
        location: {
            city?: string;
            continent?: string;
            coordinates?: { latitude: number; longitude: number };
            country?: string;
            countryCode?: string;
            postalCode?: string;
            region?: string;
            regionCode?: string;
            timezone?: string;
        };
        random: number;
        session: {
            activeSessionLength: number;
            averageSessionLength: number;
            count: number;
            id: string;
            isReturningVisitor: boolean;
            landingPage: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
        };
        stableId: string;
        traits: Record<string, JSONType>;
    }[]
    | undefined,
>
The list of profiles affected by the batch operation.
Remarks
Batch requests must contain at least one event. Every event must contain an anonymous ID. Profiles will be created or updated according to the anonymous ID.

This method is intended to be used from server environments.
Example
```
const profiles = await client.upsertManyProfiles({
  events: [
    { anonymousId: 'anon-1', type: 'identify', ... },
    { anonymousId: 'anon-2', type: 'identify', ... },
  ],
})
```
- Defined in api-client/src/experience/ExperienceApiClient.ts:433

upsertProfile

upsertProfile(
params: UpsertProfileParams,
options?: ExperienceApiClientRequestOptions,
): Promise<OptimizationData>
Creates or updates a profile depending on whether a profileId is provided.
Parameters
- params: UpsertProfileParams
  Parameters including optional profile ID and events.
- Optionaloptions: ExperienceApiClientRequestOptions
  Optional request options.
Returns Promise<OptimizationData>
The resulting optimization data.
Example
```
// Create
await client.upsertProfile({ events })

// Update
await client.upsertProfile({ profileId: 'profile-id', events })
```
- Defined in api-client/src/experience/ExperienceApiClient.ts:398

Class ExperienceApiClient

Remarks

Example

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns ExperienceApiClient

Properties

Protected ReadonlybaseUrl

Protected ReadonlyclientId

Protected Readonlyenvironment

Protected Readonlyfetch

Protected Readonlyname

Methods

createProfile

Parameters

Returns Promise<OptimizationData>

Remarks

Example

getProfile

Parameters

Returns Promise<OptimizationData>

Throws

Example

ProtectedlogRequestError

Parameters

requestName: string

Returns void

Remarks

updateProfile

Parameters

Returns Promise<OptimizationData>

Throws

Example

upsertManyProfiles

Parameters

Remarks

Example

upsertProfile

Parameters

Returns Promise<OptimizationData>

Example

Settings

On This Page

`Protected` `Readonly`baseUrl

`Protected` `Readonly`clientId

`Protected` `Readonly`environment

`Protected` `Readonly`fetch

`Protected` `Readonly`name

`Protected`logRequestError