From 82e2efe8939f88cfaed756082be201ac0949d5b2 Mon Sep 17 00:00:00 2001 From: Charles Hudson Date: Thu, 30 Apr 2026 14:24:42 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=98=20docs(READMEs):=20Improving=20REA?= =?UTF-8?q?DME=20structure=20and=20consistency?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also improving `AGENTS.md` file structure to better optimize agent context and performance. [[NT-2776](https://contentful.atlassian.net/browse/NT-2776)] --- .husky/pre-push | 36 +- AGENTS.md | 85 +- CONTRIBUTING.md | 22 + README.md | 38 +- documentation/AGENTS.md | 79 +- documentation/README.md | 8 +- documentation/concepts/README.md | 7 +- ...tive-sdk-interaction-tracking-mechanics.md | 5 +- documentation/guides/AGENTS.md | 79 ++ documentation/guides/README.md | 12 +- ...-react-native-sdk-in-a-react-native-app.md | 2 +- .../integrating-the-web-sdk-in-a-web-app.md | 36 +- implementations/AGENTS.md | 82 ++ implementations/ios-sdk/AGENTS.md | 44 + implementations/ios-sdk/README.md | 68 +- implementations/node-sdk+web-sdk/AGENTS.md | 10 +- implementations/node-sdk+web-sdk/README.md | 55 +- implementations/node-sdk/AGENTS.md | 9 +- implementations/node-sdk/README.md | 55 +- implementations/react-native-sdk/AGENTS.md | 10 +- implementations/react-native-sdk/README.md | 80 +- implementations/react-web-sdk/AGENTS.md | 10 +- implementations/react-web-sdk/README.md | 112 ++- implementations/web-sdk/AGENTS.md | 9 +- implementations/web-sdk/README.md | 56 +- implementations/web-sdk_react/AGENTS.md | 10 +- implementations/web-sdk_react/README.md | 111 ++- lib/build-tools/README.md | 33 + lib/mocks/AGENTS.md | 5 + lib/mocks/README.md | 20 +- packages/AGENTS.md | 96 ++ packages/android/AGENTS.md | 2 +- packages/android/README.md | 5 + packages/ios/AGENTS.md | 35 +- packages/ios/CODE_MAP.md | 6 +- packages/ios/ContentfulOptimization/AGENTS.md | 43 + packages/ios/README.md | 73 +- packages/ios/ios-jsc-bridge/AGENTS.md | 40 + packages/ios/ios-jsc-bridge/README.md | 61 ++ packages/node/node-sdk/AGENTS.md | 4 +- packages/node/node-sdk/README.md | 450 +++------ packages/react-native-sdk/AGENTS.md | 4 +- packages/react-native-sdk/README.md | 834 +++------------- packages/react-native-sdk/dev/README.md | 108 ++- packages/universal/AGENTS.md | 26 + packages/universal/api-client/AGENTS.md | 13 +- packages/universal/api-client/README.md | 254 ++--- packages/universal/api-schemas/AGENTS.md | 13 +- packages/universal/api-schemas/README.md | 170 ++-- packages/universal/core-sdk/AGENTS.md | 23 +- packages/universal/core-sdk/README.md | 665 +++---------- .../core-sdk/src/preview-support/AGENTS.md | 24 + .../core-sdk/src/preview-support/README.md | 199 ++-- packages/web/AGENTS.md | 26 + .../web/frameworks/react-web-sdk/AGENTS.md | 7 +- .../web/frameworks/react-web-sdk/README.md | 578 +++-------- packages/web/preview-panel/AGENTS.md | 11 +- packages/web/preview-panel/README.md | 71 +- packages/web/web-sdk/AGENTS.md | 11 +- packages/web/web-sdk/README.md | 913 +++--------------- 60 files changed, 2236 insertions(+), 3717 deletions(-) create mode 100644 documentation/guides/AGENTS.md create mode 100644 implementations/AGENTS.md create mode 100644 implementations/ios-sdk/AGENTS.md create mode 100644 lib/build-tools/README.md create mode 100644 packages/AGENTS.md create mode 100644 packages/ios/ContentfulOptimization/AGENTS.md create mode 100644 packages/ios/ios-jsc-bridge/AGENTS.md create mode 100644 packages/ios/ios-jsc-bridge/README.md create mode 100644 packages/universal/AGENTS.md create mode 100644 packages/universal/core-sdk/src/preview-support/AGENTS.md create mode 100644 packages/web/AGENTS.md diff --git a/.husky/pre-push b/.husky/pre-push index d1e42d57..f11d4646 100644 --- a/.husky/pre-push +++ b/.husky/pre-push @@ -11,6 +11,19 @@ package_tarballs_exist() { find pkgs -maxdepth 1 -name "contentful-*.tgz" -print -quit 2>/dev/null | grep -q . } +is_documentation_file() { + local file=$1 + + case "$file" in + *.md | *.mdx | *.markdown | documentation/* | docs/* | */documentation/* | */docs/*) + return 0 + ;; + *) + return 1 + ;; + esac +} + # Collect changed files for each pushed ref from pre-push hook input # Input rows: changed_files="" @@ -46,6 +59,25 @@ done changed_files=$(printf "%s" "$changed_files" | sed '/^$/d' | sort -u) +if [ -z "$changed_files" ]; then + echo "No changed files detected for checks." + exit 0 +fi + +substantive_changed_files="" +while IFS= read -r changed_file; do + if ! is_documentation_file "$changed_file"; then + substantive_changed_files+="$changed_file"$'\n' + fi +done <<<"$changed_files" + +substantive_changed_files=$(printf "%s" "$substantive_changed_files" | sed '/^$/d' | sort -u) + +if [ -z "$substantive_changed_files" ]; then + echo "Only documentation-related changes detected; skipping build and check hook." + exit 0 +fi + # List workspaces (relative paths) workspaces=$(pnpm ls -r --depth -1 --json | jq -r ".[].path" | sed "s|^$REPO_ROOT/||") @@ -55,7 +87,7 @@ implementations=$(find implementations -mindepth 1 -maxdepth 1 -type d -exec bas # Find changed workspaces with tsconfig.json changed_workspaces=() for workspace in $workspaces; do - if echo "$changed_files" | grep -q "^$workspace/"; then + if echo "$substantive_changed_files" | grep -q "^$workspace/"; then [ -f "$workspace/tsconfig.json" ] && changed_workspaces+=("$workspace") fi done @@ -64,7 +96,7 @@ done changed_implementations=() for implementation in $implementations; do implementation_path="implementations/$implementation" - if echo "$changed_files" | grep -q "^$implementation_path/"; then + if echo "$substantive_changed_files" | grep -q "^$implementation_path/"; then [ -f "$implementation_path/tsconfig.json" ] && changed_implementations+=("$implementation") fi done diff --git a/AGENTS.md b/AGENTS.md index 4a248e8d..01f23e10 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,15 @@ # AGENTS.md -This file defines repository-wide rules only. For any change, read this file first, then read the -nearest `AGENTS.md` in the subtree you are editing. +This file defines repository-wide rules only. For any change, read this file first, then read each +applicable child `AGENTS.md` from outermost to nearest in the subtree you are editing. ## Hierarchy - The root `AGENTS.md` owns stable repo-wide policy. -- `lib/*/AGENTS.md`, `packages/**/AGENTS.md`, and `implementations/*/AGENTS.md` own local - instructions, commands, and gotchas. +- `packages/AGENTS.md` and `implementations/AGENTS.md` own shared policy for all packages and + reference implementations. +- `lib/*/AGENTS.md`, `packages/**/AGENTS.md`, and `implementations/*/AGENTS.md` own more specific + local instructions, commands, and gotchas. - If local guidance conflicts with this file, follow the more specific `AGENTS.md` for that subtree. - When adding a new workspace package or implementation, add a sibling `AGENTS.md` in the same change. @@ -106,14 +108,7 @@ Do not hand-edit generated or local-only artifacts unless the task is explicitly before finishing if the change grew. - For `implementations/` edits, prefer `pnpm implementation:lint` after the first meaningful patch and again before finishing if the change grew. -- For a single workspace package, prefer targeted `typecheck`, `test:unit`, and `build`. -- For built workspace packages, run the package `size:check` script when runtime code, published - dependencies, bundler config, exports, or bundle shape changes. - For cross-cutting changes, broaden validation to affected downstream packages or implementations. -- For package changes used by implementations, run `pnpm build:pkgs` before reinstalling or running - implementation tests. -- For implementation-only changes, use `pnpm implementation:lint`, targeted implementation - `typecheck`, and targeted E2E as needed. - If you skip a relevant check because of time or environment constraints, say exactly what was not run and why. @@ -175,25 +170,9 @@ High-signal repo-wide commands: - what you already tried - the smallest next action, user input, or approval needed -Common repo-specific failure modes: - -- An implementation does not reflect a package change: run `pnpm build:pkgs`, then rerun the - relevant `pnpm implementation:run -- implementation:install`. -- If the goal is E2E setup rather than the narrowest possible refresh step, prefer the combined root - wrapper `pnpm setup:e2e:`. For a full E2E run, prefer - `pnpm test:e2e:`. -- Implementation-specific runtime failures such as Docker availability, Playwright browser setup, - emulator requirements, `.env` drift, PM2 state, and local port conflicts belong in the relevant - implementation `AGENTS.md`, not here. - ## Docs, Specs, And CI -- When public SDK behavior changes, update the relevant TSDoc or JSDoc and the affected package - `README.md` in the same change. - Authored supporting docs live in `documentation/`; generated TypeDoc output lives in `docs/`. -- If a package includes a package-local dev harness or other meaningful local dev surface, keep that - surface relevant to the current SDK behavior and update it in the same change when the package's - developer-facing flows, configuration, or core capabilities change. - If the repository later adds any replacement design, architecture, or specification artifacts for the changed area, keep them aligned in the same change. - `docs/` is generated by TypeDoc and is gitignored. @@ -201,6 +180,56 @@ Common repo-specific failure modes: change should alter E2E coverage, update the workflow and keep it aligned with [CONTRIBUTING.md](./CONTRIBUTING.md). +## README And Markdown Standards + +- Treat README files as maintained source-of-truth orientation for humans. Keep them aligned with + package exports, implementation scripts, local `.env.example` files, and authored documentation in + the same change as behavior or workflow updates. +- Preserve the README family already used by the target directory: + - root, published package, and reference implementation READMEs use the centered Contentful logo + header, `Contentful Personalization & Analytics` title, subtype `

`, navigation links, and + pre-release warning. + - `documentation/**/README.md` files are navigation indexes with frontmatter. + - placeholder and internal-only README files may use a plain Markdown `#` title plus explicit + status or internal-use admonitions. +- Use title case for Markdown headings, preserving official product, package, API, component, hook, + and file casing. +- Lead with reader intent and scope: what to use, when to use it, and what belongs elsewhere. Prefer + concrete implementation guidance over marketing language. +- Keep terminology consistent: "Optimization SDK Suite", "Personalization", "Analytics", "Experience + API", "Insights API", "reference implementation", and exact package names such as + `@contentful/optimization-web`. +- Use fenced code blocks with language tags (`sh`, `ts`, `tsx`, `json`, `html`) and prefer `pnpm` + commands. Do not introduce npm, yarn, or undocumented global-tool instructions. +- Use GitHub admonitions intentionally: warning/caution for pre-release, internal, destructive, or + unsafe flows; important for required contracts; note for helpful context that is not required. +- Match README depth to the README category, not to the amount of available detail: + - application-facing package READMEs orient the integrator, preserve common setup options, and + link to authored guides or generated reference docs for deep workflows and exhaustive API + details + - lower-level package READMEs orient SDK maintainers and package authors, explain the layer's + role, and avoid application-integration tutorial depth + - reference implementation READMEs stay procedural and point readers to the code being + demonstrated instead of duplicating package API tutorials + - internal and placeholder READMEs stay short, explicit, and status-oriented +- Move step-by-step implementation material into `documentation/guides/` when an existing guide is + the right home; create a new guide only when no existing guide covers that reader goal. Use + generated TypeDoc reference for exhaustive signatures, method catalogs, callback payload shapes, + and exported type details. +- Before changing README navigation or cross-document links, account for every render target that + consumes that README: GitHub source browsing, TypeDoc project documents, and npmjs package README + rendering for published packages. +- Keep relative links pointed at source-of-truth files in this repository when the README is only + consumed in-repo or by TypeDoc, or when the package README publish rewrite flow is known to + rewrite that link for npm. Use stable absolute URLs for links that must work unchanged across + GitHub, TypeDoc, and npm. +- Link to generated reference docs for API reference and shared README header navigation that needs + to work in all render targets, not as a replacement for source README guidance. +- When a README has a collapsible table of contents, preserve the exact `` and + `` markers and keep entries synchronized with headings. +- For Markdown edits, run Prettier on touched files when practical and at least run + `git diff --check` before finishing. + ## Safety Rules - Never overwrite or delete ignored local files just to get a clean run. @@ -211,7 +240,7 @@ Common repo-specific failure modes: ## Preferred Workflow 1. Read the root `AGENTS.md`. -2. Read the nearest `AGENTS.md` in the subtree you will edit. +2. Read each applicable child `AGENTS.md` from outermost to nearest in the subtree you will edit. 3. Make the narrowest source-of-truth change in the correct layer. 4. Run the smallest meaningful validation set. 5. Broaden validation only when exports, build tooling, mocks, or shared behavior changed. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3699a9bd..4fc5e053 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,7 @@ gotchas. - [Validation Matrix](#validation-matrix) - [Code Style and Local Hooks](#code-style-and-local-hooks) - [Documentation](#documentation) + - [README Depth and Render Targets](#readme-depth-and-render-targets) - [Local Troubleshooting](#local-troubleshooting) - [Troubleshooting CI Issues](#troubleshooting-ci-issues) - [E2E Coverage and Environment](#e2e-coverage-and-environment) @@ -325,6 +326,27 @@ keep these artifacts aligned: `documentation/` contains source markdown that TypeDoc publishes. `docs/` is generated output. Do not hand-edit generated TypeDoc output. +### README Depth and Render Targets + +READMEs are orientation surfaces, not the only place every detail should live. Match depth to the +README category: + +- Application-facing package READMEs keep purpose, install, minimal setup, common options, critical + caveats, and links to guides, reference implementations, and generated API reference. +- Lower-level package READMEs explain the package's role in the SDK stack, who should use it + directly, common setup options where useful, and where exhaustive API details live. +- Reference implementation READMEs stay procedural: what the implementation demonstrates, + prerequisites, setup, run/test commands, environment notes, and related package links. +- Internal and placeholder READMEs stay short, explicit, and status-oriented. + +Move step-by-step implementation material into the existing guide for that runtime when one exists. +Create a new guide only when no existing guide covers the reader goal. Keep exhaustive method +catalogs, callback payload shapes, and exported type details in TypeDoc. + +Package README links must work in GitHub source browsing, generated TypeDoc project documents, and +npmjs README rendering. Use canonical generated-doc URLs for shared header navigation and verify +repo-relative links before relying on package README publish rewriting. + ## Local Troubleshooting - An implementation is not reflecting your latest package change: run `pnpm build:pkgs`, then diff --git a/README.md b/README.md index b441df37..b525f949 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ enables developers and content creators to ship their products faster. - [Choosing a Package](#choosing-a-package) - [Published Packages](#published-packages) -- [Planned SDKs](#planned-sdks) +- [Native and Planned SDKs](#native-and-planned-sdks) - [Reference Implementations](#reference-implementations) - [Repository Layout](#repository-layout) - [Get Involved](#get-involved) @@ -55,9 +55,11 @@ enables developers and content creators to ship their products faster. If you are deciding which SDK or library belongs in your application, start with [Choosing the Right SDK](./documentation/guides/choosing-the-right-sdk.md). -For additional narrative documentation, see the [Guides](./documentation/README.md) section. +For step-by-step implementation docs, start with the [Guides](./documentation/guides/README.md) +index. For behavior explanations, start with the [Concepts](./documentation/concepts/README.md) +index. -Package README files listed below are package-level overviews. Generated +Package README files listed below are package-level guides and API surface summaries. Generated [reference documentation](https://contentful.github.io/optimization) remains the source of truth for exported API signatures. @@ -84,11 +86,20 @@ General selection rules: - `@contentful/optimization-api-client` and `@contentful/optimization-api-schemas` are lower-level building blocks. -## Planned SDKs +## Native and Planned SDKs -These packages or layers are planned, but are not currently published from this repository: +React Native support is available today through +[`@contentful/optimization-react-native`](./packages/react-native-sdk/README.md). + +Native iOS work is also present in this repository as a pre-release Swift Package under +[`packages/ios`](./packages/ios/README.md), backed by the +[`@contentful/optimization-ios-bridge`](./packages/ios/ios-jsc-bridge/README.md) JavaScriptCore +adapter and the [iOS reference app](./implementations/ios-sdk/README.md). Treat this surface as +alpha implementation work rather than a stable public native SDK. + +The following native and framework SDKs are still planned and are not currently published from this +repository: -- iOS Swift SDK - Android Kotlin SDK - Android Java SDK - Nest.js SDK @@ -101,14 +112,19 @@ These packages or layers are planned, but are not currently published from this Reference implementations exist to exercise critical flows end to end and to document common usage patterns with intentionally minimal application code. -- [Web Vanilla](./implementations/web-sdk/README.md): static browser integration for the Web SDK -- [React Web](./implementations/web-sdk_react/README.md): React-based browser integration -- [Node SSR Only](./implementations/node-sdk/README.md): server-rendered integration using the Node +- [Web Vanilla](./implementations/web-sdk/README.md) - static browser integration for the Web SDK +- [React Web](./implementations/react-web-sdk/README.md) - primary React browser integration using + the official React Web SDK package +- [Web SDK React Adapter](./implementations/web-sdk_react/README.md) - adapter-based React example + built directly on top of the Web SDK +- [Node SSR Only](./implementations/node-sdk/README.md) - server-rendered integration using the Node SDK -- [Node SSR + Web Vanilla](./implementations/node-sdk+web-sdk/README.md): split server/browser flow +- [Node SSR + Web Vanilla](./implementations/node-sdk+web-sdk/README.md) - split server/browser flow using Node and Web SDKs together -- [React Native](./implementations/react-native-sdk/README.md): mobile application integration for +- [React Native](./implementations/react-native-sdk/README.md) - mobile application integration for Android and iOS targets +- [iOS Reference App](./implementations/ios-sdk/README.md) - native app and XCUITest surface for + current iOS bridge and preview-panel scenarios; this is not a published iOS SDK package ## Repository Layout diff --git a/documentation/AGENTS.md b/documentation/AGENTS.md index ea513cd7..84548fcc 100644 --- a/documentation/AGENTS.md +++ b/documentation/AGENTS.md @@ -1,5 +1,7 @@ # AGENTS.md +Read the repository root `AGENTS.md` first. + These instructions apply to authored documentation under `documentation/`. ## Documentation Categories @@ -8,75 +10,26 @@ These instructions apply to authored documentation under `documentation/`. - Put "how it works" explanations in `concepts/`. - Put nonconforming or unpublished material in `drafts/`. Drafts are not part of public navigation unless the user explicitly asks to publish or link them. -- Do not turn an implementation guide into a deep mechanics reference. Link to a concept document - when the reader needs lower-level behavior details. +- When package README content grows beyond orientation and common setup, first look for an existing + guide or concept that matches the reader goal and update that document instead of creating a new + one. Create a new guide only when the material has no existing guide home. +- Do not move exhaustive API reference material from READMEs into authored docs when generated + TypeDoc already owns the detail. Authored docs should explain integration flow, decisions, and + mechanics that generated reference docs cannot. ## Directory README Files - Keep directory `README.md` frontmatter `children` aligned with the visible list order in the same file. -- In `guides/README.md`, keep `Choosing the Right SDK` under `## Start Here`. -- In `guides/README.md`, list implementation guides under `## Integration Guides` in platform/layer - order: - 1. Node - 2. Web - 3. React Web - 4. React Native - When adding, moving, or removing a document, update the nearest directory `README.md` and any affected relative links in the same change. - -## Integration Guide Structure - -Use this structure for implementation guides: - -1. H1: `# Integrating the Optimization SDK in a App` -2. A short introduction that starts with the reader's implementation goal, usually - `Use this guide when...` -3. A collapsible table of contents immediately after the introduction and before the first `##` - section. -4. `## Scope and Capabilities` -5. `## The Integration Flow` -6. Numbered `##` sections for core implementation steps only. -7. Unnumbered `##` sections for optional or informative material. -8. `## Reference Implementations to Compare Against` - -Do not place a table of contents after a section it outlines. - -## Table of Contents - -Every guide must include this TOC wrapper: - -```md -
- Table of Contents - - -... - - -
-``` - -- The TOC block must appear before the first `##` heading. -- Keep TOC entries and anchors synchronized with the headings after any heading edit. -- Include both `##` and relevant `###` headings in the TOC. - -## Numbering Rules - -- Number only core implementation steps. -- Do not number optional or informational sections such as live updates, preview panels, caching - notes, hybrid architecture notes, or reference sections. -- If a section is optional, say so in prose near the integration flow instead of making it part of - the numbered flow. - -## Reference Implementation Policy - -- Only link to or mention reference implementations that are co-located in this monorepo. -- Do not link to or mention external demo applications. -- Mention relevant monorepo reference implementations briefly near the top of an integration guide, - usually in `The Integration Flow`. -- Expand reference links in `Reference Implementations to Compare Against`. -- Prefer links to implementation READMEs and relevant source files over vague references. +- Treat directory README files as navigation indexes, not full guides or concepts. Keep the body to + a short "start here" paragraph and grouped lists of child documents with one-sentence + descriptions. +- Use the observed index headings for consistency: `## Sections` at the documentation root, + `## Start Here` and `## Integration Guides` under `guides/`, and `## Available Concepts` under + `concepts/`. +- Preserve frontmatter `title` values that match the visible `#` heading. ## Heading and Writing Style @@ -100,7 +53,5 @@ Every guide must include this TOC wrapper: - Run Prettier on touched Markdown files. - Run `git diff --check`. -- For guide edits, verify that each TOC block appears before the first `##` and that TOC anchors - resolve to headings. - For moved or newly linked documents, verify relative Markdown links resolve to existing files when the target is inside the repository. diff --git a/documentation/README.md b/documentation/README.md index 72227401..4e5988bd 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -7,10 +7,12 @@ children: # Documentation -Start here for authored Optimization SDK documentation. +Start here for authored Optimization SDK documentation. Package README files provide package-level +orientation and API surface summaries; these documents provide cross-package selection guidance, +step-by-step implementation flows, and deeper mechanics. ## Sections -- [Guides](./guides/README.md): package selection and step-by-step SDK implementation documents -- [Concepts](./concepts/README.md): explanations of how SDK capabilities work and how runtime +- [Guides](./guides/README.md) - package selection and step-by-step SDK implementation documents +- [Concepts](./concepts/README.md) - explanations of how SDK capabilities work and how runtime behavior is determined diff --git a/documentation/concepts/README.md b/documentation/concepts/README.md index a300ad89..e1df2747 100644 --- a/documentation/concepts/README.md +++ b/documentation/concepts/README.md @@ -7,11 +7,12 @@ children: # Concepts Start here when you need to understand how SDK features work, why they behave a certain way, or how -the implementation makes runtime decisions. +the implementation makes runtime decisions. Concepts complement package README files and guides; +they are not the first stop for installation or setup commands. ## Available Concepts -- [React Native SDK Interaction Tracking Mechanics](./react-native-sdk-interaction-tracking-mechanics.md): - explains how the React Native SDK observes, gates, and emits tracking events — covering event +- [React Native SDK Interaction Tracking Mechanics](./react-native-sdk-interaction-tracking-mechanics.md) - + explains how the React Native SDK observes, gates, and emits tracking events, covering event types, the viewport state machine, default thresholds, consent gating, scroll context, screen tracking paths, and the configuration resolution order diff --git a/documentation/concepts/react-native-sdk-interaction-tracking-mechanics.md b/documentation/concepts/react-native-sdk-interaction-tracking-mechanics.md index 30f52cbf..1178d132 100644 --- a/documentation/concepts/react-native-sdk-interaction-tracking-mechanics.md +++ b/documentation/concepts/react-native-sdk-interaction-tracking-mechanics.md @@ -166,7 +166,8 @@ The React Native SDK layers RN-specific behavior on top: The offline queue has a cap (`queuePolicy.offlineMaxEvents`) and a drop callback (`queuePolicy.onOfflineDrop`). See the -[README](../../packages/react-native-sdk/README.md#queue-policy-options) for the full shape. +[README](../../packages/react-native-sdk/README.md#common-configuration) for the common queue +configuration entry point. ### Persistence Via AsyncStorage @@ -511,7 +512,7 @@ Beyond the layer above, the full `CoreStatefulConfig` is accepted as `Optimizati | `logLevel` | `'error'` | Set to `'debug'` to see every gate decision. | The full configuration reference lives in the -[React Native SDK README](../../packages/react-native-sdk/README.md#configuration). +[React Native SDK README](../../packages/react-native-sdk/README.md#common-configuration). ### Resolution Order diff --git a/documentation/guides/AGENTS.md b/documentation/guides/AGENTS.md new file mode 100644 index 00000000..41839957 --- /dev/null +++ b/documentation/guides/AGENTS.md @@ -0,0 +1,79 @@ +# AGENTS.md + +Read the repository root `AGENTS.md`, then `documentation/AGENTS.md`, before this file. + +These instructions apply to public integration guides under `documentation/guides/`. + +## Directory README + +- Keep `Choosing the Right SDK` under `## Start Here`. +- List implementation guides under `## Integration Guides` in platform/layer order: + 1. Node + 2. Web + 3. React Web + 4. React Native + +## Integration Guide Structure + +Use this structure for implementation guides: + +1. H1: `# Integrating the Optimization SDK in a App` +2. A short introduction that starts with the reader's implementation goal, usually + `Use this guide when...` +3. A collapsible table of contents immediately after the introduction and before the first `##` + section. +4. `## Scope and Capabilities` +5. `## The Integration Flow` +6. Numbered `##` sections for core implementation steps only. +7. Unnumbered `##` sections for optional or informative material. +8. `## Reference Implementations to Compare Against` + +Do not place a table of contents after a section it outlines. Do not turn an implementation guide +into a deep mechanics reference. Link to a concept document when the reader needs lower-level +behavior details. + +When extracting dense material from a package README, prefer updating the existing guide for that +runtime. Keep package setup choices, common configuration, and workflow sequencing in the guide; +keep method-by-method API details in TypeDoc. Create a new guide only when the extracted material +has a distinct implementation goal that is not covered by an existing guide. + +## Table of Contents + +Every guide must include this TOC wrapper: + +```md +
+ Table of Contents + + +... + + +
+``` + +- The TOC block must appear before the first `##` heading. +- Keep TOC entries and anchors synchronized with the headings after any heading edit. +- Include both `##` and relevant `###` headings in the TOC. + +## Numbering Rules + +- Number only core implementation steps. +- Do not number optional or informational sections such as live updates, preview panels, caching + notes, hybrid architecture notes, or reference sections. +- If a section is optional, say so in prose near the integration flow instead of making it part of + the numbered flow. + +## Reference Implementation Policy + +- Only link to or mention reference implementations that are co-located in this monorepo. +- Do not link to or mention external demo applications. +- Mention relevant monorepo reference implementations briefly near the top of an integration guide, + usually in `The Integration Flow`. +- Expand reference links in `Reference Implementations to Compare Against`. +- Prefer links to implementation READMEs and relevant source files over vague references. + +## Validation + +- For guide edits, verify that each TOC block appears before the first `##` and that TOC anchors + resolve to headings. diff --git a/documentation/guides/README.md b/documentation/guides/README.md index 4cb32ef8..4570f100 100644 --- a/documentation/guides/README.md +++ b/documentation/guides/README.md @@ -11,23 +11,25 @@ children: # Guides Start here when you need package selection guidance or step-by-step SDK implementation instructions. +If you only need package-level API summaries, use the linked package README from the root package +inventory instead. ## Start Here -- [Choosing the Right SDK](./choosing-the-right-sdk.md): pick the narrowest published package layer +- [Choosing the Right SDK](./choosing-the-right-sdk.md) - pick the narrowest published package layer for a browser, React, Node, or React Native application ## Integration Guides -- [Integrating the Optimization Node SDK in a Node App](./integrating-the-node-sdk-in-a-node-app.md): +- [Integrating the Optimization Node SDK in a Node App](./integrating-the-node-sdk-in-a-node-app.md) - step-by-step server-side integration guidance using Express-style examples and the Node reference implementations -- [Integrating the Optimization Web SDK in a Web App](./integrating-the-web-sdk-in-a-web-app.md): +- [Integrating the Optimization Web SDK in a Web App](./integrating-the-web-sdk-in-a-web-app.md) - step-by-step browser-side integration guidance covering singleton SDK setup, consent, page events, entry resolution, merge tags, flags, tracking, and hybrid SSR cookie continuity -- [Integrating the Optimization React Web SDK in a React App](./integrating-the-react-web-sdk-in-a-react-app.md): +- [Integrating the Optimization React Web SDK in a React App](./integrating-the-react-web-sdk-in-a-react-app.md) - step-by-step client-side integration guidance covering providers, consent, entry personalization, interaction tracking, live updates, router adapters, and preview panel setup -- [Integrating the Optimization React Native SDK in a React Native App](./integrating-the-react-native-sdk-in-a-react-native-app.md): +- [Integrating the Optimization React Native SDK in a React Native App](./integrating-the-react-native-sdk-in-a-react-native-app.md) - step-by-step React Native / Expo integration guidance covering setup, consent, personalization and interaction tracking, screen tracking, live updates, and the in-app preview panel diff --git a/documentation/guides/integrating-the-react-native-sdk-in-a-react-native-app.md b/documentation/guides/integrating-the-react-native-sdk-in-a-react-native-app.md index cbf039fa..1896421e 100644 --- a/documentation/guides/integrating-the-react-native-sdk-in-a-react-native-app.md +++ b/documentation/guides/integrating-the-react-native-sdk-in-a-react-native-app.md @@ -168,7 +168,7 @@ Common props on `OptimizationRoot`: The full configuration reference (API endpoints, fetch retries, queue policy, event-builder overrides) is documented in the -[React Native SDK README](../../packages/react-native-sdk/README.md#configuration). +[React Native SDK README](../../packages/react-native-sdk/README.md#common-configuration). ### Access the SDK Instance with Hooks diff --git a/documentation/guides/integrating-the-web-sdk-in-a-web-app.md b/documentation/guides/integrating-the-web-sdk-in-a-web-app.md index 5146c888..206586a3 100644 --- a/documentation/guides/integrating-the-web-sdk-in-a-web-app.md +++ b/documentation/guides/integrating-the-web-sdk-in-a-web-app.md @@ -25,6 +25,7 @@ providers, hooks, and router adapters, use the React Web guide instead. - [7. Track Entry Interactions and Follow-Up Events](#7-track-entry-interactions-and-follow-up-events) - [Automatic Entry Tracking](#automatic-entry-tracking) - [Manual Element Observation](#manual-element-observation) + - [Browser Tracking Mechanics](#browser-tracking-mechanics) - [Custom Browser Events](#custom-browser-events) - [8. Subscribe to `states` for Rerenders and UI Feedback](#8-subscribe-to-states-for-rerenders-and-ui-feedback) - [Share the Anonymous ID Cookie in Hybrid SSR + Browser Apps](#share-the-anonymous-id-cookie-in-hybrid-ssr-browser-apps) @@ -440,7 +441,40 @@ optimization.tracking.enableElement('views', element, { ``` Use `tracking.disableElement(...)` to force-disable a specific element or -`tracking.clearElement(...)` to remove a manual override and return it to automatic behavior. +`tracking.clearElement(...)` to remove a manual override and return it to automatic behavior. Manual +API overrides take precedence over data-attribute overrides. After `clearElement(...)`, the element +falls back to attribute overrides first, then normal automatic behavior. + +### Browser Tracking Mechanics + +Interaction observers are passive with respect to host event flow. They do not call +`event.preventDefault()` or `event.stopPropagation()`. + +View tracking uses `IntersectionObserver` plus dwell-time timers. Track only relevant elements, +disable tracking for elements that are no longer needed, and choose stable `minVisibleRatio` and +`dwellTimeMs` values that match your UI so visibility cycles do not reset constantly. + +Hover tracking uses pointer and mouse enter/leave events with dwell-time timers. Tune `dwellTimeMs` +and `hoverDurationUpdateIntervalMs` for pointer-heavy UIs so short pointer movement does not create +unwanted event volume. + +Click tracking uses semantic clickability checks plus tracked-entry resolution. Prefer native +clickable elements such as `