placement() - Encore SDK

Returns a fluent builder for presenting offers at a named placement. The id is recorded on the claimed transaction so placement(id).redeem() can later resolve exactly that claim; the options carry per-surface UI configuration.

Signature

function placement(
  idOrOptions?: string | PlacementOptions,
  options?: PlacementOptions
): PlacementBuilder

All argument combinations work:

Encore.placement()                                            // anonymous, defaults
Encore.placement('cancel_flow')                               // named placement
Encore.placement({ appearance: { accentColor: '#5671FF' } })  // options only
Encore.placement('post-purchase', { layout: 'thankYou' })     // named + options

PlacementOptions

Structure

PlacementOptions is a union of two layout variants sharing a common base:

// Common to every layout
interface BasePlacementOptions {
  appearance?: { backgroundColor?: string; textColor?: string; accentColor?: string };
  header?: { icon?: 'success' | 'none'; title?: string; subtitle?: string };
  display?: { appDisplayName?: string; trialPeriod?: string; logoUrl?: string };
  redemptionMode?: 'deferred' | 'immediate';  // per-placement; default from configure()
}

// The default offer sheet
interface ListPlacementOptions extends BasePlacementOptions {
  layout?: 'list';
}

// The post-purchase success composition
interface ThankYouPlacementOptions extends BasePlacementOptions {
  layout: 'thankYou';
  offerContext?: { title?: string; subtitle?: string };  // priming copy above the offers
  footer?: { text?: string };                            // trust line below the carousel
}

type PlacementOptions = ListPlacementOptions | ThankYouPlacementOptions;

Field Reference

Field	Type	Applies to	Description
`appearance`	`AppearanceConfig`	both layouts	`accentColor`, `backgroundColor`, `textColor`: CSS color strings.
`layout`	`'list' \| 'thankYou'`	-	Layout template; default `'list'` (the offer sheet). Unknown values fall back to `'list'` with a warning.
`redemptionMode`	`'deferred' \| 'immediate'`	both layouts	Per-placement override of the `configure()` default: the claim↔redeem coupling for this surface. See Redemption Modes.
`display`	`{ appDisplayName?, trialPeriod?, logoUrl? }`	both layouts (consumed by `'list'` · deferred)	Local override of the portal-managed host display values the deferred screens render; required to resolve (locally or remotely) in `'list'` · deferred. See Display Resolution.
`header.title` / `header.subtitle`	`string`	both layouts	Top heading block; an explicit value always wins. Defaults: in `'list'` · deferred, the composed “Get free for ” / “Claim a partner offer to start”; in `'list'` · immediate, the remote/generic copy; in `'thankYou'`, `title` defaults to “Payment Successful”, and a `receipt` passed to `show()` supersedes `subtitle`.
`header.icon`	`'success' \| 'none'`	`'thankYou'` only	Status check above the title; `'success'` (default) renders the green check, `'none'` hides it. Ignored by `'list'`.
`offerContext`	`{ title?, subtitle? }`	`'thankYou'` only	Priming copy above the offers. The `subtitle` is a fallback; the active offer’s campaign `perk` line supersedes it.
`footer.text`	`string`	`'thankYou'` only	Trust line below the carousel; omitted → not rendered.

In the 'thankYou' layout the blocks render top to bottom: check icon → header.title → status subtitle (the receipt passed to show(), else header.subtitle) → offerContext copy → the carousel → footer.text. Usage end to end: Reduce Paywall Churn ('list' · deferred) · Post-Purchase Placements ('thankYou').

PlacementBuilder

interface PlacementBuilder {
  show(options?: { receipt?: { amount: string; purpose?: string } }): Promise<ShowResult>;
  redeem(): Promise<RedeemResult>;
  onNotGranted(callback: (reason: NotGrantedReason) => void): PlacementBuilder;
  onLoadingStateChange(callback: (isLoading: boolean) => void): PlacementBuilder;
}

show(options?)

Presents the offer carousel with this placement’s options and resolves the bare ShowResult ('claimed' | 'dismissed' | 'unavailable'). On a thankYou-layout placement, pass the per-transaction receipt, rendered as the “You paid … for …” subtitle line (render-only, never sent to Encore’s servers).

redeem()

Redeems the claim recorded at this placement, phase 2 of the deferred flow. It never resolves another placement’s transaction (resolves { status: 'none' } if this placement has no pending claim). Contract: redeem().

onNotGranted(callback)

Fires when the sheet closes without a claim, carrying the dismissal reason (the same NotGrantedReason a dismissed result carries).

onLoadingStateChange(callback)

Fires true when the presentation starts loading and false when it settles; useful for spinners and disabling the triggering button. Callbacks are scoped to this builder instance; they don’t persist across calls.

Examples

Two-phase flow at a named placement

import Encore from '@encorekit/web-sdk';

// Phase 1: claim (deferred mode, no redirect yet)
const result = await Encore.placement('cancel_flow')
  .onLoadingStateChange((isLoading) => setSpinner(isLoading))
  .show();
if (result.status !== 'claimed') return; // 'dismissed' | 'unavailable'

// Phase 2: later, from a click handler
const outcome = await Encore.placement('cancel_flow').redeem();
// outcome.status === 'redeemed' on success

Post-purchase placement (thankYou layout)

const placement = Encore.placement('post-purchase', {
  layout: 'thankYou',
  redemptionMode: 'immediate', // one-tap claim on this surface only
  appearance: { accentColor: '#0A6' },
  footer: { text: 'Secured by Acme' },
});

const result = await placement.show({ receipt: { amount: '$9.99', purpose: 'Pro Plan' } });
// result.status === 'claimed' → the advertiser tab is already open (immediate mode)

show(): the ShowResult contract
redeem(): phase 2; placement-scoped resolution
Redemption Modes: the redemptionMode axis
Display Resolution: how display and header values resolve

​Signature

​PlacementOptions

​Structure

​Field Reference

​PlacementBuilder

​show(options?)

​redeem()

​onNotGranted(callback)

​onLoadingStateChange(callback)

​Examples

​Two-phase flow at a named placement

​Post-purchase placement (thankYou layout)

​Related