From e92398e8264e0fbedc1c1697d81fc9b2ee6c8406 Mon Sep 17 00:00:00 2001 From: Charles Hudson Date: Mon, 21 Sep 2026 12:29:12 +0200 Subject: [PATCH] docs(docs): add v1 to v2 migration guide Document the coordinated package upgrade, configuration and transport changes, direct schema migration, and runtime-specific validation paths. Add verified v1 migration knowledge, a guide blueprint, documentation navigation, and package README links so the guide ships with the v2 release. --- README.md | 4 + .../optimization-sdk-v1-to-v2.md | 63 ++++ documentation/guides/README.md | 9 + ...optimization-sdk-packages-from-v1-to-v2.md | 325 ++++++++++++++++++ .../optimization-sdk-v1.md | 96 ++++++ .../internal/sdk-knowledge/shared/concepts.md | 8 + packages/android/README.md | 6 + packages/ios/ContentfulOptimization/README.md | 6 + packages/node/node-sdk/README.md | 6 + packages/react-native-sdk/README.md | 6 + packages/universal/api-client/README.md | 6 + packages/universal/api-schemas/README.md | 4 + packages/universal/core-sdk/README.md | 6 + packages/web/frameworks/nextjs-sdk/README.md | 6 + .../web/frameworks/react-web-sdk/README.md | 6 + packages/web/preview-panel/README.md | 6 + packages/web/web-sdk/README.md | 6 + .../references/authoring-checklist.md | 7 + 18 files changed, 576 insertions(+) create mode 100644 documentation/authoring/migration-blueprints/optimization-sdk-v1-to-v2.md create mode 100644 documentation/guides/migrating-optimization-sdk-packages-from-v1-to-v2.md create mode 100644 documentation/internal/migration-knowledge/optimization-sdk-v1.md diff --git a/README.md b/README.md index 6548fafb7..f20bc0038 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,10 @@ For step-by-step implementation docs, start with the [Guides](./documentation/gu index. For behavior explanations, start with the [Concepts](./documentation/concepts/README.md) index. +If you are upgrading existing Optimization packages from v1, follow +[Migrate Optimization SDK packages from v1 to v2](./documentation/guides/migrating-optimization-sdk-packages-from-v1-to-v2.md) +before changing package versions. + Package README files listed below are package-level guides and API surface summaries. For packages included in the TypeDoc build, generated [reference documentation](https://contentful.github.io/optimization) remains the source of truth for diff --git a/documentation/authoring/migration-blueprints/optimization-sdk-v1-to-v2.md b/documentation/authoring/migration-blueprints/optimization-sdk-v1-to-v2.md new file mode 100644 index 000000000..98b4f534b --- /dev/null +++ b/documentation/authoring/migration-blueprints/optimization-sdk-v1-to-v2.md @@ -0,0 +1,63 @@ +--- +migration: optimization-sdk-v1 +archetype: migration +source: ../../internal/migration-knowledge/optimization-sdk-v1.md +guide: ../../guides/migrating-optimization-sdk-packages-from-v1-to-v2.md +--- + +# Optimization SDK v1 to v2 migration blueprint + +## Reader goal + +- **Use when:** An application or SDK layer uses one or more final-v1 Optimization packages. +- **Target result:** All directly installed Optimization packages use compatible v2 releases, retain + the intended Contentful space environment, and pass the application's existing personalization and + event checks. +- **Guide file:** `documentation/guides/migrating-optimization-sdk-packages-from-v1-to-v2.md` +- **Write after:** None. +- **First verification:** The upgraded app emits one accepted page or screen event and resolves one + authored all-visitors variant in the same Contentful space and environment used before migration. + +## Migration route + +| Legacy surface | Target route | Detail owner | +| --------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------- | +| Final-v1 package set | Compatible v2 application, framework, foundation, and tooling packages | This guide's package matrix | +| `clientId` shared configuration | Required `spaceId` configuration | Target runtime integration guide and SDK KB | +| Omitted `environment` resolving to `main` | Omitted `environment` resolving to `master` | Target runtime integration guide and SDK KB | +| Web Component `client-id` / `clientId` | `space-id` / `spaceId` | Web integration guide and Web SDK source | +| Swift and Kotlin `OptimizationConfig(clientId: ...)` | `OptimizationConfig(spaceId: ...)` | Native integration guides and native SDK source | +| Experience API v2 and Insights API v1 organization routes | Experience API v3 and Insights API v2 Contentful-space routes | Shared API transport fact | +| V1 response and event schema unions | V2 response and ExO schema unions | API Client source and API Schemas facade README | + +## Section plan + +| Section | Purpose | Must route to | Fact sources | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Choose the packages to upgrade | Prevent partial or invented upgrades by listing the last v1 and target release families, including the API Schemas exception. | Package READMEs and package-specific installation instructions. | [v1 package baselines](../../internal/migration-knowledge/optimization-sdk-v1.md#package-baselines) | +| Replace shared configuration | Apply the common `clientId` to `spaceId` change once across JavaScript environment and framework SDKs. | Node, Web, React Web, Next.js, and React Native integration guides. | [v1 shared configuration](../../internal/migration-knowledge/optimization-sdk-v1.md#shared-configuration), [Web setup](../../internal/sdk-knowledge/web/web.md#setup--initialization-and-binding), [React Web setup](../../internal/sdk-knowledge/web/react-web.md#setup--initialization-and-binding), [Node setup](../../internal/sdk-knowledge/node/node.md#setup--initialization-and-binding), [React Native setup](../../internal/sdk-knowledge/native/react-native.md#setup--initialization-and-binding) | +| Preserve the intended environment | Stop an omitted v1 `main` environment from silently becoming v2 `master`; require the reader to identify and set the intended value. | Target runtime configuration section. | [v1 shared configuration](../../internal/migration-knowledge/optimization-sdk-v1.md#shared-configuration), [Web setup](../../internal/sdk-knowledge/web/web.md#setup--initialization-and-binding), [Next.js setup](../../internal/sdk-knowledge/web/nextjs-app-router.md#setup--initialization-and-binding) | +| Update Web Component configuration | Replace the root element's attribute/property without re-teaching Web Component integration. | Web integration guide. | [v1 Web Component](../../internal/migration-knowledge/optimization-sdk-v1.md#web-component-configuration), [v2 Web Component](../../internal/sdk-knowledge/web/web.md#components--hooks) | +| Update native initialization | Apply the corresponding Swift and Kotlin initializer rename and preserve the environment. | SwiftUI, UIKit, Compose, and Views integration guides. | [v1 native initialization](../../internal/migration-knowledge/optimization-sdk-v1.md#native-initialization), [v2 iOS setup](../../internal/sdk-knowledge/native/ios.md#setup--initialization-and-binding), [v2 Android setup](../../internal/sdk-knowledge/native/android.md#setup--initialization-and-binding) | +| Update direct API Client integrations | Limit route work to direct transport consumers, proxies, allow-lists, and mocks; environment/framework SDK users do not construct routes. | API Client README. | [v1 API routes](../../internal/migration-knowledge/optimization-sdk-v1.md#api-routes), [v2 API transport](../../internal/sdk-knowledge/shared/concepts.md#api-transport-scope) | +| Update direct schema consumers | Identify response-envelope, change-union, event-union, and deprecated facade work without asking ordinary runtime users to edit schemas. | API Client and API Schemas READMEs. | [v1 schemas](../../internal/migration-knowledge/optimization-sdk-v1.md#response-and-event-schemas), [v1 integration boundaries](../../internal/migration-knowledge/optimization-sdk-v1.md#v1-integration-boundaries) | + +## Handoffs + +None. + +## Link roles + +- [Guides index](../../guides/README.md). +- [Node integration guide](../../guides/integrating-the-node-sdk-in-a-node-app.md). +- [Web integration guide](../../guides/integrating-the-web-sdk-in-a-web-app.md). +- [React Web integration guide](../../guides/integrating-the-react-web-sdk-in-a-react-app.md). +- [Next.js App Router integration guide](../../guides/integrating-the-optimization-sdk-in-a-nextjs-app-router-app.md). +- [Next.js Pages Router integration guide](../../guides/integrating-the-optimization-sdk-in-a-nextjs-pages-router-app.md). +- [React Native integration guide](../../guides/integrating-the-react-native-sdk-in-a-react-native-app.md). +- [iOS SwiftUI integration guide](../../guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md). +- [iOS UIKit integration guide](../../guides/integrating-the-optimization-ios-sdk-in-a-uikit-app.md). +- [Android Compose integration guide](../../guides/integrating-the-optimization-android-sdk-in-a-compose-app.md). +- [Android Views integration guide](../../guides/integrating-the-optimization-android-sdk-in-a-views-app.md). +- [`@contentful/optimization-api-client` README](../../../packages/universal/api-client/README.md). +- [`@contentful/optimization-api-schemas` README](../../../packages/universal/api-schemas/README.md). diff --git a/documentation/guides/README.md b/documentation/guides/README.md index 1ee5c5752..8defb6c76 100644 --- a/documentation/guides/README.md +++ b/documentation/guides/README.md @@ -2,6 +2,7 @@ title: Guides children: - ./choosing-the-right-sdk.md + - ./migrating-optimization-sdk-packages-from-v1-to-v2.md - ./integrating-the-node-sdk-in-a-node-app.md - ./integrating-the-web-sdk-in-a-web-app.md - ./integrating-the-react-web-sdk-in-a-react-app.md @@ -36,6 +37,14 @@ you are unsure which SDK layer belongs in your app. - [Choose the right SDK](./choosing-the-right-sdk.md) - Choose the SDK package and runtime layer for your app. +## Version migration guides + +Use this guide when an existing Optimization SDK integration is moving between major versions. + +| Guide | Runtime or app type | Package | +| ----------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------- | +| [Optimization SDK v1 to v2](./migrating-optimization-sdk-packages-from-v1-to-v2.md) | Existing Optimization SDK Suite integration | Installed Optimization packages | + ## Integration guides Server and web SDK guides are listed before native and mobile SDK guides. diff --git a/documentation/guides/migrating-optimization-sdk-packages-from-v1-to-v2.md b/documentation/guides/migrating-optimization-sdk-packages-from-v1-to-v2.md new file mode 100644 index 000000000..d7c562829 --- /dev/null +++ b/documentation/guides/migrating-optimization-sdk-packages-from-v1-to-v2.md @@ -0,0 +1,325 @@ +--- +fern: + slug: migrate-optimization-sdk-v1-to-v2 + section: Migration guides + description: >- + Upgrade Optimization SDK packages from their final v1 releases to v2 while preserving the + intended Contentful space environment and updating direct API and schema integrations. +--- + +# Migrate Optimization SDK packages from v1 to v2 + +Use this guide when an application or SDK layer uses one or more v1 Optimization packages and you +want to upgrade those packages to v2 without changing the application's personalization design. + +## What changes + +Version 2 renames the shared `clientId` configuration key to `spaceId`; both keys contain the same +Contentful Space ID. The default Contentful environment also changes from `main` to `master`. For +most applications, the migration is limited to upgrading directly installed packages, renaming that +configuration key, and preserving the intended environment. + +Additional changes apply only when your code directly uses the low-level API Client, inspects its +URLs, or imports its schemas. The Experience API, which returns the visitor profile and selected +optimizations, moves from v2 organization routes to v3 space routes. The Insights API, which receives +interaction events, moves from v1 organization routes to v2 space routes. Direct schema consumers +must also handle updated response and event unions, including Experience Optimization (ExO) node +events. + +This upgrade does not require a Contentful content-model migration or a profile-cookie reset. After +updating the version-specific surfaces below, continue to use the integration guide for your +runtime's consent, entry resolution, event, tracking, preview, and cache behavior. + +## Before you migrate + +Gather these inputs: + +- Every directly installed Optimization package and its current version. Include packages used only + by build tools, tests, or internal SDK layers. +- The lockfile entries for Optimization packages so you can check for mixed v1 and v2 dependency + trees after installation. +- The Contentful Space ID used by the integration. In v1 this value may be stored under a variable + named `clientId`; the name changes, but the value is the Contentful Space ID. +- The Contentful environment the application currently uses. If v1 omits `environment`, record + `main` as the effective value before upgrading. +- Every `clientId`, `client-id`, `OptimizationConfig(clientId: ...)`, and + `OptimizationConfig(clientId = ...)` initialization site. +- Any direct API Client calls, network allow-lists, reverse proxies, request mocks, response-envelope + parsing, exhaustive `Change` handling, or event-schema validation. +- One entry with a replacement **variant** attached to an **experience** in Contentful. An experience + is the authored rule that selects among the original entry—the **baseline**—and its variants. For + this test, target all visitors so the request matches automatically, and give the variant visibly + different content. The integration guide for your runtime shows where the fetched entry is passed + to the SDK. + +## Migration path + +1. Inventory the directly installed packages using the matrix below. Do not add transitive + Optimization packages as direct dependencies solely for this migration. +2. While still on v1, set `environment` explicitly to the environment the application already uses. + This preserves behavior across the default change. +3. Upgrade all directly installed packages in the same change. Use v2 for packages in the + coordinated release and `1.2.1` for the deprecated API Schemas compatibility facade if the app + still installs it. +4. Replace shared `clientId` configuration with `spaceId`, then update any Web Component and native + initialization surfaces. +5. If the app directly consumes the API Client or its schemas, update the route-dependent + infrastructure and exhaustive schema handling described below. +6. Reinstall dependencies and inspect the lockfile for unintended mixed v1/v2 copies. +7. Run the runtime-specific checks in [Validate the migration](#validate-the-migration). + +## Replace legacy surfaces + +### Choose the packages to upgrade + +Upgrade only the packages the application installs directly. Framework and environment packages +bring their required shared packages through their declared dependencies. + +| Package | Final v1 | Migration target | +| -------------------------------------------- | -------- | ---------------- | +| `com.contentful.java:optimization-android` | `1.1.0` | `2.0.0` | +| `ContentfulOptimization` | `1.1.0` | `2.0.0` | +| `@contentful/optimization-api-client` | `1.1.1` | `2.0.0` | +| `@contentful/optimization-core` | `1.3.0` | `2.0.0` | +| `@contentful/optimization-nextjs` | `1.3.0` | `2.0.0` | +| `@contentful/optimization-node` | `1.2.1` | `2.0.0` | +| `@contentful/optimization-react-native` | `1.1.0` | `2.0.0` | +| `@contentful/optimization-react-web` | `1.3.0` | `2.0.0` | +| `@contentful/optimization-web` | `1.3.0` | `2.0.0` | +| `@contentful/optimization-web-preview-panel` | `1.2.0` | `2.0.0` | +| `@contentful/optimization-api-schemas` | `1.2.0` | `1.2.1` | + +The API Schemas package remains on its own v1 version line. It is a deprecated compatibility package +that re-exports schemas now owned by API Client and Core. If your code imports +`@contentful/optimization-api-schemas`, migrate those imports to the owning package entry points when +practical; do not wait for a v2 release of this package. See the +[`@contentful/optimization-api-schemas` migration table](../../packages/universal/api-schemas/README.md#migrate-imports). + +The Preview Panel's `attachOptimizationPreviewPanel(...)` call does not take `clientId` directly. +Upgrade its package with the Web SDK packages it consumes, then confirm that the panel still connects +to the upgraded Web SDK. + +### Replace shared configuration + +In JavaScript and TypeScript SDK configuration, rename `clientId` to `spaceId`. This includes direct +construction, React and React Native root/provider props, Next.js binders, and configuration objects +passed through application helpers. + +The value does not change: both names refer to the Contentful Space ID. Environment-variable names +are app-owned, so you may retain an existing variable name temporarily, but renaming it to describe +a Space ID makes the new contract clearer. + +**Adapt this to your use case:** + +```diff + const optimization = new ContentfulOptimization({ +- clientId: process.env.CONTENTFUL_CLIENT_ID, ++ spaceId: process.env.CONTENTFUL_SPACE_ID, + environment: process.env.CONTENTFUL_ENVIRONMENT, + }) +``` + +Follow the current integration guide for the exact construction surface in +[Node](./integrating-the-node-sdk-in-a-node-app.md), +[Web](./integrating-the-web-sdk-in-a-web-app.md), +[React Web](./integrating-the-react-web-sdk-in-a-react-app.md), +[Next.js App Router](./integrating-the-optimization-sdk-in-a-nextjs-app-router-app.md), +[Next.js Pages Router](./integrating-the-optimization-sdk-in-a-nextjs-pages-router-app.md), or +[React Native](./integrating-the-react-native-sdk-in-a-react-native-app.md). + +### Preserve the intended environment + +The v1 default is `main`; the v2 default is `master`. An application that omitted `environment` in +v1 would silently address a different Contentful environment after upgrading if you continue to +omit it. + +While the application still uses v1, make the existing effective environment explicit. Keep the v1 +`clientId` key in this preparatory edit: + +**Adapt this to your use case:** + +```ts +const optimization = new ContentfulOptimization({ + clientId: process.env.CONTENTFUL_CLIENT_ID, + environment: 'main', +}) +``` + +After upgrading the packages and renaming the key for v2, preserve that same environment value: + +**Adapt this to your use case:** + +```ts +const optimization = new ContentfulOptimization({ + spaceId: process.env.CONTENTFUL_SPACE_ID, + // Keep "main" when that is the environment the v1 integration used. + environment: 'main', +}) +``` + +The literal environment value is owned by your Contentful space. Use `master` only when that is the +environment the application should address. After migration, you may omit the field when the v2 +`master` default matches your intended environment. + +### Update Web Component configuration + +For an SDK-owned ``, rename the HTML attribute and the corresponding DOM +property. The element requires a Space ID unless you assign an existing SDK instance through its +`sdk` property. + +**Adapt this to your use case:** + +```diff +- ++ + + +``` + +For imperative DOM code, replace `root.clientId` with `root.spaceId`. See the +[Web SDK integration guide](./integrating-the-web-sdk-in-a-web-app.md) for the current Web Component +surface. + +### Update native initialization + +Swift and Kotlin use the same Contentful Space ID and environment as the JavaScript SDKs. Rename the +initializer argument and keep the existing environment explicit. + +For Swift: + +**Adapt this to your use case:** + +```diff + let config = OptimizationConfig( +- clientId: contentfulSpaceId, ++ spaceId: contentfulSpaceId, + environment: "main" + ) +``` + +For Kotlin: + +**Adapt this to your use case:** + +```diff + val config = OptimizationConfig( +- clientId = contentfulSpaceId, ++ spaceId = contentfulSpaceId, + environment = "main", + ) +``` + +Continue with the current [SwiftUI](./integrating-the-optimization-ios-sdk-in-a-swiftui-app.md), +[UIKit](./integrating-the-optimization-ios-sdk-in-a-uikit-app.md), +[Android Compose](./integrating-the-optimization-android-sdk-in-a-compose-app.md), or +[Android Views](./integrating-the-optimization-android-sdk-in-a-views-app.md) integration guide. + +### Update direct API Client integrations + +Skip this section if the application uses an environment or framework SDK and does not inspect API +URLs. Those SDKs construct the API paths internally. + +Direct API Client consumers still replace `clientId` with `spaceId`. Update any proxy rules, +network allow-lists, request mocks, or diagnostics that match the old paths: + +| Transport | V1 path prefix | V2 path prefix | +| -------------- | --------------------------------------------------------------- | ------------------------------------------------------- | +| Experience API | `v2/organizations/{clientId}/environments/{environment}` | `v3/spaces/{spaceId}/environments/{environment}` | +| Insights API | `v1/organizations/{clientId}/environments/{environment}/events` | `v2/spaces/{spaceId}/environments/{environment}/events` | + +Do not construct these paths in ordinary SDK integrations. Configure `spaceId` and `environment` +and let the API Client own the route. See the +[`@contentful/optimization-api-client` README](../../packages/universal/api-client/README.md) for +the current direct-client configuration. + +### Update direct schema consumers + +Skip this section unless application, adapter, test, or tooling code imports API schemas or performs +exhaustive checks on response and event unions. A **response envelope** is the outer +`{ data, message, error }` object returned by the Experience API. `Change` and the event types are +**discriminated unions**: TypeScript and the runtime schemas choose a member from its `type` field. +Search imports from `@contentful/optimization-api-client/api-schemas` or the deprecated +`@contentful/optimization-api-schemas`, plus `switch` statements that branch on `.type`. + +| V1 assumption | V2 contract | +| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| Response-envelope `error` is `boolean \| null` | `error` is `{ code: string } \| null` | +| Every `Change` has type `Variable` | `Change` is discriminated across `Variable`, `Experience`, and `Fragment` | +| Experience events include `alias` and `group` | The Experience union includes `exo_node_view`; `alias` and `group` are not members | +| Insights events are `component`, `component_click`, `component_hover` | The union also includes `exo_node_view`, `exo_node_click`, and `exo_node_hover` | + +`Variable` changes carry Custom Flag values; `Experience` and `Fragment` changes carry selected +Contentful entity variants. The `exo_node_*` event names describe Experience Optimization node +views, clicks, and hovers. Update exhaustive `switch` statements and schema fixtures rather than +coercing v2 payloads into the old union. Import Experience and Insights schemas from +`@contentful/optimization-api-client/api-schemas`; import Contentful CDA schemas and helpers from +`@contentful/optimization-core/api-schemas`. The deprecated +`@contentful/optimization-api-schemas` facade remains available for compatibility, but new imports +should use the owning packages. + +## Validate the migration + +Run the checks that match the application's installed packages: + +1. Inspect resolved versions with the package manager the app already uses: + + | Runtime | Inspection mechanism | + | --------------------- | --------------------------------------------------------------------------------------- | + | pnpm | `pnpm why @contentful/optimization-web` with each directly installed JavaScript package | + | npm | `npm ls @contentful/optimization-web` with each directly installed JavaScript package | + | Yarn | `yarn why @contentful/optimization-web` with each directly installed JavaScript package | + | Swift Package Manager | Xcode's **Package Dependencies** view or the app's `Package.resolved` | + | Gradle | The app module's `dependencies` task for its runtime classpath configuration | + + Every directly installed package in the matrix should resolve to its migration target. Transitive + packages may follow their own version lines; `@contentful/optimization-api-schemas@1.2.1` is the + expected exception in this release. + +2. Start the application with the intended `spaceId` and an explicit `environment`. If the app + already logs or proxies Optimization requests, confirm their space and environment path segments. + If no request diagnostic already exists, continue with the smoke checks below rather than adding + network instrumentation solely for migration. Event acceptance and variant rendering show that + the upgraded flow works, but they do not by themselves prove the exact transport path because an + SDK can use queued, handed-off, or cached state. +3. Trigger and observe the runtime's normal first event. An **accepted** event is one the local SDK + consent policy allows it to send: + + | Runtime | Action and observable proof | + | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | Node | Exercise the existing request that calls `page()` or `identify()` and confirm its returned result has `accepted: true`; see the [Node quick start](./integrating-the-node-sdk-in-a-node-app.md#quick-start). | + | Web and React Web | Load a tracked route and inspect the app's existing event diagnostics; the [Web page-event section](./integrating-the-web-sdk-in-a-web-app.md#page-and-route-events) and [React Web page-event section](./integrating-the-react-web-sdk-in-a-react-app.md#page-events-and-route-tracking) show the runtime-owned signals. | + | Next.js | Load a route once and confirm the bound root or tracker owns one page event; use the [App Router](./integrating-the-optimization-sdk-in-a-nextjs-app-router-app.md#the-bound-root-and-page-events) or [Pages Router](./integrating-the-optimization-sdk-in-a-nextjs-pages-router-app.md#the-bound-root-and-page-events) check. | + | React Native | Open a tracked screen and observe the accepted `screen` event through `states.eventStream`; see [Screen and navigation tracking](./integrating-the-react-native-sdk-in-a-react-native-app.md#screen-and-navigation-tracking). | + | iOS | Subscribe to `client.eventStream`, open a tracked screen, and confirm it emits the accepted `screen` event; see [SwiftUI analytics diagnostics](./integrating-the-optimization-ios-sdk-in-a-swiftui-app.md#custom-events-and-analytics-diagnostics) or [UIKit analytics diagnostics](./integrating-the-optimization-ios-sdk-in-a-uikit-app.md#custom-events-and-analytics-diagnostics). | + | Android | Collect `client.eventStream`, open a tracked screen, and confirm it emits the accepted `screen` event; see [Compose analytics diagnostics](./integrating-the-optimization-android-sdk-in-a-compose-app.md#custom-events-and-analytics-diagnostics) or [Views analytics diagnostics](./integrating-the-optimization-android-sdk-in-a-views-app.md#custom-events-and-analytics-diagnostics). | + +4. Load the authored all-visitors experience gathered before migration. Confirm its visibly different + variant, not only the baseline, resolves. +5. If the existing integration emits interaction or custom events, trigger one and confirm its + existing diagnostic or analytics-forwarding path still observes it. Do not add a new event solely + for this migration. +6. If the existing integration supports denied consent, exercise that path and use the runtime + integration guide's consent section to confirm the event appears in `onEventBlocked`, + `blockedEventStream`, or the native equivalent instead of being sent. Blocked-event diagnostics + are evidence; the SDK does not replay the blocked call after consent changes. +7. If the app uses direct schemas, run its response and event fixture tests with v2 payload shapes. +8. If the app uses the Preview Panel, open it and confirm it can select a variant through the + upgraded Web SDK instance. + +## Troubleshooting + +| Symptom | Likely cause | Action | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| Type error says `clientId` is unknown or `spaceId` is required | A v1 configuration key remains | Replace the key at that initialization boundary and pass the Contentful Space ID | +| Personalization works against unexpected content | The omitted environment changed from `main` to `master` | Set `environment` explicitly to the Contentful environment the v1 integration used | +| `` reports that `space-id` is required | The element still uses `client-id` or no SDK instance is assigned | Rename the attribute/property or assign the existing SDK through `sdk` | +| Requests receive route-not-found or proxy errors | A proxy, allow-list, or mock still expects organization-based v1/v2 API paths | Update route-dependent infrastructure to the space-based path prefixes in this guide | +| Type narrowing misses response changes or ExO events | An exhaustive v1 schema check is still in place | Handle the v2 discriminated unions and update fixtures instead of casting the payload | +| Preview fails after otherwise successful migration | Preview Panel and Web/Core packages are on incompatible major versions | Align the directly installed Preview Panel and Web packages, reinstall, and inspect the resolved lockfile | + +## Related guides + +- [Choose the right SDK](./choosing-the-right-sdk.md) +- [Guides index](./README.md) +- [`@contentful/optimization-api-client` README](../../packages/universal/api-client/README.md) +- [`@contentful/optimization-api-schemas` migration table](../../packages/universal/api-schemas/README.md#migrate-imports) diff --git a/documentation/internal/migration-knowledge/optimization-sdk-v1.md b/documentation/internal/migration-knowledge/optimization-sdk-v1.md new file mode 100644 index 000000000..26b9b294a --- /dev/null +++ b/documentation/internal/migration-knowledge/optimization-sdk-v1.md @@ -0,0 +1,96 @@ +# Optimization SDK v1 migration knowledge + +Source revisions: the final v1 tags for each package listed in [Package baselines](#package-baselines). + +Internal migration reference. Facts only; not guide prose. Source pointers use +`:#`. + +## Package baselines + +| Package | Final v1 release | Source tag | +| -------------------------------------------- | ---------------- | --------------------------------------- | +| `com.contentful.java:optimization-android` | `1.1.0` | `optimization-android-v1.1.0` | +| `ContentfulOptimization` | `1.1.0` | `optimization-swift-v1.1.0` | +| `@contentful/optimization-api-client` | `1.1.1` | `optimization-api-client-v1.1.1` | +| `@contentful/optimization-core` | `1.3.0` | `optimization-core-v1.3.0` | +| `@contentful/optimization-nextjs` | `1.3.0` | `optimization-nextjs-v1.3.0` | +| `@contentful/optimization-node` | `1.2.1` | `optimization-node-v1.2.1` | +| `@contentful/optimization-react-native` | `1.1.0` | `optimization-react-native-v1.1.0` | +| `@contentful/optimization-react-web` | `1.3.0` | `optimization-react-web-v1.3.0` | +| `@contentful/optimization-web` | `1.3.0` | `optimization-web-v1.3.0` | +| `@contentful/optimization-web-preview-panel` | `1.2.0` | `optimization-web-preview-panel-v1.2.0` | +| `@contentful/optimization-api-schemas` | `1.2.0` | `optimization-api-schemas-v1.2.0` | + +The v1 API Schemas library has its own version line and exposes Contentful CDA, Experience API, and +Insights API schemas from its package root. source: +optimization-api-schemas-v1.2.0:packages/universal/api-schemas/package.json#name; +optimization-api-schemas-v1.2.0:packages/universal/api-schemas/README.md#Package-surface. + +## Shared configuration + +- JavaScript SDK configuration requires `clientId`; an omitted `environment` resolves to `main`. + The same values configure Experience and Insights API clients. source: + optimization-api-client-v1.1.1:packages/universal/api-client/src/ApiClientBase.ts#ApiConfig; + optimization-api-client-v1.1.1:packages/universal/api-client/src/ApiClientBase.ts#DEFAULT_ENVIRONMENT; + optimization-core-v1.3.0:packages/universal/core-sdk/src/CoreBase.ts#CoreConfig. +- The Web, React Web, Next.js, Node, and React Native SDKs expose the shared Core configuration, so + their v1 initialization paths inherit `clientId` and the `main` environment default. source: + optimization-web-v1.3.0:packages/web/web-sdk/src/ContentfulOptimization.ts#ContentfulOptimization; + optimization-react-web-v1.3.0:packages/web/frameworks/react-web-sdk/src/root/OptimizationRoot.tsx#OptimizationRootProps; + optimization-nextjs-v1.3.0:packages/web/frameworks/nextjs-sdk/src/bound-component-types.ts#NextjsBoundRootConfig; + optimization-node-v1.2.1:packages/node/node-sdk/src/ContentfulOptimization.ts#ContentfulOptimization; + optimization-react-native-v1.1.0:packages/react-native-sdk/src/ContentfulOptimization.ts#ContentfulOptimization. + +## API routes + +- The Experience API client sends profile and event requests beneath + `v2/organizations/{clientId}/environments/{environment}`. source: + optimization-api-client-v1.1.1:packages/universal/api-client/src/experience/ExperienceApiClient.ts#ExperienceApiClient. +- The Insights API client sends event batches to + `v1/organizations/{clientId}/environments/{environment}/events`. source: + optimization-api-client-v1.1.1:packages/universal/api-client/src/insights/InsightsApiClient.ts#InsightsApiClient. + +Applications using an environment or framework SDK do not construct these paths. Direct API Client +consumers, network allow-lists, proxies, and request mocks may depend on them. source: +optimization-api-client-v1.1.1:packages/universal/api-client/src/ApiClient.ts#ApiClient; +optimization-core-v1.3.0:packages/universal/core-sdk/src/CoreBase.ts#CoreBase. + +## Web Component configuration + +The v1 `` element observes `client-id`, reads it through the `clientId` +property, and refuses to create its owned SDK when the attribute or an assigned `sdk` is absent. +source: +optimization-web-v1.3.0:packages/web/web-sdk/src/web-components/ContentfulOptimizationRootElement.ts#ContentfulOptimizationRootElement. + +## Native initialization + +- Swift `OptimizationConfig` requires `clientId` and defaults `environment` to `main`; bridge + serialization forwards those keys to the shared runtime. source: + optimization-swift-v1.1.0:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationConfig.swift#OptimizationConfig. +- Kotlin `OptimizationConfig` requires `clientId` and defaults `environment` to `main`; JSON + serialization forwards those keys to the shared runtime. source: + optimization-android-v1.1.0:packages/android/ContentfulOptimization/src/main/kotlin/com/contentful/optimization/core/OptimizationConfig.kt#OptimizationConfig. + +## Response and event schemas + +- The v1 Experience response envelope represents `error` as a nullable boolean. source: + optimization-api-schemas-v1.2.0:packages/universal/api-schemas/src/experience/ResponseEnvelope.ts#ResponseEnvelope. +- The v1 `Change` union accepts only `Variable` changes. source: + optimization-api-schemas-v1.2.0:packages/universal/api-schemas/src/experience/change/Change.ts#Change. +- The v1 Experience event union includes `alias` and `group`; the Insights event union includes + `component`, `component_click`, and `component_hover`. source: + optimization-api-schemas-v1.2.0:packages/universal/api-schemas/src/experience/event/ExperienceEvent.ts#ExperienceEvent; + optimization-api-schemas-v1.2.0:packages/universal/api-schemas/src/insights/event/InsightsEvent.ts#InsightsEvent. + +## V1 integration boundaries + +- The v1 runtime uses SDK-owned Contentful entry fields, the `ctfl-opt-aid` visitor profile cookie, + an app-owned consent decision, and Core entry resolution. source: + optimization-api-schemas-v1.2.0:packages/universal/api-schemas/src/contentful/OptimizedEntry.ts#OptimizedEntryFields; + optimization-core-v1.3.0:packages/universal/core-sdk/src/constants.ts#ANONYMOUS_ID_COOKIE; + optimization-core-v1.3.0:packages/universal/core-sdk/src/consent/ConsentPolicy.ts#hasEventConsent; + optimization-core-v1.3.0:packages/universal/core-sdk/src/resolvers/OptimizedEntryResolver.ts#OptimizedEntryResolver. +- The Preview Panel consumes the Web and Core SDKs but does not expose the shared `clientId` + configuration as its own initialization input. source: + optimization-web-preview-panel-v1.2.0:packages/web/preview-panel/src/attachOptimizationPreviewPanel.ts#attachOptimizationPreviewPanel; + optimization-web-preview-panel-v1.2.0:packages/web/preview-panel/package.json#dependencies. diff --git a/documentation/internal/sdk-knowledge/shared/concepts.md b/documentation/internal/sdk-knowledge/shared/concepts.md index 6aaf7d025..771cfeea0 100644 --- a/documentation/internal/sdk-knowledge/shared/concepts.md +++ b/documentation/internal/sdk-knowledge/shared/concepts.md @@ -266,6 +266,14 @@ event can therefore have no `data` yet; only a returned `data` value contains th selections, and changes described above. source: core-sdk#events/EventEmissionResult.ts#EventEmissionResult; core-sdk#CoreStatefulEventEmitter.ts#sendExperienceEventWithResult +## API transport scope + +The API Client scopes Experience API requests under +`v3/spaces/{spaceId}/environments/{environment}` and Insights API event requests under +`v2/spaces/{spaceId}/environments/{environment}`. Both clients use the shared configured Contentful +space and environment; an omitted environment resolves to `master`. +source: api-client#ApiClientBase.ts#DEFAULT_ENVIRONMENT; api-client#experience/ExperienceApiClient.ts#ExperienceApiClient; api-client#insights/InsightsApiClient.ts#InsightsApiClient + ## Optimization handoff `OptimizationHandoff` is the framework-neutral handoff shape for server, static, and edge rendered diff --git a/packages/android/README.md b/packages/android/README.md index 3f8631520..49ddd2877 100644 --- a/packages/android/README.md +++ b/packages/android/README.md @@ -21,6 +21,12 @@ optimization behavior through a local QuickJS bridge while Kotlin code owns nati as persistence, networking, lifecycle handling, Jetpack Compose UI, XML Views UI, and preview-panel UI. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing the Maven dependency version. +
Table of Contents diff --git a/packages/ios/ContentfulOptimization/README.md b/packages/ios/ContentfulOptimization/README.md index 71422b8be..f5378bb5a 100644 --- a/packages/ios/ContentfulOptimization/README.md +++ b/packages/ios/ContentfulOptimization/README.md @@ -27,6 +27,12 @@ optimization behavior through a local JavaScriptCore bridge while Swift code owns native app concerns such as persistence, networking, lifecycle handling, SwiftUI views, and preview-panel UI. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing the Swift Package version. + Requires iOS 15 or later. ## Installation diff --git a/packages/node/node-sdk/README.md b/packages/node/node-sdk/README.md index a8aa1aacc..d119ef03a 100644 --- a/packages/node/node-sdk/README.md +++ b/packages/node/node-sdk/README.md @@ -25,6 +25,12 @@ for the step-by-step flow. This README keeps the package orientation and common at hand; generated [reference documentation](https://contentful.github.io/optimization) remains the source of truth for exported API signatures. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing package versions. +
Table of Contents diff --git a/packages/react-native-sdk/README.md b/packages/react-native-sdk/README.md index 2590fe791..268bc2f9c 100644 --- a/packages/react-native-sdk/README.md +++ b/packages/react-native-sdk/README.md @@ -27,6 +27,12 @@ for the step-by-step flow. This README keeps the package orientation and common at hand; generated [reference documentation](https://contentful.github.io/optimization) remains the source of truth for exported API signatures. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing package versions. +
Table of Contents diff --git a/packages/universal/api-client/README.md b/packages/universal/api-client/README.md index 46421c1b7..96bcf1ae6 100644 --- a/packages/universal/api-client/README.md +++ b/packages/universal/api-client/README.md @@ -23,6 +23,12 @@ We recommend starting applications with Web, React Web, Node, or React Native SD directly when building or maintaining SDK layers, tests, tooling, or first-party integrations that need raw API access. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing package versions or route-dependent infrastructure. +
Table of Contents diff --git a/packages/universal/api-schemas/README.md b/packages/universal/api-schemas/README.md index 42d634df3..43f7c0f51 100644 --- a/packages/universal/api-schemas/README.md +++ b/packages/universal/api-schemas/README.md @@ -23,6 +23,10 @@ This package preserves the historical root exports for Contentful CDA, Experience API, and Insights API schemas. The owning packages maintain those contracts. +If you are upgrading an Optimization integration from v1, follow the +[v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +and use [Migrate imports](#migrate-imports) for this deprecated facade. +
Table of Contents diff --git a/packages/universal/core-sdk/README.md b/packages/universal/core-sdk/README.md index ecb007d27..62e16015e 100644 --- a/packages/universal/core-sdk/README.md +++ b/packages/universal/core-sdk/README.md @@ -26,6 +26,12 @@ when deciding which application-facing package belongs in an integration. Genera [reference documentation](https://contentful.github.io/optimization) remains the source of truth for exported API signatures. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing package versions. +
Table of Contents diff --git a/packages/web/frameworks/nextjs-sdk/README.md b/packages/web/frameworks/nextjs-sdk/README.md index 523c121ea..38dbb0d54 100644 --- a/packages/web/frameworks/nextjs-sdk/README.md +++ b/packages/web/frameworks/nextjs-sdk/README.md @@ -21,6 +21,12 @@ server helpers, React Web roots, and edge-safe Core pass-throughs; it is not a n runtime. The package root intentionally has no runtime export. Import one of the documented subpaths so server, client, router, and edge boundaries stay explicit. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing package versions. + ## What this package provides | Runtime | Import path | Responsibility | diff --git a/packages/web/frameworks/react-web-sdk/README.md b/packages/web/frameworks/react-web-sdk/README.md index d7edfd757..98e4a9a00 100644 --- a/packages/web/frameworks/react-web-sdk/README.md +++ b/packages/web/frameworks/react-web-sdk/README.md @@ -26,6 +26,12 @@ for the step-by-step flow. This README keeps the package orientation and common at hand; generated [reference documentation](https://contentful.github.io/optimization) remains the source of truth for exported API signatures. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing package versions. +
Table of Contents diff --git a/packages/web/preview-panel/README.md b/packages/web/preview-panel/README.md index 37806f4dc..93773a434 100644 --- a/packages/web/preview-panel/README.md +++ b/packages/web/preview-panel/README.md @@ -20,6 +20,12 @@ This package implements the first-party browser preview panel for the micro-frontend and talks to the Web SDK through the preview bridge exposed by the Optimization Web SDK runtime. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> and align this package with the upgraded Web SDK packages. +
Table of Contents diff --git a/packages/web/web-sdk/README.md b/packages/web/web-sdk/README.md index 111f8c32c..8255c09e4 100644 --- a/packages/web/web-sdk/README.md +++ b/packages/web/web-sdk/README.md @@ -27,6 +27,12 @@ for the step-by-step flow. This README keeps the package orientation and common at hand; generated [reference documentation](https://contentful.github.io/optimization) remains the source of truth for exported API signatures. +> [!IMPORTANT] +> +> Upgrading from v1? Follow the +> [v1-to-v2 migration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) +> before changing package versions. +
Table of Contents diff --git a/skills/optimization-guide-authoring/references/authoring-checklist.md b/skills/optimization-guide-authoring/references/authoring-checklist.md index c6f7bba03..29a226bf7 100644 --- a/skills/optimization-guide-authoring/references/authoring-checklist.md +++ b/skills/optimization-guide-authoring/references/authoring-checklist.md @@ -247,6 +247,13 @@ add per-archetype checks. behavior, and cache boundaries. - [ ] Runtime migrations stay split; plugin/privacy/preview and content-model replacement work is routed to shared migration guides instead of folded into every runtime guide. +- [ ] Every staged example names the version or migration state in which it is valid. A preparatory + edit made before the package upgrade does not use a target-version-only API. +- [ ] Adjacent cross-runtime examples name their language or runtime in prose; readers do not have to + infer Swift versus Kotlin, or another runtime distinction, from syntax alone. +- [ ] Every cross-runtime validation item includes its action and observation mechanism inline or + deep-links to the exact runtime subsection that supplies them. A generic link to an integration + guide is not performable verification. ## D. Decision guides (`choosing-the-right-sdk.md` and future)