contentful · David Nalchevanidze (nalchevanidze) · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
@@ -1 +1 @@
-24.13.0
+24.15.0
@@ -0,0 +1,15 @@
+DOTENV_CONFIG_QUIET=true
+
+PUBLIC_NINETAILED_CLIENT_ID="mock-client-id"
+PUBLIC_NINETAILED_ENVIRONMENT="main"
+
+PUBLIC_EXPERIENCE_API_BASE_URL="http://localhost:8000/experience/"
+PUBLIC_INSIGHTS_API_BASE_URL="http://localhost:8000/insights/"
+
+PUBLIC_CONTENTFUL_TOKEN="mock-token"
+PUBLIC_CONTENTFUL_ENVIRONMENT="master"
+PUBLIC_CONTENTFUL_SPACE_ID="mock-space-id"
+
+PUBLIC_CONTENTFUL_CDA_HOST="localhost:8000"
+PUBLIC_CONTENTFUL_BASE_PATH="contentful"
+PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL="true"
@@ -0,0 +1,23 @@
+# dependencies
+node_modules/
+
+# build output
+dist/
+
+# Angular cache
+.angular/
+
+# env files (copy from .env.example to set up locally)
+.env
+.env*.local
+
+# logs produced by launch-reference-app.sh
+logs/
+
+# debug
+*.log
+.pnpm-debug.log*
+
+# misc
+.DS_Store
+*.tsbuildinfo
@@ -0,0 +1,41 @@
+# AGENTS.md
+
+Angular SPA reference implementation of `@contentful/optimization-web`. Serves the app on
+`http://localhost:4200` via the Angular CLI dev server alongside the shared mock API server.
+
+## Rules
+
+- Do not add local adapter shims; import SDK behaviour directly from the published package surface
+  when it exists.
+- This implementation uses Angular CLI (`@angular/build`) and PM2-managed mock server processes.
+- Use standalone components (no NgModule).
+- Use modern Angular patterns: signals and `computed()` for state, `inject()` for dependency
+  injection (not constructor injection), `input()` / `output()` for component I/O, `toSignal()` to
+  bridge RxJS observables to templates, and `@if` / `@for` control flow syntax.
+- Name files and classes after the concept only — no Angular-role suffixes anywhere. File: `home.ts`
+  not `home.component.ts`. Class: `Home` not `HomeComponent`, `Optimization` not
+  `OptimizationService`, `MergeTag` not `MergeTagPipe`, etc.
+- Avoid unsafe type assertions (`as SomeType`). Use `isRecord()` and typed type-guard functions
+  instead. The `no-unsafe-type-assertion` ESLint rule is enforced and blocks commits.
+- Use explicit named types instead of `ReturnType<typeof ...>` inference. Prefer the actual type
+  (e.g. `Signal<Foo>`, `ContentfulClientApi<undefined>`) over derived magic types.
+- Follow the Angular style guide class member ordering: inputs → injected dependencies → private
+  state → constructor (effects/setup) → protected state (template-facing computed/signals) →
+  lifecycle hooks → public methods → private methods.
+
+## Commands
+
+```sh
+pnpm implementation:run -- web-sdk_angular implementation:install
+pnpm implementation:run -- web-sdk_angular serve:mocks
+pnpm implementation:run -- web-sdk_angular dev
+pnpm implementation:run -- web-sdk_angular build
+pnpm implementation:run -- web-sdk_angular typecheck
+```
+
+## Validate
+
+- Run `typecheck` for TypeScript changes.
+- Run `build` for production bundling changes.
+- Run lint via `npx eslint <file>` from the implementation directory for source file changes.
+- The pre-commit hook runs lint and Prettier automatically — fix any errors before committing.
@@ -0,0 +1,89 @@
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/personalization/">
+    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+  </a>
+</p>
+
+<h1 align="center">Contentful Personalization & Analytics</h1>
+
+<h3 align="center">Web SDK + Angular Reference Implementation</h3>
+
+<div align="center">
+
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
+
+</div>
+
+> [!WARNING]
+>
+> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.
+
+Reference implementation of `@contentful/optimization-web` for Angular applications. Demonstrates
+all SDK integration patterns — entry resolution, auto and manual tracking, consent, identify/reset,
+live updates, nested entries, rich text with merge tags, feature flags, analytics event display, and
+the preview panel.
+
+## What this demonstrates
+
+- SDK initialisation as a singleton Angular service
+- Page tracking on every route change via the Angular router
+- Entry resolution with variant/baseline display
+- Auto-tracking via `data-ctfl-*` DOM attributes
+- Manual tracking via `sdk.tracking.enableElement`
+- Click scenarios: direct, descendant, ancestor
+- Consent gating
+- Identify and reset with session persistence
+- Live updates: global toggle and per-entry override
+- Preview panel forced-live mode
+- Nested entries with recursive resolution
+- Rich text rendering with inline merge tags
+- Feature flag subscription with auto-emitted view events
+- Analytics event display with heartbeat deduplication
+- Multi-route navigation with conversion tracking
+
+## Prerequisites
+
+- Node.js ^24.15.0 (to match `.nvmrc`)
+- pnpm 10.x
+
+## Quick start
+
+From the **repository root**:
+
+```sh
+pnpm build:pkgs
+pnpm implementation:run -- web-sdk_angular implementation:install
+pnpm implementation:run -- web-sdk_angular serve:mocks
+pnpm implementation:run -- web-sdk_angular dev
+```
+
+The app is available at `http://localhost:4200`. The mock server must be running for entry data and
+variant resolution to work.
+
+Other commands from the **repository root**:
+
+```sh
+pnpm implementation:run -- web-sdk_angular build
+pnpm implementation:run -- web-sdk_angular typecheck
+```
+
+Or equivalently from the **implementation directory**:
+
+```sh
+pnpm dev
+pnpm build
+pnpm typecheck
+```
+
+## Environment variables
+
+Copy `.env.example` to `.env`:
+
+```sh
+cp .env.example .env
+```
+
+## Related
+
+- [@contentful/optimization-web](../../packages/web/web-sdk/README.md) — Web SDK
@@ -0,0 +1,62 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "web-sdk_angular": {
+      "projectType": "application",
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular/build:application",
+          "options": {
+            "outputPath": "dist/web-sdk_angular",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "tsConfig": "tsconfig.json",
+            "assets": [],
+            "styles": ["src/styles.css"]
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kB",
+                  "maximumError": "1MB"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular/build:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "web-sdk_angular:build:production"
+            },
+            "development": {
+              "buildTarget": "web-sdk_angular:build:development"
+            }
+          },
+          "defaultConfiguration": "development",
+          "options": {
+            "port": 4200
+          }
+        }
+      }
+    }
+  },
+  "cli": {
+    "analytics": false,
+    "packageManager": "pnpm"
+  }
+}
@@ -0,0 +1,38 @@
+{
+  "name": "@implementation/web-sdk_angular",
+  "private": true,
+  "version": "0.0.0",
+  "description": "Reference implementation of @contentful/optimization-web for Angular applications.",
+  "license": "MIT",
+  "scripts": {
+    "dev": "ng serve",
+    "build": "ng build",
+    "clean": "rimraf ./dist",
+    "serve:mocks": "pm2 start --name web-sdk_angular-mocks \"pnpm --dir ../../lib/mocks serve\"",
+    "serve:mocks:stop": "pm2 stop web-sdk_angular-mocks && pm2 delete web-sdk_angular-mocks",
+    "test:unit": "echo \"No unit tests necessary\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@angular/common": "^22.0.0",
+    "@angular/compiler": "^22.0.0",
+    "@angular/core": "^22.0.0",
+    "@angular/platform-browser": "^22.0.0",
+    "@angular/router": "^22.0.0",
+    "@contentful/optimization-web": "*",
+    "@contentful/optimization-web-preview-panel": "*",
+    "@contentful/rich-text-types": "^17.2.7",
+    "contentful": "^11.12.4",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@angular/build": "^22.0.0",
+    "@angular/cli": "^22.0.0",
+    "@angular/compiler-cli": "^22.0.0",
+    "@types/node": "^24.0.13",
+    "pm2": "^6.0.14",
+    "rimraf": "^6.1.3",
+    "typescript": "~6.0.3"
+  }
+}
@@ -0,0 +1,8 @@
+sharedWorkspaceLockfile: false
+
+overrides:
+  '@contentful/optimization-api-client': 'file:../../pkgs/contentful-optimization-api-client-0.0.0.tgz'
+  '@contentful/optimization-api-schemas': 'file:../../pkgs/contentful-optimization-api-schemas-0.0.0.tgz'
+  '@contentful/optimization-core': 'file:../../pkgs/contentful-optimization-core-0.0.0.tgz'
+  '@contentful/optimization-web': 'file:../../pkgs/contentful-optimization-web-0.0.0.tgz'
+  '@contentful/optimization-web-preview-panel': 'file:../../pkgs/contentful-optimization-web-preview-panel-0.0.0.tgz'
@@ -0,0 +1,38 @@
+import {
+  type ApplicationConfig,
+  provideBrowserGlobalErrorListeners,
+  provideZonelessChangeDetection,
+} from '@angular/core'
+import { provideRouter } from '@angular/router'
+import { routes } from './app.routes'
+import { provideContentfulOptimizationConfig, resolveLogLevel } from './config'
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBrowserGlobalErrorListeners(),
+    provideZonelessChangeDetection(),
+    provideRouter(routes),
+    provideContentfulOptimizationConfig({
+      clientId: import.meta.env.PUBLIC_NINETAILED_CLIENT_ID ?? 'mock-client-id',
+      environment: import.meta.env.PUBLIC_NINETAILED_ENVIRONMENT ?? 'main',
+      insightsBaseUrl:
+        import.meta.env.PUBLIC_INSIGHTS_API_BASE_URL ?? 'http://localhost:8000/insights/',
+      experienceBaseUrl:
+        import.meta.env.PUBLIC_EXPERIENCE_API_BASE_URL ?? 'http://localhost:8000/experience/',
+      logLevel: resolveLogLevel(import.meta.env.PUBLIC_OPTIMIZATION_LOG_LEVEL),
+      locale: 'en-US',
+      app: { name: 'ContentfulOptimization SDK - Angular Web Reference', version: '0.0.0' },
+      autoTrackEntryInteraction: { views: true, clicks: true, hovers: true },
+      contentful: {
+        accessToken: import.meta.env.PUBLIC_CONTENTFUL_TOKEN ?? 'mock-token',
+        environment: import.meta.env.PUBLIC_CONTENTFUL_ENVIRONMENT ?? 'master',
+        spaceId: import.meta.env.PUBLIC_CONTENTFUL_SPACE_ID ?? 'mock-space-id',
+        cdaHost: import.meta.env.PUBLIC_CONTENTFUL_CDA_HOST ?? 'localhost:8000',
+        basePath: import.meta.env.PUBLIC_CONTENTFUL_BASE_PATH ?? 'contentful',
+      },
+      ...(import.meta.env.PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL !== 'false'
+        ? { previewPanel: {} }
+        : {}),
+    }),
+  ],
+}
@@ -0,0 +1,18 @@
+<nav>
+  <a
+    data-testid="link-home"
+    routerLink="/"
+    routerLinkActive="active"
+    [routerLinkActiveOptions]="{ exact: true }"
+    >Home</a
+  >
+  <a data-testid="link-page-two" routerLink="/page-two" routerLinkActive="active">Page Two</a>
+</nav>
+<div class="app-layout">
+  <aside class="app-sidebar">
+    <app-tracking-log />
+  </aside>
+  <main>
+    <router-outlet />
+  </main>
+</div>
@@ -0,0 +1,9 @@
+import type { Routes } from '@angular/router'
+import { Home } from './pages/home'
+import { PageTwo } from './pages/page-two'
+
+export const routes: Routes = [
+  { path: '', component: Home },
+  { path: 'page-two', component: PageTwo },
+  { path: '**', redirectTo: '' },
+]
@@ -0,0 +1,16 @@
+import { Component, inject } from '@angular/core'
+import { RouterLink, RouterLinkActive, RouterOutlet } from '@angular/router'
+import { TrackingLog } from './components/tracking-log'
+import { NgContentfulOptimization } from './services/optimization'
+
+@Component({
+  selector: 'app-root',
+  imports: [RouterOutlet, RouterLink, RouterLinkActive, TrackingLog],
+  templateUrl: './app.html',
+})
+export class App {
+  constructor() {
+    // forces singleton creation on startup to wire up page tracking before first route
+    inject(NgContentfulOptimization)
+  }
+}