placement()

Returns a fluent builder for presenting offers at a named placement. The id is attributed on the offers request; the options carry everything the presentation can be configured with.

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('streak_day_7', { useCase: 'rewardUsers' })  // named + options

PlacementOptions

One flat shape. The composition is derived from useCase, never selected separately:

interface PlacementOptions {
  useCase?: 'reduceChurn' | 'rewardUsers';   // default 'reduceChurn'
  headline?: string;
  subheadline?: string;
  statusIcon?: 'success' | 'none';           // default 'none'
  appearance?: AppearanceConfig;             // theme colors + reward-sheet overrides
}

Field Reference

Field	Type	Default	Description
`useCase`	`'reduceChurn' \| 'rewardUsers'`	`'reduceChurn'`	Why this placement presents, which is also what it renders. `'reduceChurn'` is the offer carousel, a save attempt at a moment the user is leaving. `'rewardUsers'` is the reward composition, for a moment the user just accomplished something: its own headline chrome around a paged carousel, claim-only, with no purchase ask anywhere in it. A use case with nothing to present isn’t an error: `show()` resolves `{ status: 'unavailable' }`, same as no eligible offers, and it never falls back to another use case’s offers or copy.
`headline`	`string`	Resolved copy	The sheet’s headline for this presentation, and the primary way to supply reward copy. Applies to both use cases. Beats the copy Encore resolved for your app, which in turn beats the copy shipped with the screen. Blank or whitespace-only falls through rather than blanking the sheet: omit the field instead of passing `''`.
`subheadline`	`string`	Resolved copy	Counterpart to `headline`: same precedence, same blank-falls-through rule.

headline and subheadline here set the copy. appearance.headline and appearance.subheadline set how that copy looks, or replace the element entirely. They are different fields with the same names, and they compose: a non-blank appearance.headline.text beats this one, and everything else about the slot is styling. See Advanced UI.

| statusIcon | 'success' \| 'none' | 'none' | Status icon above the headline. Nothing renders unless you explicitly ask for 'success', which draws a green-circle check. Only the 'rewardUsers' composition has a status block to put it in; 'reduceChurn' renders the carousel bare and ignores this. The default is 'none' deliberately, and it matches the native SDKs: a success check is a payment-status icon, and a reward sheet has not finished anything yet, it is still asking the user to choose a gift. Opt in only for the rare integration that wants one. | | appearance | AppearanceConfig | Encore’s palette | Theme colors injected as custom properties, plus per-element overrides for the reward sheet. The full contract is on Advanced UI. |

The useCase symbols match the native SDKs verbatim (iOS .reduceChurn / .rewardUsers, Android REDUCE_CHURN / REWARD_USERS), so a cross-platform integration reads one vocabulary. The values Encore sends and stores are separate frozen labels, which is what keeps a rename from ever changing the wire. You never type a wire value here: passing one is rejected as an unrecognized use case.

Usage end to end: Reduce Churn at the Paywall (useCase: 'reduceChurn', the default) · Post-Purchase Placements (useCase: 'rewardUsers').

PlacementBuilder

interface PlacementBuilder {
  useCase(useCase: 'reduceChurn' | 'rewardUsers'): PlacementBuilder;
  headline(text: string): PlacementBuilder;
  subheadline(text: string): PlacementBuilder;
  onNotGranted(callback: (reason: NotGrantedReason) => void): PlacementBuilder;
  onLoadingStateChange(callback: (isLoading: boolean) => void): PlacementBuilder;
  show(): Promise<ShowResult>;
}

useCase(useCase)

Sets which use case this placement serves. Equivalent to passing useCase in the options object, and composes with the other builder methods:

Encore.placement('streak_day_7').useCase('rewardUsers').show();

Default 'reduceChurn' if never called. See Reward Users for the full guide. A value other than 'reduceChurn' or 'rewardUsers' is an integration bug, not a normal decline: show() resolves dismissed with an INVALID_REQUEST error, and onNotGranted carries it. The builder has no onError equivalent, so use Encore.show()’s inline form if you need that callback too. See Errors.

headline(text) and subheadline(text)

Override the sheet’s copy for this presentation. Identical in effect to passing headline / subheadline in the options object, so pick whichever reads better at the call site:

// Builder form
Encore.placement('streak_day_7')
  .useCase('rewardUsers')
  .headline('Nice work, Sam!')
  .subheadline('That is your fifth week running')
  .show();

// Options form, exactly equivalent
Encore.placement('streak_day_7', {
  useCase: 'rewardUsers',
  headline: 'Nice work, Sam!',
  subheadline: 'That is your fifth week running',
}).show();

Same precedence as the options fields: this copy beats what Encore resolved for your app, which beats the copy shipped with the screen. Blank or whitespace-only falls through rather than blanking the sheet, so a builder step can never erase copy by passing an empty string. A later call wins, including over a value passed to placement() itself. Both steps match the native SDKs’ .headline(...) / .subheadline(...), so a cross-platform integration reads the same at every call site.

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.

show()

Presents the sheet with this placement’s options and resolves the ShowResult ('claimed' | 'dismissed' | 'unavailable'). It takes no arguments: everything a placement can be configured with lives in PlacementOptions, passed to placement() or set through the builder steps above. Never rejects.

Examples

Reduce churn at a named placement

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

const result = await Encore.placement('cancel_flow')
  .onLoadingStateChange((isLoading) => setSpinner(isLoading))
  .show();

if (result.status === 'claimed') {
  // The advertiser tab is already open. Keep result.transactionId.
  keepSubscriptionActive();
}

Reward users at a moment your app detected

For celebrating a moment your app already detected (a completed purchase, a streak, a milestone): the Reward Users use case. useCase: 'rewardUsers' renders its own chrome, and headline / subheadline are the top of its copy chain:

const placement = Encore.placement('streak_day_7', {
  useCase: 'rewardUsers',
  headline: 'Nice work, Sam!',
  subheadline: 'That is your fifth week running',
  appearance: { accentColor: '#0A6' },
});

const result = await placement.show();
if (result.status === 'unavailable') {
  // Either no eligible offers, or nothing to present for this use case.
}

show(): the ShowResult contract and the inline form.
The Claim Flow: what a claim does, and what its payload carries.
Reward Users: the useCase: 'rewardUsers' use case.
Updating to 2.x: moving off the nested header options.

iOS

Android

Web

Bridges

Signature

PlacementOptions

Field Reference

PlacementBuilder

useCase(useCase)

headline(text) and subheadline(text)

onNotGranted(callback)

onLoadingStateChange(callback)

show()

Examples

Reduce churn at a named placement

Reward users at a moment your app detected

​Signature

​PlacementOptions

​Field Reference

​PlacementBuilder

​useCase(useCase)

​headline(text) and subheadline(text)

​onNotGranted(callback)

​onLoadingStateChange(callback)

​show()

​Examples

​Reduce churn at a named placement

​Reward users at a moment your app detected

​Related

Signature

PlacementOptions

Field Reference

PlacementBuilder

useCase(useCase)

headline(text) and subheadline(text)

onNotGranted(callback)

onLoadingStateChange(callback)

show()

Examples

Reduce churn at a named placement

Reward users at a moment your app detected

Related