Adapters

Version: 1.x

Adapters provide environment-specific implementations for plugins. They handle differences between browser and server environments, such as cookie management, request and response handling, and reading the current location. In the analytics layer, adapters implement the AnalyticsAdapter interface, which extends the generic PluginAdapter from @sitecore-content-sdk/core.

The built-in AnalyticsAdapter interface is as follows:

export interface AnalyticsAdapter extends PluginAdapter {
  isBot?: () => boolean;
  getClientId: () => string | null;
  setClientId: () => Promise<void>;
  location: {
    getSearchParams: () => string;
  };
}

Field	Description
`isBot()`	Optional function that returns whether the current visitor is a bot.
`getClientId()`	Gets the visitor client ID, or returns `null` when one is not available.
`setClientId()`	Gets or creates the client ID and stores it using the environment-specific implementation.
`location.getSearchParams()`	Returns the current URL search parameters.

Adapters are passed to plugins during initialization. This allows each plugin to remain independent of the environment in which it runs. For example, the analytics plugin calls getClientId() and setClientId() without directly accessing window, document, or a Node.js request. The adapter performs those environment-specific operations.

How adapters work in an Angular application

You do not construct the built-in adapters yourself. provideSitecoreAngular() registers the SITECORE_ANALYTICS injection token and selects the browser or server analytics implementation based on the current platform. Each implementation initializes the Content SDK with the matching adapter.

import { inject } from '@angular/core';
import { SITECORE_ANALYTICS } from '@sitecore-content-sdk/angular';

private readonly analytics = inject(SITECORE_ANALYTICS);

The same injected service can be used in browser and server-side rendering (SSR) code. The browser implementation uses the browser adapter, and the SSR implementation uses the server adapter with the current request and response.

await this.analytics.pageView({
  channel: 'WEB',
  currency: 'USD',
  page,
  language,
});

This removes the need for platform checks in components that send analytics events. Initialization is lazy and occurs when the analytics service sends its first event.

The Express middleware, which executes outside of Angular injection context, performs initialization separately, but otherwise follows the same pattern. createBotTrackingMiddleware() and createPersonalizeMiddleware() create server adapters from the live Express request and response before initializing the required plugins.

Using a custom adapter

Use a custom adapter when the default visitor identification or storage behavior does not fit your application. For example, you might obtain client IDs from an identity service or store them outside the cookies managed by the SDK.

The adapter must implement AnalyticsAdapter. Browser adapters must also set type to 'browser'.

import type { AnalyticsBrowserAdapter } from '@sitecore-content-sdk/analytics-core';

export function customBrowserAdapter(): AnalyticsBrowserAdapter {
  return {
    type: 'browser',
    getClientId: () => window.localStorage.getItem('my_client_id'),
    setClientId: async () => {
      window.localStorage.setItem('my_client_id', await fetchClientIdFromMyService());
    },
    isBot: () => /bot|crawler|spider/i.test(navigator.userAgent),
    location: {
      getSearchParams: () => window.location.search,
    },
  };
}

See Lightweight tracking and Plugins for the plugin dependencies and the Angular integration points. When migrating from a JSS Angular application, replace direct @sitecore-cloudsdk initialization with the SITECORE_ANALYTICS facade and configure custom event or consent behavior through that facade. See Upgrade JSS 22.x Angular apps to Content SDK for Angular 1.0 for migration details.

For a full walkthrough of overriding the default analytics implementation and registering additional plugins, see Analytics customization.

If you have suggestions for improving this article, let us know!