Interaction tracking in Node and stateless environments

Overview

This page covers the case 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.

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 SDK instance per module or process, but every event call must receive request-scoped inputs from the current request. The SDK does not retain profile, consent, page, cookie, session, or browser-storage state between calls.

In practice, the application must supply:

• The current profile ID, usually from ANONYMOUS_ID_COOKIE (ctfl-opt-aid) or a session.
• The consent decision, usually from an application-owned consent cookie, session, or user setting.
• 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 payload.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.

1
const pageResponse = await optimization.page(
2
  {
3
    profile: profileId ? { id: profileId } : undefined,
4
    page: {
5
      path: req.path,
6
      query,
7
      referrer: req.get('referer') ?? '',
8
      search: url.search,
9
      url: url.toString(),
10
    },
11
    userAgent: req.get('user-agent') ?? 'node-server',
12
  },
13
  { locale: req.acceptsLanguages()[0] ?? 'en-US' },
14
)

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

1
await optimization.track(
2
  {
3
    profile: pageResponse.profile,
4
    event: 'quote_requested',
5
    properties: {
6
      plan: 'enterprise',
7
      source: 'pricing-page',
8
    },
9
  },
10
  requestOptions,
11
)

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
await optimization.trackView(
4
  {
5
    profile: pageResponse.profile,
6
    componentId: resolvedEntry.sys.id,
7
    experienceId: selectedOptimization?.experienceId,
8
    variantIndex: selectedOptimization?.variantIndex,
9
    viewDurationMs: 0,
10
    viewId: randomUUID(),
11
  },
12
  requestOptions,
13
)

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

For each rendered entry, put the resolved entry ID on the element that represents the visible Contentful entry. When the entry came from an optimization, include the selected optimization metadata.

1
<article
2
  data-ctfl-entry-id="resolved-entry-id"
3
  data-ctfl-optimization-id="experience-id"
4
  data-ctfl-sticky="true"
5
  data-ctfl-variant-index="1"
6
>
7
  ...
8
</article>

data-ctfl-entry-id is required for automatic tracking. The other attributes are optional and belong only on optimized entries:

If the server also needs a stable baseline ID for later browser rerenders, use a separate application-owned attribute such as data-ctfl-baseline-id. The tracking payload uses the resolved entry ID.

Initialize the Web SDK without client-side personalization

This browser code enables tracking but does not fetch entries or resolve variants. It assumes the Web SDK constructor is provided by your browser bundle or approved script delivery path:

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: {
11
      views: true,
12
      clicks: true,
13
      hovers: false,
14
    },
15
  })
16
17
  document.querySelector('#accept-consent')?.addEventListener('click', () => {
18
    optimization.consent(true)
19
  })
20
21
  document.querySelector('#reject-consent')?.addEventListener('click', () => {
22
    optimization.consent(false)
23
  })
24
</script>

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. Serialize the profile returned by the server’s page() or identify() call and pass it as defaults.profile. 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.

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 React Web SDK tracking

The Next.js SSR + React Web SDK reference implementation is one concrete example of the same tracking-only browser pattern. The 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:

• Server-only modules, routes, loaders, middleware, actions, or Server Components import @contentful/optimization-node, call sdk.page(), call sdk.resolveOptimizedEntry(...), and render plain React elements.
• Server-rendered entry wrappers include data-ctfl-entry-id and data-ctfl-baseline-id, so the browser tracking runtime can observe them after hydration.
• Client-only modules import @contentful/optimization-react-web for OptimizationRoot, router page tracking, consent controls, identify controls, and automatic interaction tracking.
• OptimizationRoot and router page trackers are loaded behind the framework’s client-only boundary, so the browser Web SDK is not instantiated during SSR. In Next.js, the reference implementation uses next/dynamic with ssr: false. Other frameworks need the equivalent client-only island, lazy hydration, or browser-only wrapper.
• The client tree does not use OptimizedEntry, useOptimizedEntry, or browser-side resolveOptimizedEntry().
• The client SDK is not initialized with defaults.selectedOptimizations, so browser state cannot re-resolve the already rendered entries.

This split avoids the common accidental-client-personalization path in React apps. OptimizedEntry is the React Web SDK’s browser-personalization component; using it in a hydrated client tree can cause the browser to resolve variants from client SDK state. For server-only personalization, render the resolved entry in the server-owned render path and use React Web 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 Node 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 Node SDK calls in server-only code, keep React Web 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.