Skip to content

feat(nextjs): add cache-safe optimization handoff support #379

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Charles Hudson (phobetron) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(nextjs): add cache-safe optimization handoff support #379

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,11 @@ Native and E2E examples; narrow with test-file, suite, scheme, or flow arguments
remove behavior, narrow public APIs, obscure readable code, add one-off shims, or change source
structure for bundle size unless the requester or maintainer explicitly approves that exact
proposal.
- When reviewing an existing changeset, assume included bundle-size budget changes already have the
required requester or maintainer approval unless the user explicitly asks to audit approval. Do not
flag budget bumps as findings, risks, or noteworthy by themselves; only report concrete validation
problems such as a failing size check, a budget applied to the wrong bundle, or inconsistent
package policy.
- Do not infer bundle-size tradeoff approval from general requests such as "fix CI", "make checks
pass", "get under budget", or an implementation request.
- Stop and surface the remaining overage when the remaining options would reduce maintainability,
Expand Down
38 changes: 19 additions & 19 deletions documentation/authoring/blueprints/android-compose.md
View file
Open in desktop

Large diffs are not rendered by default.

36 changes: 18 additions & 18 deletions documentation/authoring/blueprints/android-views.md
View file
Open in desktop

Large diffs are not rendered by default.

34 changes: 17 additions & 17 deletions documentation/authoring/blueprints/ios-swiftui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ guide: ../../guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md
- **Deliberate simplifications:** Consent starts granted; entry rendering is deferred to Core because
the app must supply the Contentful fetch.
- **Explainer switches:** profile point = include; managed-fetch clause = omit.
- **Fact sources:** [setup](../../internal/sdk-knowledge/native/ios.md#setup--factory),
- **Fact sources:** [setup](../../internal/sdk-knowledge/native/ios.md#setup--initialization-and-binding),
[events](../../internal/sdk-knowledge/native/ios.md#events--tracking),
[package](../../internal/sdk-knowledge/native/ios.md#package--entry-points).

Expand All @@ -37,21 +37,21 @@ guide: ../../guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md

## Section map

| Section | Category | Purpose | Must teach or show | Fact sources |
| ------------------------------------------ | ------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Install and initialize the SwiftUI root | Required for first integration | Establish the SDK-owned client and the SwiftUI provider tree. | SPM add and Xcode build/run; `OptimizationRoot` diff; `@EnvironmentObject` access; readiness gate; synchronous throwing init. | [setup](../../internal/sdk-knowledge/native/ios.md#setup--factory), [package](../../internal/sdk-knowledge/native/ios.md#package--entry-points) |
| Consent and privacy-policy handoff | Common but policy-dependent | Replace the quick-start default-on shortcut and explain the two axes. | Two-axis example; boolean versus split consent; pre-consent allow-list; app-owned policy. | [consent](../../internal/sdk-knowledge/native/ios.md#consent--persistence) |
| Contentful entry fetching and locale shape | Required for first integration | Establish the app-owned single-locale fetch that feeds resolution. | App owns the CDA fetch (no managed path); single-locale and include depth; SDK locale versus CDA locale. | [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution), [identifiers](../../internal/sdk-knowledge/native/ios.md#identifier-ownership) |
| Entry resolution and fallback rendering | Required for first integration | Complete the entry half of Milestone 1 through `OptimizedEntry`. | Render-closure example and cast; direct `resolveOptimizedEntry` alternative; baseline fallback; loading treatment. | [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution), [fallback](../../internal/sdk-knowledge/native/ios.md#failure--fallback-behavior) |
| Screen events and SwiftUI navigation | Required for first integration | Deepen the quick-start screen proof across SwiftUI navigation. | `.trackScreen` placement; `trackCurrentScreen` for dynamic names and route keys; dedupe; choose-one-path warning. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |
| Entry interaction tracking | Common but policy-dependent | Explain viewport-based views and taps and their opt-outs. | Scroll provider; thresholds; tap versus SwiftUI `Button`; `trackViews`/`trackTaps` opt-outs; `onTap` gating. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |
| Identity, profile state, and reset | Common but policy-dependent | Integrate login/logout and profile continuity. | Identify/reset example; `UserDefaults` continuity; reset preserves consent. | [consent](../../internal/sdk-knowledge/native/ios.md#consent--persistence), [identifiers](../../internal/sdk-knowledge/native/ios.md#identifier-ownership) |
| Custom events and analytics diagnostics | Optional | Cover business events and the debug/forwarding seam. | `track` example; passthrough `eventStream` with subscribe-before-fire; `blockedEventStream`; forwarding link. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |
| Custom Flags and MergeTag rendering | Optional | Cover content-model-dependent reads. | `getFlag` versus `flagPublisher`; `getMergeTagValue`; flag-view exposure governance. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking), [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution) |
| Live updates | Optional | Allow mounted entries to re-resolve. | Root and per-entry scopes; locked-by-default explanation; preview forces live; panel-close snapshot. | [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution), [runtime](../../internal/sdk-knowledge/native/ios.md#version--runtime-quirks) |
| Preview panel | Optional | Add the debug/authoring surface. | Debug gating; `PreviewPanelConfig`; `PreviewContentfulClient` for names; overlay placement. | [runtime](../../internal/sdk-knowledge/native/ios.md#version--runtime-quirks) |
| Strict event policy and endpoint controls | Advanced or production-only | Expose production privacy and endpoint posture. | `allowedEventTypes: []`; `onEventBlocked`/`blockedEventStream` proof; API endpoint overrides; queue policy. | [consent](../../internal/sdk-knowledge/native/ios.md#consent--persistence), [setup](../../internal/sdk-knowledge/native/ios.md#setup--factory) |
| Offline delivery and lifecycle flushing | Advanced or production-only | Explain constrained-network delivery. | Reachability and background flush; in-memory queue plus 100-event cap; no durable outbox; `flush()` checkpoints. | [runtime](../../internal/sdk-knowledge/native/ios.md#version--runtime-quirks), [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |
| Section | Category | Purpose | Must teach or show | Fact sources |
| ------------------------------------------ | ------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Install and initialize the SwiftUI root | Required for first integration | Establish the SDK-owned client and the SwiftUI provider tree. | SPM add and Xcode build/run; `OptimizationRoot` diff; `@EnvironmentObject` access; readiness gate; synchronous throwing init. | [setup](../../internal/sdk-knowledge/native/ios.md#setup--initialization-and-binding), [package](../../internal/sdk-knowledge/native/ios.md#package--entry-points) |
| Consent and privacy-policy handoff | Common but policy-dependent | Replace the quick-start default-on shortcut and explain the two axes. | Two-axis example; boolean versus split consent; pre-consent allow-list; app-owned policy. | [consent](../../internal/sdk-knowledge/native/ios.md#consent--persistence) |
| Contentful entry fetching and locale shape | Required for first integration | Establish the app-owned single-locale fetch that feeds resolution. | App owns the CDA fetch (no managed path); single-locale and include depth; SDK locale versus CDA locale. | [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution), [identifiers](../../internal/sdk-knowledge/native/ios.md#identifier-ownership) |
| Entry resolution and fallback rendering | Required for first integration | Complete the entry half of Milestone 1 through `OptimizedEntry`. | Render-closure example and cast; direct `resolveOptimizedEntry` alternative; baseline fallback; loading treatment. | [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution), [fallback](../../internal/sdk-knowledge/native/ios.md#failure--fallback-behavior) |
| Screen events and SwiftUI navigation | Required for first integration | Deepen the quick-start screen proof across SwiftUI navigation. | `.trackScreen` placement; `trackCurrentScreen` for dynamic names and route keys; dedupe; choose-one-path warning. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |
| Entry interaction tracking | Common but policy-dependent | Explain viewport-based views and taps and their opt-outs. | Scroll provider; thresholds; tap versus SwiftUI `Button`; `trackViews`/`trackTaps` opt-outs; `onTap` gating. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |
| Identity, profile state, and reset | Common but policy-dependent | Integrate login/logout and profile continuity. | Identify/reset example; `UserDefaults` continuity; reset preserves consent. | [consent](../../internal/sdk-knowledge/native/ios.md#consent--persistence), [identifiers](../../internal/sdk-knowledge/native/ios.md#identifier-ownership) |
| Custom events and analytics diagnostics | Optional | Cover business events and the debug/forwarding seam. | `track` example; passthrough `eventStream` with subscribe-before-fire; `blockedEventStream`; forwarding link. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |
| Custom Flags and MergeTag rendering | Optional | Cover content-model-dependent reads. | `getFlag` versus `flagPublisher`; `getMergeTagValue`; flag-view exposure governance. | [events](../../internal/sdk-knowledge/native/ios.md#events--tracking), [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution) |
| Live updates | Optional | Allow mounted entries to re-resolve. | Root and per-entry scopes; locked-by-default explanation; preview forces live; panel-close snapshot. | [render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution), [runtime](../../internal/sdk-knowledge/native/ios.md#version--runtime-quirks) |
| Preview panel | Optional | Add the debug/authoring surface. | Debug gating; `PreviewPanelConfig`; `PreviewContentfulClient` for names; overlay placement. | [runtime](../../internal/sdk-knowledge/native/ios.md#version--runtime-quirks) |
| Strict event policy and endpoint controls | Advanced or production-only | Expose production privacy and endpoint posture. | `allowedEventTypes: []`; `onEventBlocked`/`blockedEventStream` proof; API endpoint overrides; queue policy. | [consent](../../internal/sdk-knowledge/native/ios.md#consent--persistence), [setup](../../internal/sdk-knowledge/native/ios.md#setup--initialization-and-binding) |
| Offline delivery and lifecycle flushing | Advanced or production-only | Explain constrained-network delivery. | Reachability and background flush; in-memory queue plus 100-event cap; no durable outbox; `flush()` checkpoints. | [runtime](../../internal/sdk-knowledge/native/ios.md#version--runtime-quirks), [events](../../internal/sdk-knowledge/native/ios.md#events--tracking) |

## SDK-specific authoring overrides

Expand All @@ -61,7 +61,7 @@ guide: ../../guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md
- Prove "init plus one accepted screen event" rather than an entry render in the quick start: iOS has
no managed fetch, so an entry-render proof would force an app-specific Swift CDA fetch into the
quick start. Entry rendering moves to Core. Facts:
[setup](../../internal/sdk-knowledge/native/ios.md#setup--factory),
[setup](../../internal/sdk-knowledge/native/ios.md#setup--initialization-and-binding),
[render](../../internal/sdk-knowledge/native/ios.md#render--entry-resolution).
- Keep the native package/build step inline in the quick start: add the Swift Package in Xcode, then
build and run on a simulator (there is no `pod install`). Facts:
Expand Down
Loading
Loading