Subchapter 9.26

SSR Guide

references/ssr-guide.mdMarkdown28 KBView on GitHub

SSR and Edge Rendering Guide

Server-side and edge-side rendering patterns for Contentful Personalization (Ninetailed Experience API).

SSR Guide · Contentful Personalization · contentful/skills · Skills Docs

Action	Method	Path	Preflight?	Returns experiences?
Create profile (first visit)	POST	`/profiles?type=preflight`	Yes	Yes
Update profile (returning visit)	POST	`/profiles/{profileId}?type=preflight`	Yes	Yes
Create without preflight	POST	`/profiles`	No	Yes
Update without preflight	POST	`/profiles/{profileId}`	No	Yes

{
  data: {
    profile: {
      id: string,          // canonical profile ID -- ALWAYS use this for the cookie
      stableId: string,
      traits: Record<string, unknown>,
    },
    experiences: Array<{
      experienceId: string,
      variantIndex: number,
      variants: Record<string, string>
    }>,
    changes: Array<{
      key: string,
      type: string,
      value: unknown,
      meta: { experienceId: string, variantIndex: number }
    }>,
  },
  error: null,
  message: 'ok'
}

Pattern	Server calls API?	Client SDK?	Preflight?	Best for
Hybrid SSR + Client	Yes	Yes	Yes	Most setups – no-flicker SSR with full client-side Insights and interactivity
Hybrid ESR + Client	Yes (edge)	Yes	Yes	Same as above, but personalization runs at the CDN edge
Server-Only	Yes	No	No	Static generation, email rendering, or when no client-side personalization is needed

Browser --> Server/Edge --> Experience API (?type=preflight)
                |                    |
                |<-- profile, experiences, changes (read-only)
                |
                v
         Render personalized HTML
                |
                v
Browser receives HTML (personalized, no flicker)
                |
         Client SDK hydrates
                |
                v
         Client SDK --> Experience API (non-preflight, persists state)

Browser --> Server --> Experience API (non-preflight, persists state)
                |                |
                |<-- profile, experiences, changes
                |
                v
         Render personalized HTML
                |
                v
Browser receives HTML (no client SDK, no further API calls)

Feature	Available?	Why
Personalized HTML rendering	Yes	Server gets experiences/changes from the API response
Trait-based audiences	Yes	Server can send identify events to set traits
Geo-based audiences	Yes	Include `countryCode` in the page event
Sticky variants	No	Sticky variants require component view events from the client-side viewport
Insights dashboards	No	Insights requires client-side component view/click/hover events
Real-time segment transitions	No	Session behavior during browsing is not tracked without client events
Experiment results	No	Experiments need component view events to produce usable data

Setup	Server call	Client call	Analytics events
Hybrid with preflight	`?type=preflight`	Normal	1 pageview (from client)
Hybrid without preflight	Normal	Normal	2 pageviews (doubled)
Server-only	Normal	None	1 pageview (from server)

Issue	Symptom	Why
Cookie not set at all	Client always creates new profile	Server calls API but never sets `Set-Cookie`. Client SDK finds no `ntaid`, creates fresh profile.
Cookie set from request, not response	Profile ID drift after merges	After merge, canonical ID changes. Old cookie follows a redirect chain, adding latency.
Wrong `Path` attribute	Cookie missing on some routes	Cookie with `Path=/checkout` is not sent on `/` or `/products`.
Missing `Secure` flag	Cookie dropped on HTTPS	Some browsers require `Secure` for HTTPS cookies.
`SameSite=Strict`	Cookie missing on cross-origin navigation	Links from email/social do not send `Strict` cookies on first request.
Domain mismatch	Edge and client use different profiles	Cookie on `cdn.example.com` is not visible to `app.example.com`.

{
  type: 'page' | 'track' | 'identify' | 'screen' | 'component',
  channel: 'web' | 'mobile' | 'server',  // use 'server' for SSR/ESR
  messageId: string,       // unique per event -- use crypto.randomUUID()
  timestamp: string,       // ISO 8601 -- when the event occurred
  context: {
    library: { name: string, version: string },
    location?: {
      countryCode?: string,   // ISO 3166-1 alpha-2 -- critical for geo audiences
      city?: string,
      region?: string,
    },
    page?: {
      path: string,
      query: Record<string, string | string[]>,
      referrer: string,
      search: string,
      url: string,
    },
  },
}

Field	Required?	Notes
`type`	Yes	`'page'`, `'track'`, `'identify'`
`channel`	Yes	Use `'server'` for server-side calls to distinguish from client traffic
`messageId`	Yes	Unique per event. Use `crypto.randomUUID()`
`timestamp`	Yes	ISO 8601 string
`context.library`	Yes	Identifies the calling system. Set `name` and `version`
`context.location`	No	Include `countryCode` if your edge platform provides it – without it, geo-based audiences cannot evaluate
`context.page`	Yes (page events)	Current page information

const pageEvent = {
  type: 'page' as const,
  channel: 'server' as const,
  messageId: crypto.randomUUID(),
  timestamp: new Date().toISOString(),
  sentAt: new Date().toISOString(),
  context: {
    library: { name: 'my-app-edge', version: '1.0.0' },
    page: {
      path: '/products/shoes',
      query: Object.fromEntries(searchParams),
      referrer: request.headers.get('referer') ?? '',
      search: url.search,
      url: url.toString(),
    },
    location: {
      countryCode: 'US',  // ISO 3166-1 alpha-2 -- CRITICAL for geo audiences
    },
  },
  properties: {
    path: '/products/shoes',
    query: Object.fromEntries(searchParams),
    referrer: request.headers.get('referer') ?? '',
    search: url.search,
    url: url.toString(),
    title: 'Shoes',
  },
};

const identifyEvent = {
  type: 'identify' as const,
  channel: 'server' as const,
  messageId: crypto.randomUUID(),
  timestamp: new Date().toISOString(),
  sentAt: new Date().toISOString(),
  userId: externalUserId,  // MUST be an external ID, NEVER the profile ID (ntaid)
  traits: {
    email: 'user@example.com',
    plan: 'premium',
  },
  context: {
    library: { name: 'my-app-edge', version: '1.0.0' },
  },
};

`userId` value	Behavior	Performance impact
Non-empty external ID	Merge event – resolves redirects, merges data	Significantly slower than page event
Empty string (`''`)	Trait update only – applies traits without triggering merge	Normal performance
Profile ID (ntaid)	Self-merge anti-pattern – creates redirect cycle, breaks continuity	Severe – see Anti-Pattern #2

{
  type: 'track',
  event: 'purchase_completed',
  properties: { orderId: 'order-456', total: 99.99 },
  channel: 'server',
  messageId: crypto.randomUUID(),
  timestamp: new Date().toISOString(),
  context: { library: { name: 'my-app-edge', version: '1.0.0' } },
}

Platform	Country Code Source
Vercel Edge	`request.geo.country`
Next.js Middleware	`request.geo?.country` (Vercel only – self-hosted needs IP geolocation or CDN header)

// middleware.ts
import { NextResponse } from 'next/server';

const ORG_ID = process.env.NINETAILED_ORG_ID;
const ENV_SLUG = process.env.NINETAILED_ENV_SLUG || 'main';
const API_BASE = `https://experience.ninetailed.co/v2/organizations/${ORG_ID}/environments/${ENV_SLUG}/profiles`;

export const config = {
  matcher: ['/((?!_next|api|favicon.ico|static).*)'],
};

export async function middleware(request: Request) {
  const cookies = new Map(
    request.headers
      .get('cookie')
      ?.split('; ')
      .map((c) => {
        const [k, ...v] = c.split('=');
        return [k, v.join('=')] as [string, string];
      }) ?? []
  );
  const ntaid = cookies.get('ntaid');

  const url = new URL(request.url);
  const pageEvent = {
    type: 'page' as const,
    channel: 'server' as const,
    messageId: crypto.randomUUID(),
    timestamp: new Date().toISOString(),
    sentAt: new Date().toISOString(),
    context: {
      library: { name: 'my-app-middleware', version: '1.0.0' },
      page: {
        path: url.pathname,
        query: Object.fromEntries(url.searchParams),
        referrer: request.headers.get('referer') ?? '',
        search: url.search,
        url: url.toString(),
      },
      // Geo data: request.geo?.country is only available on Vercel
    },
    properties: {
      path: url.pathname,
      query: Object.fromEntries(url.searchParams),
      referrer: request.headers.get('referer') ?? '',
      search: url.search,
      url: url.toString(),
      title: '',
    },
  };

  const apiUrl = ntaid
    ? `${API_BASE}/${ntaid}?type=preflight&locale=en`
    : `${API_BASE}?type=preflight&locale=en`;

  try {
    const apiResponse = await fetch(apiUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ events: [pageEvent] }),
      signal: AbortSignal.timeout(2000),
    });

    if (!apiResponse.ok) {
      return NextResponse.next();  // Serve baseline on API failure
    }

    const { data } = await apiResponse.json();
    const profileId = data.profile.id;
    const experiences = data.experiences ?? [];

    // Encode experience selections into query params for the page to read
    const experienceParam = experiences
      .map(
        (e: { experienceId: string; variantIndex: number }) =>
          `${e.experienceId}=${e.variantIndex}`
      )
      .sort()
      .join(',');

    const rewriteUrl = new URL(request.url);
    if (experienceParam) {
      rewriteUrl.searchParams.set('nt', experienceParam);
    }

    const response = NextResponse.rewrite(rewriteUrl);
    response.cookies.set('ntaid', profileId, {
      path: '/',
      maxAge: 31536000,
      sameSite: 'lax',
      secure: true,
    });

    return response;
  } catch {
    return NextResponse.next();  // Serve baseline on timeout or network error
  }
}

Approach	Pros	Cons
URL query params (e.g., `?nt=exp1=0,exp2=1`)	Works with CDN caching (different variant combos get different cache keys)	Pollutes the URL
Response headers (e.g., `x-ninetailed-experiences`)	Does not pollute the URL	Requires client to read headers
Inline JSON in HTML	Simplest approach	Requires HTML manipulation at the edge

// Pseudo-code for server-side identify guard
const hasIdentified = cookies.get('nt_identified') === '1';
const events = [pageEvent];

if (userId && !hasIdentified) {
  events.push(identifyEvent);
  // Set session cookie after successful API call
  response.cookies.set('nt_identified', '1', { maxAge: 0 }); // session cookie
}

// WRONG: falls back to profile ID when no customer ID
userId: customerId || ntaid || '';

// CORRECT: only use external identity, omit identify if no external ID
userId: customerId || '';

Timeout Pattern	Root Cause	Fix
Gradual increase over days/weeks	Identify on every page load (redirect chains growing)	Move identify to login/signup only. Chains self-heal over days.
Sudden spike after deploy	New code added identify to server flow, or server region changed	Check deploy dates vs error spike dates.
Consistent ~5s timeouts	Client-side AbortController timeout, not an API issue	Check client config `requestTimeout`.
Intermittent, no pattern	Network issues or WAF false positives	Check server location vs API edge.

Red Flag	What It Looks Like	Why It Breaks
Identify in per-request handler	Identify event inside middleware or `getServerSideProps`	Every page load adds a redirect hop. Merge is significantly slower than page, and each subsequent merge must traverse the growing chain.
userId fallback to profile ID	`userId: customerId \|\| ntaid \|\| ''`	System tries to merge profile with itself. User gets fresh profile on next visit.
Two sequential API calls	Separate calls for identify and page events	Two round trips. First call creates redirect, second call must traverse it.
UTM/query params as identify traits	`traits: { query_params: "?utm_source=..." }` on every page load	Same as identify-on-every-page-load. Audience should use event count rules instead.
Missing preflight in hybrid	Server call without `?type=preflight` when client SDK also runs	Both server and client persist same events. 2x everything in analytics.