SDK

setEnvironment(…​)

setPageVisit(…​)

setChannel(…​)

setConsent(…​)

setDeviceId(…​)

setUserId(…​)

setContextItem(…​)

setContextItemType(…​)

recommendation list name, limit, or list_size

block-specific filters and variables

recommendation request arguments passed to getRecommendations(…​), useCreateReco(…​), or useRecoList(…​)

block-specific rendering and layout

froomle:before-init: pre-init settings that must affect the first automatic request.

froomle:init: post-init orchestration once initialization completes.

window.FroomleFrontendSdkReady: sticky fallback for late-loaded consumers.

froomle:before-init: pre-init hook, fired before DOM init and before the first recommendation request.

froomle:init: post-init hook, fired once when SDK initialization completes.

window.FroomleFrontendSdkReady: sticky readiness promise for consumers that may attach after events already fired.

integration.primaryMode: runtime owner for the page when the SDK can resolve one (dom, framework, or programmatic).

integration.observedModes: observed browser-side usage flags for dom, framework, and programmatic.

integration.sources: ordered unique list of observed runtime sources such as dom:auto, framework:react, or programmatic:sendPurchase.

integration.lastSource: latest observed source, useful when debugging mixed environments.

init.scope: init owner scope. For the current browser DOM lifecycle this is dom.

init.status: DOM/script-tag init lifecycle (idle, before-init, initializing, ready, failed).

init.trigger: whether DOM init started as auto or manual.

init.error: last DOM/script-tag init error when init.status is failed; otherwise null.

init.ready: sticky readiness promise for DOM/script-tag init.

diagnostics.config: support-facing effective SDK state for the current page, including sdkVersion, environment, request routing, page context, consent, and identity presence.

diagnostics.config.sdkVersion: SDK runtime version reported by the current browser bundle, useful when checking whether a rollout actually loaded the expected release.

diagnostics.config.environment, pageType, channel, consent, contextItem, and contextItemType: effective page/event/recommendation context after script attributes, init options, and runtime setters have been applied.

diagnostics.config.hasUserId and hasDeviceId: boolean identity-presence flags. They do not expose the actual user_id or device_id.

diagnostics.config.requestDomain: effective request host configured through setRequestDomain(…​) or script-tag data-froomle-request-domain. This is useful when debugging custom-domain, proxy, and CNAME browser integrations. It stays null when the current integration never configured an explicit request host.

diagnostics.config.requestOrigin: effective browser request origin derived from requestDomain and the current transport mode. When setSafeRequest(false) is active it uses http://…​;; otherwise it uses https://…​;. It stays null when requestDomain is null.

diagnostics.config.deviceIdOwnership: best-known identity provenance for the current browser device_id:

diagnostics.config.deviceIdSource: most recent observed path for the current device_id, for example sdk-generated, setDeviceId, data-froomle-device-id, froomle_device_id-cookie, or recommendations-response.

diagnostics.config.deviceIdContinuity: cross-page/cross-tab continuity classification for the current browser device_id, for example no-previous-state, stable-since-previous-page-load, changed-since-previous-page-load, fresh-identified-after-anonymous-interval, anonymous-after-identified-state, or anonymous.

diagnostics.config.deviceIdWarnings: support-facing anomaly flags such as empty-string-hash, changed-during-page-lifecycle, or customer-id-before-consent-source-ready.

diagnostics.lifecycle: support-facing lifecycle observations separate from the core init contract. This includes whether froomle:before-init and froomle:init were dispatched and the inferred browser loading mode (blocking, defer, async, or custom).

diagnostics.traffic: timestamps of the last recommendation/event request attempt and the last stringified error summary, when available.

diagnostics.benchmark.defaultConfig: the current default benchmark config from setBenchmark(…​) or script-tag data-froomle-benchmark-* inputs. This is a convenience default, not a page-wide truth about one active user_group.

diagnostics.benchmark.lastRequestConfig: the last effective benchmark config that actually shaped a benchmarked recommendation request.

diagnostics.benchmark.lastRequestListNames: the last benchmarked list names seen on the wire.

diagnostics.benchmark.lastResolvedRequestId, lastResolvedUserGroup, lastResolvedBranch, lastResolutionSource: support-facing summary of the most recent benchmarked request/placement resolution.

diagnostics.benchmark.lastPlacementSurface, lastPlacementVariant, and lastPlacementRenderStrategy: where the last benchmarked placement was resolved (dom or react), which diagnostic variant was observed (response-driven means benchmark config without SDK-owned control content; control-aware means SDK-owned control content was provided), and which rendering strategy the SDK used for that placement. Current benchmark rendering uses wait, which hides the placement until the branch is resolved to avoid control-then-treatment flicker.

diagnostics.benchmark.lastUsedReturnedRecommendationContent: whether the most recent benchmarked control branch used returned Froomle content instead of customer/control content. With the current strict branch contract this should stay false; returned Froomle content is ignored on the customer/control branch unless a future explicit fallback option is introduced.

diagnostics.benchmark.observedVariants: cumulative flags for whether this runtime has already exercised branch-aware benchmark requests without SDK-owned control content (responseDriven) and/or SDK-owned control-aware benchmark behavior (controlAware).

diagnostics.benchmark.warnings: recent benchmark-specific dev/support warnings, for example missing/unusable control content on a customer/control branch, or unusable React raw control items that were skipped.

diagnostics.smartSorting: support-facing state for smart sorting and reranking. It reports the last resolved surface (dom, programmatic, or react), list name, candidate count, fixed-rank count, response count, unmatched candidate count, and recent smart-sorting warnings.

diagnostics.autoExclusions: support-facing state for opt-in in-page exclusion collection. It reports whether collection is enabled, the effective selector config, request-batching split summaries, the last collection surface (dom, programmatic, framework, or react), collected/skipped counts, last sent histories.exclude entries, diagnostics-only origin/source attribution, and recent auto-exclusion warnings.

diagnostics.autoExclusions.enabled and effectiveConfig: whether automatic exclusion collection is active and which effective selector/source config was used most recently.

diagnostics.autoExclusions.lastBatchingAt: timestamp of the last request-batching diagnostics update.

diagnostics.autoExclusions.lastBatchingSurface: surface that produced the last batching diagnostics update (dom, programmatic, framework, or react).

diagnostics.autoExclusions.lastBatchingSplitByExclusions: true when the last React or framework/queued recommendation batch had to be split into multiple outgoing requests because placements resolved to different histories.exclude sets. Use this together with lastBatchingPlacementCount, lastBatchingOutgoingRequestCount, and lastBatchingExclusionSignatureCount to verify whether in-page deduplication changed request coalescing.

diagnostics.autoExclusions.lastBatchingPlacementCount, lastBatchingOutgoingRequestCount, and lastBatchingExclusionSignatureCount: batching counters for the last grouped recommendation pass.

diagnostics.autoExclusions.lastCollectionAt: timestamp of the last exclusion collection pass.

diagnostics.autoExclusions.lastCollectionSurface: surface that performed the last exclusion collection pass (dom, programmatic, framework, or react).

diagnostics.autoExclusions.lastCollectedCount: number of exclusions collected in the last collection pass before request sending.

diagnostics.autoExclusions.lastSkippedCurrentPlacementCount: number of collected candidates skipped because they belonged to the current recommendation placement and includePlacement was not enabled.

diagnostics.autoExclusions.lastSkippedInvisibleCount: number of selector candidates skipped because the source required visible elements and the candidate was not visible.

diagnostics.autoExclusions.lastMissingIdCount: number of selector candidates skipped because no usable item id could be extracted.

diagnostics.autoExclusions.lastSourceCounts: count of last collected exclusions by source type before request sending.

diagnostics.autoExclusions.lastSentCount: number of exclusions sent on the most recent recommendation request.

diagnostics.autoExclusions.lastSentOriginCounts: count of last sent exclusions by primary diagnostics origin. Supported origins are manual-api, request-option, selector, and unknown.

diagnostics.autoExclusions.lastSentExclusions[].origin, source, and origins: diagnostics-only attribution for a sent exclusion. For example, manual-api means addExclusions(…​), request-option means request-level exclusions, and selector means DOM selector collection. These fields are not sent to the recommendation API.

diagnostics.autoExclusions.warnings: recent auto-exclusion-specific dev/support warnings such as invalid selectors, unusable regexes, or raw histories override warnings.

window.FroomleFrontendSdkReady remains available and aliases window.FroomleFrontendSdkRuntime.init.ready.

window.FroomleFrontendSdkDiagnostics remains available as a convenience alias to window.FroomleFrontendSdkRuntime.integration.

For new browser-side diagnostics and support tooling, prefer window.FroomleFrontendSdkRuntime and treat diagnostics as observational support state, not as a new control surface.

auto: the SDK started itself during script evaluation (standard behavior in script-tag usage).

manual: the SDK was started via init().

froomle_device_id

froomle_user_id

froomle_consent

__froomle_device_diagnostics_v1

On load, the SDK reads existing cookie values and reuses them.

If identity is passed via script attributes or setters, the SDK updates the matching cookie.

Calling setFroomleConsent(…​) (or window.FroomleFrontendSdk.setConsent(…​)) updates froomle_consent.

In script-tag/global mode, the live SDK <script> element also mirrors data-froomle-consent, data-froomle-user-id, and data-froomle-channel after the corresponding setters run, including late same-page updates.

Other data-froomle-* attributes remain boot inputs. In particular, data-froomle-device-id is not rewritten from SDK-managed identity.

When consent becomes 2 and device_id is still no-consent, the SDK generates a UUID device id and stores it.

If consent later drops to 0 or 1, the active SDK identity returns to no-consent.

If consent later returns to 2 after an anonymous interval, the SDK creates a fresh identified device_id instead of reviving the previous one.

Reapplying the same consent level does not rotate device_id.

The localStorage diagnostics snapshot is used only to compare device-id continuity across reloads and tabs for support/debug purposes.

The localStorage diagnostics snapshot is not sent to the backend and does not affect recommendation or event-tracking behavior.

first-party cookie

path=/

samesite=lax

long-lived max-age (20 years in current implementation)

Let the SDK manage device_id in normal browser integrations. Do not call setDeviceId(…​) from the CMP bridge unless your backend contract intentionally owns device identity.

Consent levels 0 and 1 are anonymous states; consent level 2 is the identified state.

If the CMP moves from 2 to 0 or 1, the SDK returns to anonymous no-consent identity.

If the CMP later moves from 0 or 1 back to 2, the SDK creates a fresh identified device_id rather than reviving the previous one.

Reapplying the same consent level should not rotate device_id.

Consent 0: popular/non-personalized behavior, no tracked events.

Consent 1: event tracking enabled, personalization identity still anonymous.

Consent 2: full personalization and identified tracking when identity is set.

Auto-exclusions are disabled by default.

Request-level autoExclusions overrides the global config from setAutoExclusions(…​) for that request.

Automatic collection is only reliable when the page exposes stable item IDs. Prefer data-froomle-id and data-froomle-item-type.

data-froomle-action-item is event metadata. It is not used for exclusions unless you explicitly configure it as a selector source.

By default, the SDK excludes explicit page items but not the current recommendation placement itself.

Exclusions are merged and deduplicated by item_type + id.

Queued placements with identical effective exclusion sets can still share one outgoing recommendation request.

Queued placements with different effective exclusion sets are split into separate outgoing recommendation requests, because histories.exclude applies to the full backend request.

Exclusions are request-local response filters. They may be sent under consent levels 0 and 1; behavioral pageview histories and raw custom histories are still suppressed.

The diagnostics object exposes diagnostics.autoExclusions so support can inspect what was collected, what was sent, whether exclusions caused request batching to split, and whether sent exclusions came from addExclusions(…​), request-level exclusions, or selector-based auto-collection.

Type: RecommendationItem & PromiseLike<RecommendationItem>.

You pass this handle to <FroomleReco reco={…​}>.

The same handle also exposes recommendation fields (for example reco.uri) once resolved.

Dynamic keys can always be read with reco.get('field_name').

One useCreateReco(…​) call represents one recommendation item, not a list of items.

If you want 4 recommendation cards, render 4 hook calls / 4 FroomleReco wrappers.

Compatible useCreateReco(…​) calls are batched into one backend request automatically.

Repeated filter keys merge into arrays on that grouped request. Example: two categories filters become "categories": ["Monde", "Sports"].

If you want the clearest render flow, read recommendation fields via useReco() inside a FroomleReco subtree.

Direct field access on the handle is supported, but those fields are empty until the reco resolves.

Type: { status, loading, error, response, list, items, entries }.

items is the public Froomle-item render list. Without benchmark config, and on treatment/Froomle benchmark branches, it contains returned Froomle recommendation items. On customer/control benchmark branches, it is empty so returned Froomle items are not rendered accidentally.

entries is the branch-aware render list for SDK-managed benchmark rendering. On customer/control branches it contains usable raw control items when you provide benchmark.controlItems; otherwise it is empty. On treatment/Froomle branches it contains returned Froomle items, mapped when configured.

list is the resolved public list object (or null while loading / on error). Its items follows the same branch-aware rule as the top-level items.

response is the full raw response object (or null while loading / on error), for inspection/debugging.

Use this when a parent component wants one list request and then maps the returned items into presentational children.

limit and list_size remain caller-configurable, for example from CMS settings.

exclusions, excludeItems, and autoExclusions can be passed on the hook request when this list must avoid items already visible elsewhere on the page. See Item IDs and Histories.

Use excludeItems when your React/CMS component already has the visible item objects in memory. It maps { items, getId, itemType/getItemType } to request-level exclusions without adding wrapper DOM or relying on a page scan. TypeScript infers the item shape from items.

Returned items can still be rendered inside FroomleReco for normal and treatment/Froomle rendering, so automatic impression and click_on_recommendation tracking continues to work.

useRecoList(…​) is list-based. It does not rely on the slot-batching behavior of useCreateReco(…​).

Repeated filter keys merge into arrays on the outgoing list request.

The React hook returns runtime objects. You do not import generated RecommendationList or Recommendations constructors from the root SDK package.

Type: { status, loading, error, response, list, items, entries, sortedCandidates, unmatchedCandidates }.

entries contains matched candidate/Froomle item pairs for rendering through FroomleReco entry={entry}.

sortedCandidates contains the original candidates in Froomle response order.

unmatchedCandidates contains candidates that were not returned by Froomle.

Use this for search-result reranking, curated-list reranking, or other cases where the application already owns the candidate set.

Candidate IDs can come from id, item_id, itemId, or getId(candidate, index).

Candidate item type defaults to article; set itemType / item_type or getItemType(candidate, index) for products or other item types.

Use getRank(candidate, index) or candidate rank for fixed-rank placements.

benchmark, exclusions, excludeItems, and autoExclusions follow the same request-shaping rules as useRecoList(…​).

Type: FroomleRecoEntry<TItem> | null.

entry.item is the item your component should render.

entry.branch is "control" or "treatment".

Render the entry through <FroomleReco entry={entry}> so the SDK can stamp recommendation attribution metadata.

Use this for one-card benchmark slots where the control branch should render one raw customer/CMS item.

Put the raw item adapter inside benchmark.controlItem.

exclusions, excludeItems, and autoExclusions follow the same request-shaping rules as useRecoList(…​).

Use useCreateReco(…​) instead when you only want standard returned Froomle recommendation content.

reco: recommendation handle from useCreateReco(…​), or a resolved RecommendationItem from useRecoList(…​).items.

entry: branch-aware entry from useRecoList(…​).entries, useSmartSort(…​).entries, or useRecoEntry(…​).

Pass either reco or entry, not both.

children: render content.

asChild: optional. When set, FroomleReco preserves a single child element as the rendered DOM root instead of inserting its default wrapper <div>. The child must be a real DOM element, or a component that forwards props and ref to its root DOM element.

Any extra props (id, className, data-*, …​) are forwarded to the rendered root element.

By default, renders a <div> wrapper and places children inside it.

With asChild, clones a single child element and uses that child as the rendered DOM root.

Resolves reco or reads entry metadata and writes recommendation metadata on the rendered root element: data-froomle-reco (when list is known), data-froomle-id, data-froomle-item-type, data-froomle-request-id, data-froomle-user-group.

Provides the reco value or entry.item through React context for useReco().

Use asChild when your layout expects the article/card root itself to remain the direct grid or flex child.

Use the default wrapper mode when you want the broadest compatibility and your child content is not a single stable DOM root.

Use asChild when the recommendation card/article root itself must remain the actual DOM node for layout, grid, or flex behavior.

asChild requires a single child element. That child must either be a real DOM element, or a component that forwards props and ref to its root DOM element. It is the preferred mode for layout-sensitive card rails.

If an existing card component does not forward props / ref, add a thin adapter that renders the real <article> / <div> root and passes the Froomle props to that root.

Returns the current recommendation from the nearest FroomleReco provider.

Throws if called outside a FroomleReco subtree.

id: item id to add to histories.

children: rendered content.

Renders children as-is in a fragment (no extra DOM wrapper).

Calls addHistories([id]) once per mount.

Does not fetch recommendations.

Does not inject recommendation attributes or clone children.

treatment branch: the SDK fills the node with the returned recommendation item

control branch with usable control content: the SDK keeps your control content and stamps runtime recommendation metadata onto that same node

control branch with missing or unusable control content: the SDK ignores returned Froomle items, keeps the node as rendered, and warns

if control content is missing or unusable, automatic recommendation attribution cannot activate unless the rendered item has stable identity and resolved request metadata

the placement has data-froomle-id

and it contains actual renderable content, not just an empty shell

data-froomle-benchmark-mode

data-froomle-benchmark-current-group

data-froomle-benchmark-control-group

data-froomle-benchmark-treatment-group

Froomle-managed Option A: fully supported, render returned items

customer/control vs Froomle: supported, but you own the branch rendering and must not render returned Froomle items on the customer/control branch unless you deliberately implement a custom fallback outside the SDK contract

control-aware control vs Froomle with SDK-managed replacement: not a native bare-JS DOM abstraction; use declarative DOM or React if you want the SDK to own that replacement behavior

you render your own customer content when the response user_group is the control group

you render returned Froomle items when the response user_group is the treatment group

you use the response user_group and request_id to make the render decision

for manual recommendation events, you send user_group for customer/control and omit it for treatment/Froomle

you use sendEvent(…​) for manual recommendation-related tracking when auto-tracking is not available

send a benchmark-aware request

inspect the response user_group

if the group is customer/control, render your customer content and ignore returned Froomle items by default

if the group is treatment/Froomle, render returned Froomle items, or empty if the response is empty

action_item

action_item_type

list_name

request_id

user_group for customer/control only

pass it explicitly in extras

let sendEvent(…​) infer it from a rendered source element

action_item

action_item_type

list_name

request_id

user_group when the event belongs to the customer/control branch

treatment/Froomle branch: returned Froomle items are available for rendering

customer/control branch: returned Froomle items are ignored for items and entries; provide benchmark.controlItems when React should render and auto-track customer/control cards

items: the branch-aware Froomle-item render list

entries: the branch-aware render items for SDK-managed benchmark rendering

entries always exists.

On the control branch, entries contains exactly the raw items from benchmark.controlItems.items whose getId(…​) result is usable. The SDK does not fill missing control entries with returned Froomle items.

On the treatment branch, entries contains returned Froomle recommendations, mapped through benchmark.mapRecommendationItem(…​) when you provide that mapper.

If the treatment response is empty, entries is empty.

items is empty on customer/control branches, even if the raw response contains returned Froomle items. Inspect response if you need to debug the raw network payload.

Raw control items and mapper functions are render-only inputs. They are not sent to the recommendation backend and do not affect request batching.

On the control branch, the entry item is benchmark.controlItem.item.

On the treatment branch, the entry item is the returned Froomle recommendation, mapped when benchmark.mapRecommendationItem(…​) is provided.

If the usable entry cannot be resolved, the hook returns null.

data-froomle-reco

data-froomle-id

data-froomle-item-type

data-froomle-request-id

data-froomle-user-group