Engagement Adapter Pattern

The adapter pattern decouples analytics components from vendor-specific event APIs. Components call a generic interface and the adapter translates those calls into the vendor’s API. Storefront Next provides three built-in adapters for analytics event tracking that use Einstein, Active Data, and Data 360 (formerly Data Cloud).

Adapter	Purpose	Config key
Einstein	Analytics event tracking (viewProduct, addToCart, and so on)	`engagement.adapters.einstein`
Active Data	Analytics event tracking (dwac beacon)	`engagement.adapters.activeData`
Data 360	Salesforce Data 360 — view/impression events only	`engagement.adapters.data360`

All three implement the EngagementAdapter interface and are registered in a shared store.

Architecture

1┌─────────────────────────────────────────────────────────────┐
2│                     Component Layer                         │
3│  (PageViewTracker, AddToCartButton, etc.)                   │
4└──────────────────────────┬──────────────────────────────────┘
5                           │ sendEvent(event)
6                           ↓
7┌─────────────────────────────────────────────────────────────┐
8│                     Adapter Store                           │
9│  Map<string, EngagementAdapter>                             │
10│  + ensureAdaptersInitialized() (lazy, idempotent)           │
11└──────────────────────────┬──────────────────────────────────┘
12                           │
13                           ↓
14┌─────────────────────────────────────────────────────────────┐
15│              Vendor Implementations                         │
16│  createEinsteinAdapter → POST to api.cquotient.com          │
17│  createActiveDataAdapter → pixel/beacon requests            │
18│  createData360Adapter → sendBeacon to                       │
19│    {tenantId}.c360a.salesforce.com                          │
20└─────────────────────────────────────────────────────────────┘

File Structure

1src/lib/adapters/
2├── index.ts                        # Re-exports store, types, utils
3└── engagement/
4    ├── types.ts                    # EngagementAdapter interface, EngagementAdapterConfig
5    ├── store.ts                    # addAdapter, getAdapter, getAllAdapters, removeAdapter
6    ├── einstein.ts                 # createEinsteinAdapter factory (analytics events only)
7    ├── active-data.ts              # createActiveDataAdapter factory
8    ├── data360.ts                  # createData360Adapter factory (view/impression events only)
9    ├── register.ts                 # initializeEngagementAdapters (reads config, creates + registers)
10    ├── initialize.ts               # ensureAdaptersInitialized (idempotent, lazy-loads register.ts)
11    ├── einstein-config.ts          # validateEinsteinConfig helper
12    ├── data360-config.ts           # Data360Config type + validateData360Config helper
13    └── utils.ts                    # hasConsent helper

Adapter Interface

1// src/lib/adapters/engagement/types.ts
2export interface EngagementAdapter extends EventAdapter {
3  name: string;
4  sendEvent?: (
5    event: AnalyticsEvent,
6    siteInfo?: EventSiteInfo,
7    consentPreferences?: ConsentPreferences,
8  ) => Promise<unknown>;
9  send?: (url: string, options?: RequestInit) => Promise<Response>;
10}

Adapter Store

A Map<string, EngagementAdapter> with functional accessors:

1addAdapter("einstein", adapter); // Register
2getAdapter("einstein"); // Retrieve by name
3getAllAdapters(); // All registered adapters
4removeAdapter("einstein"); // Unregister

Lazy Initialization

Adapter code is dynamically imported to stay out of the initial bundle:

1// src/lib/adapters/engagement/initialize.ts
2export async function ensureAdaptersInitialized(appConfig: AppConfig): Promise<void> {
3  if (getAllAdapters().length > 0) return; // Already done
4  const { initializeEngagementAdapters } = await import("./register");
5  initializeEngagementAdapters(appConfig);
6}

The dynamic import() means that the Einstein, Active Data, and Data 360 implementation modules are code-split into a separate chunk.

Configuration

Adapters are configured in config.server.ts under engagement.adapters:

1engagement: {
2    adapters: {
3        einstein: {
4            enabled: true,
5            host: 'https://api.cquotient.com',
6            einsteinId: '<your-einstein-id>',
7            siteId: '<your-site-id>',
8            realm: '<realm>',
9            isProduction: false,
10            consentCategory: 'analytics',
11            eventToggles: { view_product: true, cart_item_add: true, ... },
12        },
13        activeData: {
14            enabled: true,
15            host: '<host>',
16            siteUUID: '<uuid>',
17            consentCategory: 'analytics',
18            eventToggles: { view_product: true, cart_item_add: true, ... },
19        },
20        data360: {
21            enabled: true,
22            appSourceId: '<your-app-source-id>',
23            tenantId: '<your-tenant-id>',
24            siteId: '<your-site-id>',
25            webStoreId: 'sfnext',           // separates Storefront Next traffic from PWA Kit's in a shared DLO
26            consentCategory: 'analytics',
27            eventToggles: { view_product: true, view_category: true, ... },
28        },
29    },
30},

If an adapter’s enabled flag is false, it isn’t registered.

Data 360 maps only view and impression events — view_page, view_product, view_search, view_category, and view_recommender. Cart, checkout, wishlist, and click events have no Data 360 mapping and ship disabled in eventToggles.

For how to provision Data 360 and connect your storefront, see Send Storefront Next Analytics Events to Data 360.

Testing

Mocking Adapters in Tests

1import { addAdapter, removeAdapter } from "@/lib/adapters";
2
3const mockAdapter: EngagementAdapter = {
4  name: "mock-einstein",
5  sendEvent: vi.fn().mockResolvedValue(undefined),
6};
7
8beforeEach(() => addAdapter("einstein", mockAdapter));
9afterEach(() => removeAdapter("einstein"));

Testing Initialization

1import { resetAdaptersInitialization } from "@/lib/adapters/engagement/initialize";
2
3afterEach(() => resetAdaptersInitialization()); // Clear cached promise for clean state

Add an Engagement Adapter

Create src/lib/adapters/engagement/your-adapter.ts with a factory function returning EngagementAdapter.
Register it in src/lib/adapters/engagement/register.ts inside initializeEngagementAdapters().
Add configuration under engagement.adapters.yourAdapter in config.server.ts.