Changelog

Unreleased

2.4.1 — 2026-10-11

Action needed

• presentPopup / screenChanged with autoPresent now draw a block popup that they used to skip. When a block wins the popup slot and you have not set popups.onBlockPopup (React / React Native / Expo <CFPopupHost>: renderBlock or onBlockPopup), a block with a non-empty #title or #body is shown with the built-in card instead of returning not_handled. To keep the 2.4.0 behaviour, set popups.blockPopups: 'off' (or <CFPopupHost blockPopups="off" />). If you handle onAction, it can now receive a block (see Added). A custom CFPopupPresenter now also receives blocks: check view.kind before reading view.campaign.

Fixed

• An in-app message (instance id starting jm_, delivered under journey_message or the placement you chose) that the person closed came back on every sync when analytics consent was not granted, because the dismiss / cta_click event that removes it is only sent with consent. The SDK now remembers on the device which messages got trackDismiss, trackCtaClick or trackTap (with or without consent; the event itself is still sent only with consent) and leaves them out of getBlock, getBlocks, getAll, variant, subscribe, the sync() result, fetchBlock and the React hooks. It stores instance ids and times only, keeps them for 8 days (at most 200), and clears them on a user change, logout(), deleteIdentity() and resetFrequency(). A block counts as an in-app message by its jm_ instance id, whatever its key; other blocks are unaffected.

Added

• The built-in popup card also draws block popups that use the standard fields: #title, #body, #image (https only), #cta_label, #cta_url; #cta_visible false (a toggle, or the text "false") hides the button. Same theme, layout, RTL, accessibility, delay, one-popup-at-a-time and CTA link rules as in-app campaigns; the result is { shown: true, kind: 'block', id: <instanceId> }. Tracking goes through the block path (trackImpression, then exactly one of trackCtaClick or trackDismiss), so the frequency ledger, the dismissed in-app message list and the instance's statistics all apply. onBlockPopup / renderBlock, when set, always wins; a block without #title / #body is still not_handled. renderCampaignPopup / renderCampaign never applies to blocks.
• popups.blockPopups ('builtIn' default, or 'off') and the blockPopups prop on <CFPopupHost>.
• popups.onAction(item, url) / the onAction prop: item is the campaign, or the block when the CTA came from a built-in block card (tell them apart with 'campaignId' in item). Existing (campaign, url) => … handlers still compile.
• Types CFBlockPopupsMode, CFBlockPopupView, CFPopupView; blockPopupView in @contentflow/sdk/advanced. A custom CFPopupPresenter now receives CFPopupView: check view.kind === 'block' before reading view.campaign.

Changed

• The package's sourcemaps no longer embed the original TypeScript sources. Stack traces still map to file and line; the package is about half the size (2.0 MB packed, was 3.9 MB).

2.4.0 — 2026-10-10

Action needed

• If you route SDK traffic through your own proxy with a CORS allowlist, allow the new request header X-CF-Session-Id, now sent on /sync, /blocks/{key} and /campaigns reads (see Changed). The ContentFlow gateway already allows it.

Added

• Core workspace switches on CFSdkFeatures: contentSync, strings, analyticsEvents, pushPreferences, geofences, profileUpdates (wire keys content_sync, strings, analytics_events, push_preferences, geofences, profile_updates). ContentFlow can now turn these off for one workspace or for every workspace during an incident; the server handles each one with a response the SDK already treats as success. With analytics_events off the SDK also drops events on the device (never sent or stored), reported to subscribeEventDrops with dropReasons.feature_disabled.
• Popup frequency control (#1049). The server already withholds a block or in-app campaign that is capped for the user or device; the SDK now keeps a local ledger with the same rule so caps also hold before the event batch flushes, offline, from cache and within a session. Existing integrations get it without new calls: trackImpression, trackTap / trackCtaClick, trackDismiss, trackConversion and the campaign track* calls update the ledger.
  • client.shouldShow(blockOrCampaign) and client.frequencyReason(...) (capped_impressions | capped_clicks | capped_session | cooldown | stopped_on_<event> | workspace_guard).
  • client.getPopup(screen) / ContentFlow.getPopup(screen): at most one interruptive block or in-app campaign for the screen, highest priority first, after its rule and the workspace popup limits (config.frequency.fatigue: per session, per day, minimum gap). React and React Native: useCFPopup(screen) → { popup, dismiss }, tracking the impression and the dismissal. A background sync does not count a second impression for the popup on screen, and refreshes its content. The popup stays while it is still delivered, or when it is withheld only because its own frequency rule now caps it (a "show once" popup after its impression); a popup paused, disabled, untargeted or expired in the portal comes down on the next sync.
  • trackCampaignDismiss(campaign) for "until the customer closes it" campaigns; ContentFlow.trackCtaClick / trackDismiss on the singleton.
  • resetFrequency() (meant for debug builds; not blocked in release) forgets the local counts so a "once ever" popup can be tested again.
  • Windows use the workspace time zone from config.frequency.timezone (Asia/Riyadh by default): "once per day" resets at local midnight. A login keeps what was counted anonymously on the device; the ledger is cleared on logout() and deleteIdentity(). It stores counters and timestamps only, in the same storage as the other per-device state (secure storage when enabled).
  • CFCampaign.frequency, CFSdkFeatures.frequencyCaps (the frequency_caps workspace switch: off means the SDK ignores its ledger), new types CFPopup, CFFrequencyRule, CFFrequencyConfig, CFSuppressionReason.
• SDK-drawn campaign popup. In-app campaigns (the campaign result of getPopup) can now be shown with a built-in UI; blocks stay app-drawn. Nothing changes for an app that does not opt in.
  • client.presentPopup(screen, { placement?, locale? }) / ContentFlow.presentPopup(screen) → { shown, kind, id?, reason? } (none | already_showing | not_handled | features_off | no_ui_context). A campaign gets the built-in popup (or popups.renderCampaignPopup); a block goes to popups.onBlockPopup(block), which draws and tracks it as before. One popup at a time.
  • client.screenChanged(screen): with popups.autoPresent (default false) presents that screen's popup after popups.delayMs (0 to 60000, default 0); a newer screen cancels a presentation that has not gone up yet.
  • CFConfig.popups: { autoPresent, delayMs, theme, renderCampaignPopup, onBlockPopup, onAction }. onAction(campaign, url) returning true means the app handled the CTA (deep links); otherwise the SDK opens it. Only http, https and app schemes are opened (javascript:, data:, file:, vbscript:, blob: and about: are refused; the cta_click is still tracked). The campaign image is loaded only from https on the web popup and the React Native popup; anything else is dropped.
  • Tracking is automatic, once per presentation: impression when it shows, then exactly one of cta_click (CTA) or dismiss (close button, backdrop, Escape, Android back). Consent gating is unchanged.
  • Web (@contentflow/sdk/web, @contentflow/sdk): a DOM popup in its own shadow root (text via textContent only, role="dialog", focus trap, Escape, prefers-reduced-motion, prefers-color-scheme), installed by createCFClient / ContentFlow.init; createDomPopupPresenter() for a client built by hand.
  • React: <CFPopupHost screen autoPresent renderBlock onAction />. React Native / Expo: <CFPopupHost> from @contentflow/sdk/react-native on RN Modal (Android back, accessibilityViewIsModal, RTL from the locale or I18nManager, no new dependencies).
  • Right-to-left locales (ar, he, iw, fa, ur, ps, sd, yi, ckb) lay the popup out RTL with an Arabic close label for ar.
  • trackCampaignCtaClick(campaign) (campaign cta_click, same payload as the other campaign events), isPopupShowing(), closePopup(), setPopupPresenter(); helpers isAllowedActionUrl, isRtlLocale.

Changed

• One session id per session, sent as X-CF-Session-Id on content reads (/sync, /blocks/{key}, /campaigns) and as context.sessionId on every event batch, so the server can scope once-per-session popup rules and session funnels. The id used to be fixed for the whole client lifetime; it now belongs to the popup frequency ledger and rotates exactly when the ledger starts a new session (cold start, 30 minutes in the background, logout(), deleteIdentity(), resetFrequency()). Events keep the session they were queued in (a batch spanning a rotation is sent as one request per session, the page-unload keepalive flush too). If a later session's request must be retried, only that request and the ones not yet sent are retried; a session's events the server already accepted are never sent twice. The id is a random UUID (sess-<base36> where crypto.randomUUID is unavailable), memory only, with no PII; web, React Native and Expo share the same background detection.
• ScheduleMode is now 'always' | 'payday' | 'ramadan' | 'custom', the modes the server accepts and enforces (#955); BlockSchedule gains tz and precision. The old 'scheduled' and 'off' were never valid on the server. Type-only change.
• Every request now also declares frequency-v1 in X-CF-SDK-Capabilities (erasure-partial-v1,frequency-v1), so analytics can tell which clients enforce frequency locally. Informational only: server-side caps also apply to older SDK versions.

2.3.0 — 2026-10-03

Action needed

• A rejected key stops the SDK for that key (#1006). An HTTP 401, or a 403 with INVALID_SDK_KEY, MISSING_SDK_KEY, SDK_KEY_IN_QUERY or TENANT_KEY_MISMATCH, now stops polling, the live stream and every queue for good, and drops what was queued; later calls reject with CFInvalidKeyError. Only a new client with a corrected key, or an app restart, resumes. Handle CFInvalidKeyError in onError / subscribeErrors() if you want to report it (see Fixed).
• On-device geofencing needs an explicit location grant (#1010). startGeofencing stays idle until the app calls setChannelConsent({ locationTracking: true }); unset location consent is not enough (see Added).
• License. 2.3.0 is the first release under the proprietary ContentFlow SDK License (LICENSE in the package); earlier releases keep their terms. Read it before you upgrade (see Changed).

Fixed

• A rejected SDK key now stops the SDK instead of retrying forever (#1006). The key is dead on an HTTP 401 (any code, or none) or on a 403 with INVALID_SDK_KEY, MISSING_SDK_KEY, SDK_KEY_IN_QUERY or TENANT_KEY_MISMATCH, read from the top-level code or the nested error.code. Other 403s, such as DEVICE_NOT_IDENTIFIED, USER_MISMATCH, IDENTITY_* and location refusals, don't count. When the key dies, the SDK reports one new CFInvalidKeyError (code: 'invalid_sdk_key', with status, serverCode and droppedCount) through onError, subscribeErrors() and getLiveStatus().lastError, and logs it with console.error even without debug. It drops queued events, string-sensor events, the offline outbox and location points. It stops the poll tick and the SSE stream; live status becomes stopped with reason invalid_key. The SDK then sends no more requests with that key: sync() and start() resolve with last-good content, and calls that return a result reject with the same error. The state is held in memory only. Create a new client with a corrected key, or restart the app, to resume. Previously /sync backed off to 5 minutes and kept polling, event batches were dropped one by one, and the stream reconnected forever. CFInvalidKeyError is exported from every entry.
• The SSE stream checks the key with the conditional /sync before every reconnect, on web and React Native, because an EventSource can't see a 401 (#1006). If the key is dead, the stream stops. If the check fails with a transport error or a 5xx, the stream reconnects with the existing backoff.
• Every send queue now holds at most 500 items: the event queue, the offline outbox and the location queue. A larger maxOfflineQueueSize is capped at 500. When a queue is full, the oldest item is dropped. Capacity drops are reported at most once a minute with the count since the last report, instead of one report and warning per dropped event (#1006). The location queue is sent in time-ordered chunks of at most 100 points per request, the gateway's per-request limit, so a large backlog after an outage is no longer refused whole; a chunk that fails with a transport error, 429 or 5xx is retried with everything after it, while chunks already delivered aren't sent again.
• Retries now cover only transport failures, 429 and 5xx, with exponential backoff and jitter (from 1 s, capped at 5 minutes) (#1006). The SDK now honours Retry-After, as seconds or an HTTP date and capped at 1 hour, as the minimum wait. Other 4xx responses are dropped and not retried. Location batches that fail with a transport error, 429 or 5xx are now retried; they used to be dropped. Event batches keep the existing eventRetryPolicy rule: by default, a transport failure or 5xx is reported through onEventsUncertain and isn't replayed.

Added

• On-device geofences (#989): client.startGeofencing({ monitor }) / stopGeofencing() / isGeofencing fetch the workspace's nearest fences from GET /geofences (ETag-conditional), register them with the OS through a GeofenceRegionMonitor, and report OS transitions on POST /location as geofenceEvents with source: "device". @contentflow/sdk/expo adds defineContentFlowGeofenceTask, startExpoGeofencing, stopExpoGeofencing and createExpoGeofenceMonitor on expo-location + expo-task-manager (new optional peer dependencies, injected like expo-notifications). Opt-in only; runs while analytics consent is granted, location consent is not revoked and the location switch is on, and removes every SDK-owned region when one turns off. Nearest-N within the OS limit (iOS 20, Android 100, minus reservedAppRegions), asking for exactly the free slots and using the server's truncated flag (falling back to one more than fits against a server without it), with a boundary region for re-selection after a move; enter and exit are always monitored and reported whatever the trigger flags (the server needs the exit to close a stay), dwell only when on; query lat/lng rounded to 3 decimals; a 502/503 keeps the registered regions and a 200 with no fences removes them; polygons are registered as their bounding circle; refusals are dropped and transport errors kept (max 50); dwell is computed from the enter time at the next wake, timestamped enter time + dwellMs, and skipped when more than 24 h old. A 404 from a gateway without the route leaves geofencing idle without a base-URL diagnosis. Web is not supported (server-side evaluation only). The ContentFlow singleton gains startGeofencing / stopGeofencing. OS registrations outlive the process, so the first start in each process clears every SDK-owned region before registering and every teardown clears them, and stopExpoGeofencing(client, Location) stops the task's regions even when this launch never started geofencing.
• On-device geofencing follow-ups (#1010): geofencing now needs an explicit location grant (setChannelConsent({ locationTracking: true })), the same as Swift; unset location consent keeps it idle. stopGeofencing({ monitor }) (and stopExpoGeofencing(client, Location)) removes SDK regions an earlier launch left even when this launch never started geofencing. OnDeviceGeofence has no name field (the server no longer sends one, #1021).
• New ContentFlow.disableStrings(keys, { writeKey }) (also on CFClient): stop tracking these localization keys; their text is still served. It sends POST /api/v1/strings/disable with X-CF-Write-Key (API root derived from baseUrl, like registerStrings) and resolves to { disabled, alreadyDisabled, unknown } (new StringDisableResult type). Their sensors turn off, so the SDK stops sending string events for them once the next strings refresh drops them from smartKeys. Turn tracking back on in the portal (Sensors → Enable); there is no SDK call for it, and registerStrings never changes tracking. Takes 1 to 500 non-empty keys of at most 200 characters (duplicates dropped) and throws before sending anything otherwise; it throws on a 400/401 or any other failure, like registerStrings. Write key only: call it from a server or CI job, never from a shipped app. Needs the management API's /strings/disable route.
• Workspace feature switches (#907): the SDK reads config.features from /sync and honours the live_updates, campaigns and location switches. Off means no SSE stream (live status reason feature_disabled), getCampaigns() resolving [] without a request, and location tracking paused with unsent points dropped. Missing or malformed values count as on; a 304 keeps the last value, which is also cached with the content. New getFeatures(), subscribeFeatures(), CFConfig.onFeaturesChange and the CFSdkFeatures type. A switch only pauses what the app started and never touches the base URL, keys, authentication, pinning or consent.
• identify() and CFConfig accept optional top-level name and email for a signed-in user. They are sent on POST /identify only when set, so the user is readable in the audience list; omit them for anonymous installs or without analytics consent. New CFClient.revokeAnalyticsLocally() stops sending events and drops everything unsent (event queue, offline queue, location points) without any network call, unlike setConsent(false), which sends an /identify; call dispose() afterwards.

Changed

• App-defined fences (registerGeofence with ids the dashboard doesn't have) no longer reach analytics from device reports; the server records only workspace fences (#989).
• Every request now sends X-CF-SDK-Capabilities: erasure-partial-v1 (with sponsored: true, erasure-partial-v1,sponsored-surface-v1). deleteIdentity() already throws CFWriteFailedError and keeps the device id on a partial erasure, so the gateway now relays its 207 to this SDK instead of a 502 (#968). resolveCapabilities and capabilityHeaderValue (from @contentflow/sdk/advanced) include it. The SDK still never declares sponsored-surface-v1 unless the app opts in.
• License: the SDK is now licensed under the ContentFlow SDK License (proprietary). Earlier releases' license terms are unchanged.

Deprecated

• Deprecated getIndustryProfile(). It now resolves to null without making a request, and logs one deprecation warning per client. It used to call GET /industry-profile, which the gateway never had, so it always returned null anyway. Industry data is write-only from the SDK: send it with updateIndustryProfile(), and ContentFlow uses it server-side. Remove calls to getIndustryProfile(); it will be removed in the next major version (#932).

2.2.2 — 2026-10-01

Action needed

• Every request now also sends X-CF-SDK-Capabilities (empty unless you set sponsored: true). If you route SDK traffic through your own proxy with a CORS allowlist, allow that header; the ContentFlow gateway already does.

Fixed

• The root entry @contentflow/sdk now exports consentPathsToConfig and the error classes (CFError, CFInvalidBaseUrlError, CFWriteFailedError, CFPartialWriteError, CFUnknownConsentPresetError, CFConsentConfigUnavailableError, CFLocalesUnavailableError, CFMalformedResponseError), plus the types CFErrorCode, ConsentConfig, ConsentPreset, ConsentPresetTopic and ConsentRequestOptions. The README imports consentPathsToConfig from the root, which failed to resolve. Additive only; nothing was removed. Use the error classes from the entry you import the client from: each entry is a separate bundle with its own copy, so instanceof only matches classes from the same entry.
• @contentflow/sdk/embed now reads its data-cf-* attributes (data-cf-key, data-cf-base, data-cf-locale, data-cf-consent, data-cf-debug) when loaded as <script type="module" src="…/embed.js" …>. The built file is an ES module, where document.currentScript is always null, so the attributes were never read and only window.contentflow worked. The embed now finds its own tag by matching its module URL against the page's module scripts. Precedence per field: window.contentflow > data attributes > defaults, so existing window.contentflow setups behave exactly as before. A classic <script src> (without type="module") still cannot load the file.

Added

• Every request sends X-CF-SDK-Version: <platform>/<version>: js/2.2.2 from the root, /web, /react, /embed and /advanced entries, react-native/2.2.2 from the React Native adapter (#903). It was the bare version (2.2.1). The platform comes from the new PlatformAdapter.sdkPlatform; a custom adapter that doesn't set it reports js.
• Every request sends X-CF-SDK-Capabilities: empty by default, sponsored-surface-v1 only when the app opts in with sponsored: true, exactly as before (#903). The header used to be omitted when empty.

Changed

• capabilityHeaderValue (from @contentflow/sdk/advanced) returns '' instead of undefined when nothing is declared.

Docs

• JSDoc examples in @contentflow/sdk/web, /react and /react-native, and the contentflow-pull CLI help, use <workspace-id>_test placeholders instead of key-shaped values, and name where keys live in the portal: Developers → Your keys. The unreferenced examples/web.html and examples/react-native.tsx (esm.sh imports, hard-coded consent) are removed (#897).

2.2.1 — 2026-09-30

Action needed

• The default base URL changed from https://app.contentflow.click/sdk/v1 to https://api.contentflow.click/sdk/v1. Only apps that don't set baseUrl are affected; the old host keeps working. (The JS SDK can't pin certificates, so there is no pinning action.)
• A base URL that doesn't end in /sdk/v1 now logs one notice per client (never blocking): ContentFlow: baseUrl <value> uses a legacy path. Update it to https://api.contentflow.click/sdk/v1 (see the 2.2.1 release notes).

Changed

• Default baseUrl is https://api.contentflow.click/sdk/v1 (the SDK host; app.contentflow.click is the portal).
• The React Native example pins expo ~57.0.26.

Added

• Base URL configuration without code. Precedence: an explicit baseUrl > globalThis.__CONTENTFLOW_BASE_URL__ (a page global) > the default. The global must be https (http only for localhost, 127.0.0.1, 10.0.2.2); an invalid value is ignored with a warning. The SDK never reads process.env; pass Vite, Next.js or Expo build values as baseUrl (see the README).

2.2.0 — 2026-09-26

Breaking / action needed

• Device location is now gated on analytics consent: without it nothing is collected or uploaded, and revoking consent stops tracking and discards unsent points. Restart tracking after consent is granted again.
• React Native: device location needs a geolocation module passed to the SDK (<CFProvider geolocation={Geolocation}> or createRNPlatform({ geolocation }), e.g. @react-native-community/geolocation); without one requestLocation() rejects immediately.
• A confirmed deleteIdentity() disposes the client; create a new one afterwards (the ContentFlow facade resets itself).

Changes

• Add deleteIdentity() (client and ContentFlow facade): GDPR / PDPL erasure through DELETE /identify. Analytics collection stops first (consent revoked locally, pending and offline events dropped). A confirmed complete erasure wipes persisted identity state, the visitor id and the device id, then disposes the client; create a new one afterwards (the facade resets itself). A partial or unconfirmed erasure throws write_failed and keeps the device id for a retry. New type DeleteIdentityReceipt.
• enableSecureStorage now does something. It was on by default but CFSecureStorage was never used. Analytics consent, channel consent and segment membership are now stored XOR-obfuscated (not encrypted) under cf_sec_ keys. Existing plain values migrate on first read, and switching the flag off migrates them back; the old copy is removed only after the new write succeeds, and the device id is never moved or regenerated. The device id stays plain (it is the obfuscation key's root). Runtimes without SHA-256 keep plain storage.
• Fix: location data was silently dropped. Location batches sent points and geofence events sent top-level fields; the gateway's POST /location reads locations[] and geofenceEvents[], so it accepted the requests and stored nothing. Both now match the gateway handler exactly.
• Fix: updateIndustryProfile 404'd. It now sends POST /profile with { userId, category, data } (a domain-profile update, stored under customAttributes.domainProfile.<industry>) and requires a signed-in user.
• Add registerStrings(strings, { writeKey }) (client and facade): strings as code, server/CI only, POST /api/v1/strings/sync (API root derived from baseUrl) with X-CF-Write-Key, same payload as the Swift, Kotlin and Flutter SDKs. New types StringRegistration, StringRegistrationOptions, StringRegistrationResult.
• Fix: device location never worked. requestLocation() waited on a callback nothing called (always timed out) and startLocationTracking() never watched. The platform adapter now supplies geolocation: navigator.geolocation on the web, and on React Native a navigator.geolocation-shaped module passed as geolocation (e.g. @react-native-community/geolocation). The permission prompt appears only on those explicit calls. Without an adapter, requestLocation() rejects immediately. New PlatformAdapter.geolocation, fromNavigatorGeolocation and related types.
• Location privacy. Location is gated on analytics consent: nothing is collected or uploaded without it, and every upload re-checks it. Revoking consent, deleteIdentity() and dispose() stop the platform watch and discard unsent points without flushing; deleteIdentity() does this before sending DELETE /identify and waits out any upload already in flight, so no location request follows an erasure. On an identity change (setUserId, logout, identify with a new user) points collected for the outgoing user are sent as that user first, or dropped, and are never retried under the incoming one.
• Documented as not yet available (no delivery-API route): submitKYC, getKYCState, getIndustryProfile.

2.1.0 — 2026-09-24

• No JavaScript SDK API or behaviour changes. The version moves to 2.1.0 so all four ContentFlow SDKs (JS, Swift, Kotlin, Flutter) release together; the Kotlin and Flutter SDKs have breaking changes in this release (see their changelogs).
• The React Native example pins expo ~57.0.25.
• The JS SDK does not do certificate pinning: enableCertificatePinning (and enableRequestSigning) still throw at init, because fetch cannot enforce them. Pin in a native wrapper or a trusted server proxy.

1.2.0 — 2026-09-19

• Add device-scoped, idempotent push token removal with unregisterPush().
• Add durable logout(), device-only channel consent receipts, push linkage receipts, HMS configuration forwarding, and typed partial-write receipts for proven identity changes.
• Serialize identity and consent writes by public API invocation order. Analytics revocation now disables collection and purges pending events immediately, while grants require an explicit server confirmation and cannot override a newer revocation.
• Reject nested success:false responses and malformed successful bodies; identify failures now reject the promise. Read outages preserve last-good content.
• Isolate persisted caches by endpoint, workspace, publishable key, installation, user and audience generation; same-user targeting changes invalidate every locale/namespace and late response, while logout clears the old outbox.
• Bound event batches to 100 and await an already-running flush. Preserve aggregate dropReasons, require exact accepted+dropped accounting, and report unaccounted events without replaying accepted items. Report uncertain transport/server delivery; automatic replay requires explicit eventRetryPolicy: 'at-least-once' and may duplicate metrics.
• Recover from unavailable storage, report offline eviction/expiry/retry exhaustion, and check consent on every offline delivery.
• Pause polling, SSE reconnects and periodic event flushes in the background; force blocks and strings reconciliation before foreground live work resumes.
• Send canonical locale query and Accept-Language, keep sync/string validators separate, remove stale validators when a response provides none, and evaluate locale-keyed campaigns through public /campaigns with exact/neutral/English resolution.
• Export campaign hooks for React and fix campaign user identity / industry event shape.
• Add installable archive samples for Web, React and React Native.
• Add observable live delivery status: client.getLiveStatus(), client.subscribeLiveStatus(), CFConfig.onLiveStatus, and the React/React Native useLiveStatus() hook. Reports mode (stream/poll/off), state, a reason (e.g. stream_unsupported, live_disabled, backgrounded), since, and a sticky lastError — previously a stream falling back to polling, or failing to stream at all, was visible only with debug: true.
• Add scoped overrides to fetchBlock(key, { locale?, deviceId? }): a one-off read of another locale or another install's content without calling setLocale() (which re-syncs the whole app). An override is never written into the block cache, the sync list, or the active locale/device identity; a call with no options is unchanged.
• Pre-consent analytics refusals are now reported, not silent. Every track*/trackString call made before setConsent(true) produces a drop report (source: 'local', reason: 'consent_not_granted') through the existing client.subscribeEventDrops() / CFConfig.onEventsDropped machinery. The underlying policy is unchanged: pre-consent events are still never collected, queued, retained, or replayed once consent arrives.
• Add EventDropInfo.source / EventsDroppedInfo.source ('local' | 'server') on every drop report, so a caller can tell the SDK's own refusals (queue full, identity changed, pre-consent) from a server-side drop. Reports from older SDKs carry no source; its absence means nothing either way.
• Add caller-visible read failures: client.subscribeErrors(), CFConfig.onError, and client.getLiveStatus().lastError now report a misconfigured baseUrl as a typed CFInvalidBaseUrlError (code: 'invalid_base_url') — the same error instance on all three surfaces. fetchBlock() and getStrings() now reject with it instead of resolving undefined/last-good strings (see Migration notes below); sync()/start() still resolve with last-good content and only report it. An ordinary transient outage (503, timeout) is unaffected and fires none of this.
• Realign ConsentPreset to what GET /sdk/consent/config/:preset actually sends: preset, industry, region, required/optional (dotted consent paths, e.g. channels.push, marketing.promotional, location), defaultTopics, availableTopics, legalFramework. The previous declared shape (id/name/nested channels/marketing/location booleans) never matched the wire, so those reads were silently undefined; id/name are kept as deprecated aliases of preset. Add consentPathsToConfig(paths, value?) to turn a preset's dotted paths into the flat ConsentConfig the write methods take. Reading a preset never grants consent.
• getConsentConfig() now throws typed errors instead of a generic Error: CFUnknownConsentPresetError (unknown preset id, carries availablePresets), CFConsentConfigUnavailableError (service failure), CFMalformedResponseError (200 with a body that doesn't match the schema). requestConsent({ preset }) propagates them unchanged. Valid preset ids: banking_ksa, insurance_ksa, healthcare_ksa, travel_ksa, retail_ksa, food_delivery_ksa, fintech_ksa — there is no default.
• Add client.getLocales() / client.getCachedLocales() — the workspace's published-locale catalog ({ locales, sourceLocale, version }), ETag-revalidated with its own validator, independent of the sync/strings validators. Every failure is typed (CFLocalesUnavailableError, CFMalformedResponseError); the SDK never synthesizes en/ar when the route is unavailable. An empty locales list is a valid answer.
• Add a theming primitive: parseCFColor(), getBlockColor(), getBlockColors(), themeFromBlock(), plus the 'color' CFFieldType and the React/React Native useCFTheme() hook (built on useCFBlock, so it follows the same live-update/cache semantics and does not itself fire an impression event). Turns a block's color field values into typed CFColor objects (hex, rgba, raw); this is a color reader, not a UI or design-token framework.
• Add @contentflow/sdk/expo: registerExpoPush() / registerExpoPushOrThrow() / unregisterExpoPush(), a dependency-injected helper for Expo apps using expo-notifications. Registers only the native device token (getDevicePushTokenAsync()); an Expo relay token (ExponentPushToken[...]) or a web PushSubscription token is rejected as unsupported_token rather than forwarded, since ContentFlow delivers through APNs/FCM/HMS directly. Does not touch consent — getting OS notification permission is not the same as ContentFlow push consent.

Migration: handle identify() rejection, use onEventsUncertain, and retain app fallbacks. Legacy unscoped caches are intentionally ignored because their workspace ownership is unknown. enableRequestSigning and enableCertificatePinning now reject at initialization: the JavaScript fetch transport never implemented those guarantees. Use a trusted proxy or native host integration when required. No public registry publication is implied by this source release.

enableOfflineQueue persists batches handed off while connectivity is already known offline. Ordinary pending, periodic and online 429 retry batches are memory-only and may be lost on process death; 1.2.0 does not claim a fully durable behavioral outbox.

Migration notes (1.2.0 behaviour changes)

• fetchBlock() / getStrings() now reject on a misconfigured baseUrl. They used to resolve with undefined / last-good strings. Because setLocale() awaits getStrings(), it now propagates that rejection too. Every other failure mode is unchanged. Background callers (poll tick, SSE refresh, start(), the React useCFTranslations hook) swallow this by design — use subscribeErrors() / onError to observe it there.
• getConsentConfig() now throws typed errors instead of a generic Error('Failed to fetch consent preset: …'). Catch CFUnknownConsentPresetError / CFConsentConfigUnavailableError / CFMalformedResponseError (or match on .code) instead of parsing the message string.
• ConsentPreset gained real fields (preset/industry/region/optional/defaultTopics/availableTopics/legalFramework); id/name are now deprecated aliases of preset rather than the primary fields — update code that reads .id/.name as the canonical identifier.
• Drop reports now carry source. A listener that branched on dropReasons alone still works; one that assumed every drop was server-reported should check source !== 'server' before treating a report as a backend signal. Pre-consent tracking now produces a drop report where it previously produced silence — a listener counting drops will see new, expected entries for any call made before consent is granted.

Generated from the ContentFlow repository by sdk-release/scripts/render-docs.mjs. Downloads and checksums are on Releases and downloads. The SDKs are licensed under the ContentFlow SDK License.