Interaction tracking in Node and stateless environments

Overview

Use this concept document when a Node or stateless server runtime owns personalization and rendering, but the application still needs Analytics events for server-rendered content. It explains what the Node SDK can track from the server, what requires a browser runtime, and how server-generated HTML can use the Web SDK for interaction tracking without moving personalization client-side.

• For step-by-step server setup, see Integrate the Optimization Node SDK in a Node app.
• For browser setup, see Integrate the Optimization Web SDK in a web app.
• For Web SDK interaction tracking mechanics, see Interaction tracking in Web SDKs.
• For profile handoff between server and browser, see Profile synchronization between client and server.

Runtime decision summary

Choose the runtime path before designing the event flow. The SDK that renders or observes the interaction decides which facts are available.

Constraints that decide delivery

Apply these constraints before choosing server-only, hybrid, or manual tracking:

• Consent is application policy. The SDK blocks events unless consent or allowedEventTypes permits the event type.
• Persistence consent decides whether profile continuity can survive beyond the current runtime. Persist ctfl-opt-aid, browser profile state, selected optimizations, and changes only when that policy permits durable continuity.
• Browser entry interactions use the wire event types component, component_click, and component_hover. Custom Flag views use component with componentType: 'Variable', but allowedEventTypes also accepts flag as a Custom Flag view selector. component allows both entry views and flag views before consent; flag narrows pre-consent admission to Custom Flag views without entry views.
• Browser Insights delivery needs a current Web SDK profile. In direct Web SDK initialization, the profile can come from defaults.profile. In React Web provider handoff and manual Next.js provider or root setup, pass server-returned Optimization data through serverOptimizationState. In the preferred App Router bound setup, the server root or provider from createNextjsAppRouterOptimization() hands off server data for the browser side automatically. In Pages Router, pass the server data returned by getServerSideOptimizationProps() through serverOptimizationState in pages/_app.tsx. The profile can also come from browser-persisted profile state that persistence consent allows the SDK to load, or a browser Experience API call such as page(), identify(), track(), or sticky trackView().
• Browser storage is best-effort. The Web SDK uses localStorage and the ctfl-opt-aid cookie when persistence consent permits continuity; if storage fails or is unavailable, continuity is limited to in-memory state.
• Serverless memory and background work are not durable stores. Await important server-side event calls before the response completes, or hand them to an application-owned durable queue.
• Offline browser queues are best-effort and browser-owned. They cannot make the original server request observe a later view, click, or hover.

The core boundary

The Node SDK can emit events, but it cannot observe a rendered page after the response leaves the server. That boundary is the main design constraint for interaction tracking in SSR, server functions, and other stateless environments.

A server request can know:

• which URL or route was requested
• which profile ID arrived with the request, if the application persisted one
• which Contentful baseline entry was fetched
• which variant resolveOptimizedEntry() selected from the current selectedOptimizations
• which HTML the server attempted to send
• which server-side business action happened, such as a form submission or checkout callback

A server request cannot know by itself:

• whether the browser received, rendered, or kept the HTML visible
• whether an entry crossed a viewport visibility threshold
• how long the entry stayed visible or hovered
• whether a real user clicked a rendered entry
• whether a client-side route changed after hydration
• whether consent changed after the response
• whether queued browser events flushed before unload

This means Node-only tracking can describe server-observed facts. Accurate view, click, and hover tracking for server-generated HTML still needs code in the browser or another runtime that can observe the final user interface.

What stateless tracking means

The Node SDK extends the stateless Core runtime. You can create one singleton SDK instance per module or process, but that singleton does not keep durable profile, consent, page, cookie, session, or browser-storage state across requests. Bind each incoming request’s inputs with forRequest() before emitting events.

The object returned by forRequest() is request-local. It retains the profile, consent, locale, page context, and request options passed at construction for that object’s lifecycle. Experience API responses from page(), identify(), track(), screen(), and sticky trackView() update that request-local profile, so later calls on the same request object can use the updated profile. Do not reuse a request object across independent HTTP requests.

In practice, the application must supply:

• the current profile ID, usually from ANONYMOUS_ID_COOKIE (ctfl-opt-aid) or a session
• the application policy decision for whether the server can call the SDK
• page context such as path, url, referrer, query, and locale
• user agent and optional IP override when server-side evaluation needs client request metadata
• the selected entry metadata needed for entry interaction events

The stateless methods are side-effecting API calls, not cacheable reads. Cache raw Contentful delivery payloads and resolve them per request. Do not cache page(), identify(), track(), screen(), trackView(), trackClick(), trackHover(), or trackFlagView() responses as if they were pure data lookups.

Event paths

Tracking uses two API paths with different semantics:

Sticky entry views are the exception that touches both paths. In Node, trackView({ sticky: true }) sends a view event through Experience first, then sends the paired Insights event using the profile returned by the Experience response. Non-sticky trackView() only uses Insights and therefore requires a request-bound profile ID.

The interaction wire event types are:

Server-side tracking capabilities

Use the Node SDK for events that the server can state truthfully.

Server-side page() is the normal SSR entry point. It records the page request, returns OptimizationData, and gives the server profile, selectedOptimizations, and changes for the render.

The examples below bind application-owned consent into a request-scoped client. Node SDK event calls fail closed except for the configured allowedEventTypes; the Node default permits identify and page before consent and labels those events as not consented.

Choose an application locale from your router, i18n, or request logic. Use that same value for CDA fetches and pass it to forRequest({ locale }) when Experience API responses and events need to use that locale. For the broader locale model, see Locale handling in the Optimization SDK Suite.

1
const appLocale = getAppLocale(req)
2
const requestOptimization = optimization.forRequest({
3
  consent: {
4
    events: appPolicyAllowsOptimizationEvent(req),
5
    persistence: appPolicyAllowsOptimizationEvent(req),
6
  },
7
  locale: appLocale,
8
  eventContext: {
9
    page: {
10
      path: req.path,
11
      query,
12
      referrer: req.get('referer') ?? '',
13
      search: url.search,
14
      url: url.toString(),
15
    },
16
    userAgent: req.get('user-agent') ?? 'node-server',
17
  },
18
  profile: profileId ? { id: profileId } : undefined,
19
})
20
21
const pageResult = await requestOptimization.page()
22
const pageResponse = pageResult.accepted ? pageResult.data : undefined
23
24
if (!pageResponse) {
25
  renderBaselineResponse()
26
  return
27
}

When the Node SDK is configured with a consumer-owned contentful.js client, prefer requestOptimization.fetchOptimizedEntry(entryId) after an accepted Experience call. The request-bound client uses the latest selectedOptimizations when they are omitted. Manual baselineEntry plus resolveOptimizedEntry() remains supported when the application owns CDA fetching or caching directly.

Both managed fetchOptimizedEntry() and manual resolveOptimizedEntry() expect single-locale CDA entry shapes. Avoid withAllLocales and locale=* for optimization surfaces.

Use server-side track() for server-known business events:

1
const appLocale = getAppLocale(req)
2
3
if (!pageResponse) {
4
  return
5
}
6
7
const requestOptimization = optimization.forRequest({
8
  consent: true,
9
  locale: appLocale,
10
  profile: pageResponse.profile,
11
})
12
13
await requestOptimization.track({
14
  event: 'quote_requested',
15
  properties: {
16
    plan: 'enterprise',
17
    source: 'pricing-page',
18
  },
19
})

Use server-side trackView() only when the event definition is “the server rendered this entry into the response”, not “the user saw this entry in the viewport”. If the business meaning requires real visibility, use browser tracking.

1
import { randomUUID } from 'node:crypto'
2
3
const appLocale = getAppLocale(req)
4
5
if (!pageResponse) {
6
  return
7
}
8
9
const { entry: resolvedEntry, selectedOptimization } = optimization.resolveOptimizedEntry(
10
  baselineEntry,
11
  pageResponse.selectedOptimizations,
12
)
13
14
const requestOptimization = optimization.forRequest({
15
  consent: true,
16
  locale: appLocale,
17
  profile: pageResponse.profile,
18
})
19
20
await requestOptimization.trackView({
21
  componentId: resolvedEntry.sys.id,
22
  experienceId: selectedOptimization?.experienceId,
23
  sticky: selectedOptimization?.sticky ?? false,
24
  variantIndex: selectedOptimization?.variantIndex,
25
  viewDurationMs: 0,
26
  viewId: randomUUID(),
27
})

Use trackClick() and trackHover() on the server only for interactions that the server actually receives, such as a POST route, redirect route, or first-party event collection endpoint. A server cannot infer a click or hover from the original HTML response.

Browser-side interaction capabilities

The Web SDK owns browser runtime mechanics that stateless Node does not own:

• consent state and event blocking in the browser
• profile, selected optimization, and change state in memory and localStorage
• anonymous ID persistence in ctfl-opt-aid
• sendBeacon and fetch(..., { keepalive: true }) delivery paths for Insights events
• offline and visibility-change flushing
• automatic DOM tracking for entry views, clicks, and hovers
• manual element tracking with optimization.tracking.enableElement(...)
• observable state for event streams and blocked-event diagnostics

For entry views, the Web SDK uses IntersectionObserver, dwell-time timers, visibility-change pause and resume, periodic duration updates, and final duration events when visibility ends. For clicks, it listens at the document level and resolves the nearest tracked entry plus a semantic clickable path. For hovers, it uses pointer or mouse enter and leave events with dwell-time timers.

Those browser mechanics are useful even when the server owns every personalization decision.

Use the Web SDK for tracking server-generated HTML

The hybrid pattern is:

1. Use @contentful/optimization-node on the server to evaluate the request, resolve entries, and render personalized HTML.
2. Add Web SDK tracking metadata to the rendered entry elements.
3. Initialize @contentful/optimization-web in the browser for consent, profile continuity, and interaction tracking.
4. Do not fetch Contentful entries or call resolveOptimizedEntry() in the browser unless the application also wants browser-side personalization after hydration.

This pattern keeps the personalization contract server-side while using the browser SDK for the part of tracking that can only be measured in the browser.

Render tracking metadata on resolved entries

Use SDK wrappers or helpers when available instead of copying the attribute map into application code. In Next.js App Router integrations, the preferred wrapper is the app-local bound OptimizedEntry returned by createNextjsAppRouterOptimization(). In Server Components, it resolves the baseline entry, renders the server-selected entry, and emits the Web SDK tracking attributes through server internals. For custom SSR wrappers, call getServerTrackingAttributes() from @contentful/optimization-nextjs/tracking-attributes. Non-Next runtimes can call resolveOptimizedEntryTrackingAttributes() from @contentful/optimization-web/tracking-attributes when they already have the same baseline entry and resolved data shape.

1
import { getServerTrackingAttributes } from '@contentful/optimization-nextjs/tracking-attributes'
2
3
const trackingAttributes = getServerTrackingAttributes(baselineEntry, resolvedData, {
4
  clickable: true,
5
  trackHovers: false,
6
})
7
8
return <article {...trackingAttributes}>...</article>

Those helpers stay aligned with the current Web and React Web tracking attributes, including per-element control attributes such as data-ctfl-track-views, data-ctfl-track-clicks, data-ctfl-track-hovers, data-ctfl-clickable, data-ctfl-view-duration-update-interval-ms, and data-ctfl-hover-duration-update-interval-ms.

If an application renders raw attributes manually, keep the stable browser tracking payload contract separate from SDK control metadata:

data-ctfl-baseline-id is SDK-recognized metadata for the baseline entry associated with the resolved entry. It is not used as componentId, and the browser tracker does not send it in interaction event payloads. The tracking payload uses the resolved entry ID from data-ctfl-entry-id.

Initialize the Web SDK without client-side personalization

This browser code uses the Web SDK’s default browser observation for views and clicks, opts out of hover observation, and does not fetch entries or resolve variants. It assumes the Web SDK constructor is provided by your browser bundle or approved script delivery path. Browser interaction delivery depends on consent or allowedEventTypes and a current Web SDK profile:

1
<script>
2
  const optimization = new ContentfulOptimization({
3
    clientId: window.__OPTIMIZATION_CONFIG__.clientId,
4
    environment: window.__OPTIMIZATION_CONFIG__.environment,
5
    app: { name: document.title, version: '1.0.0' },
6
    defaults: {
7
      consent: window.__OPTIMIZATION_CONSENT__,
8
      profile: window.__OPTIMIZATION_DATA__?.profile,
9
    },
10
    autoTrackEntryInteraction: { hovers: false },
11
  })
12
13
  document.querySelector('#accept-consent')?.addEventListener('click', () => {
14
    optimization.consent(true)
15
  })
16
17
  document.querySelector('#reject-consent')?.addEventListener('click', () => {
18
    optimization.consent(false)
19
  })
20
</script>

This is not client-side personalization. The browser SDK is present only to own browser state, observe DOM interactions, and deliver Analytics events for elements the server already rendered.

Choose how the browser gets a profile

Browser Insights events need a current Web SDK profile. A readable ctfl-opt-aid cookie gives the browser the anonymous ID, but the Web SDK’s Insights queue uses the current profile signal for event delivery. Choose one of these patterns before enabling interaction tracking:

• Bootstrap the server profile. For direct Web SDK initialization, serialize the profile returned by the server’s page() or identify() call and pass it as defaults.profile. For React Web and manual Next.js provider or root setup, pass the server OptimizationData through serverOptimizationState. Preferred Next.js bound roots and providers hand off server data automatically. Use this when the same server response already rendered personalized HTML from that profile.
• Re-evaluate in the browser. Persist ctfl-opt-aid on the server, initialize the Web SDK in the browser, call page() after your consent policy allows it, then enable tracking after the page response populates browser profile state.
• Use a first-party collection endpoint. If you do not want the browser to hold the full profile, custom browser code can send interaction observations to your server, and the server can call the Node SDK with the request’s profile ID. This is a manual tracking architecture, not the Web SDK auto-tracking path.

In Next.js server-rendered integrations, initialPageEvent="skip" intentionally avoids the initial browser Experience API page() request when the server already emitted that page event. If that skip leaves the browser with neither a bound server root or provider handoff nor manual serverOptimizationState, and without a prior persisted browser profile, automatic entry views, clicks, and hovers cannot deliver until a later browser Experience API call populates profile state.

If the Web SDK must read ctfl-opt-aid, do not mark that cookie as HttpOnly. Configure path, domain, and SameSite so the server route and browser code refer to the same profile.

Keep personalization server-owned

When the browser SDK is used only for tracking:

• Do not include a Contentful delivery client in the browser unless another feature needs it.
• Do not subscribe to states.selectedOptimizations for rerendering.
• Do not call resolveOptimizedEntry() in the browser.
• Do not let browser-side page() responses replace server-rendered content unless the architecture intentionally supports live client-side updates.
• Treat the server-rendered HTML as personalized output for cache purposes.

The Web SDK can still update browser profile state after page(), identify(), track(), or sticky trackView() calls. If the application ignores those state changes, the rendered content remains server-owned.

React meta-framework SSR with client tracking

The Next.js SDK App Router reference implementation is one concrete example of the same server-to-browser tracking pattern. In Next.js App Router, prefer the @contentful/optimization-nextjs/app-router factory so app code imports app-local bound OptimizationRoot, OptimizationProvider, OptimizedEntry, and route trackers from one binding module. Use /pages-router for Pages Router client components and /pages-router/server for getServerSideProps. Use adapter subpaths for manual server, tracking-attribute, request, or client control when the bound router path does not fit. The same ownership guidance applies to any React-based meta-framework that can render React code on the server and hydrate part of that tree in the browser.

Keep personalization server-owned by enforcing these boundaries:

• Next.js App Router Server Components can import the app-local bound OptimizationRoot, OptimizationProvider, OptimizedEntry, and route trackers from the binding module created by createNextjsAppRouterOptimization(). The bound server root or provider owns request data and profile handoff, and the bound server OptimizedEntry resolves and renders tracked entries.
• Lower-level Next.js server modules can still import /server helpers, call the request-bound page path, call sdk.resolveOptimizedEntry(...), and render attributes from getServerTrackingAttributes() when the app needs manual request control.
• Server-rendered entry wrappers include adapter/server-generated data-ctfl-* tracking attributes, so the browser tracking runtime can observe them after hydration.
• Client-only modules use the same app-local bound exports for the preferred Next.js path. Use /client imports when a manual browser-only setup needs direct browser entrypoints.
• Bound OptimizationRoot and route trackers stay behind the framework’s client-only boundary, so the browser runtime is not instantiated during SSR. Next.js App Router can render the adapter’s Client Component exports from a Server Component layout; other frameworks need the equivalent client-only island, lazy hydration, or browser-only wrapper.
• Client Components that only hydrate controls around server-rendered entries do not re-render those same entries through client OptimizedEntry, useOptimizedEntry, or browser-side resolveOptimizedEntry(). Use the bound client OptimizedEntry only for live or browser-owned surfaces that intentionally resolve variants after startup.
• Client rendering does not consume defaults.selectedOptimizations or states.selectedOptimizations to choose entry variants. When persistence consent is true, the Web SDK can load persisted selected optimizations for state continuity, but tracking-only client code must not use browser selected-optimization state to render already server-rendered entries.

This split avoids the common accidental-client-personalization path in React apps. In Next.js, the app-local OptimizedEntry has server behavior in Server Components and client behavior in Client Components. Use it for server-owned entries from Server Components. In hydrated Client Components, using OptimizedEntry means browser resolution from client SDK state. For server-only personalization, render the resolved entry in the server-owned render path and use the client SDK only for tracking and controls.

After hydration, client actions can still update the profile. For example, sdk.identify() can associate the visitor with a known user, and sdk.consent(true) can allow interaction tracking. Those actions do not change the already rendered HTML in the reference pattern. The user sees updated personalization on the next server request, such as a refresh or full navigation, when the server SDK evaluates the updated profile and renders a new response.

The exact framework primitive is less important than the ownership boundary. If a framework can run the same React module on both the server and the browser, do not put personalization and tracking concerns in that shared module. Keep server SDK calls in server-only code, keep browser SDK calls in client-only code, and exchange only durable handoff data such as the profile ID and rendered tracking attributes.

Server-only interaction tracking

A server-only application can still emit useful tracking, but the event names must match server facts.

Use Node-only tracking for:

• page requests
• known identity transitions
• server-side form submissions
• checkout, subscription, or account events that complete on the server
• rendered-entry events where “rendered in the response” is the intended measurement
• Custom Flag views when the flag was evaluated and rendered on the server

Do not use Node-only tracking for:

• viewport exposure
• dwell time
• hover time
• client-side route changes
• click events that do not hit the server
• unload-sensitive event flushing

If the application wants to count entry exposure as “included in SSR HTML”, make that definition explicit in dashboards and experiment analysis. It is a different metric from a browser viewport view.

Manual browser tracking without the Web SDK

A consumer can choose not to run the Web SDK in the browser, but then the application owns the browser tracking system. The server Node SDK does not fill that gap by itself.

A manual solution needs to implement at least these areas:

There are two common manual transport choices:

• Direct browser ingestion. Browser code constructs Insights API batches and sends them to the Insights API. This requires the browser to build all payloads correctly and hold the profile data needed for event association.
• First-party event endpoint. Browser code posts small interaction observations to an application endpoint. The server validates consent and identity, then calls trackView(), trackClick(), or trackHover() through the Node SDK. This keeps API details server-side but still requires custom browser observation logic.

The manual endpoint option can be appropriate for strict data-exposure policies, but it is not a small replacement for the Web SDK. It moves the transport and policy boundary to the server while leaving the hardest observation work in browser code.

Stateless runtime constraints

Serverless and stateless environments add operational constraints to tracking:

• A warm function can reuse a module-level SDK instance, but it cannot be trusted as a durable session store.
• In-memory queues can be lost when the runtime freezes or terminates.
• Background work started after the response can be cancelled by the platform.
• Parallel requests for the same visitor can arrive at different isolated workers.
• Shared HTML caches must vary on every personalization input or avoid personalized output.

For server-side events that matter, await the Node SDK call before the response completes or enqueue the event in a durable application-owned queue. For browser-observed interactions, prefer browser delivery through the Web SDK or an application endpoint that can accept events after the original HTML request has finished.

Architecture choices

The recommended hybrid for server-generated personalized HTML is Node SDK plus Web SDK tracking. That architecture keeps the rendering decision on the server and uses the browser SDK only for the runtime signals that the server cannot observe.

Implementation checklist

Use this checklist when implementing interaction tracking for Node-rendered HTML:

• Decide which events are server facts and which require browser observation.
• Gate every Node SDK event with the application consent policy before calling the SDK.
• Persist the returned profile.id when consent allows continuity.
• Pass { profile: { id } } into stateless Node calls when a profile ID exists.
• Render data-ctfl-entry-id with the resolved entry ID, not only the baseline entry ID.
• Render data-ctfl-optimization-id, data-ctfl-sticky, and data-ctfl-variant-index when an entry is an optimized variant.
• Initialize the Web SDK only once per page runtime if browser tracking is needed.
• Ensure the Web SDK has a profile before relying on Insights-backed auto tracking.
• Keep browser-side entry resolution disabled when personalization is intended to stay server-side.
• Treat personalized server HTML as personalized for cache policy, even if tracking runs in the browser.
• If avoiding the Web SDK, scope the manual solution as a browser tracking system, not as a small API-call wrapper.

Related documentation

• Node SDK integration guide
• Web SDK integration guide
• Next.js App Router integration guide
• Next.js Pages Router integration guide
• Interaction tracking in Web SDKs
• Profile synchronization between client and server
• Optimization Web SDK README
• Optimization React Web SDK README
• Optimization Next.js SDK README
• Node SSR + Web SDK reference implementation
• Next.js SDK App Router reference implementation
• Next.js SDK Pages Router reference implementation