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. No option picks the sheet: it follows from useCase and what Encore serves for it (Sheet Variants).

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: a save attempt at a moment the user is leaving, or a reward for a moment the user just accomplished something. The sheet is the served variant for it, or the SDK’s built-in sheet (Sheet Variants). 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, and on a served variant only where it shows your headline (Sheet Variants). Beats the copy Encore resolved for your app, which in turn beats the copy shipped with the screen. Encore never translates it, so pass it in the user’s language; the copy Encore resolves is translated for you (see Localization). 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.
`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 built-in `'rewardUsers'` sheets have a status block to put it in (Sheet Variants); the built-in `'reduceChurn'` carousel has none 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 built-in reward sheet. For a served variant, see Sheet Variants. The full contract is on Advanced UI.

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 on the built-in reward sheet, and everything else about the slot is styling. See 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>;
  redeem(): Promise<RedeemResult>;
}

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.

redeem()

Shows the redemption screen, whose button opens the advertiser, for the claim saved at this placement id; with no id, for the most recent claim. Same contract as Encore.redeem().

Examples

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. Its built-in sheet renders its own chrome, and headline / subheadline are the top of its copy chain:

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

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.
}

Reduce churn at a named placement

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

if (result.status === 'claimed') {
  // Saved for redeem(). Keep result.transactionId.
  keepSubscriptionActive();
  await Encore.placement('cancel_flow').redeem();
}

Contracts: show() · redeem().

show(): the ShowResult contract and the inline form.
redeem(): hand off a saved Reduce Churn claim.
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()

redeem()

Examples

Reward users at a moment your app detected

Reduce churn at a named placement

​Signature

​PlacementOptions

​Field Reference

​PlacementBuilder

​useCase(useCase)

​headline(text) and subheadline(text)

​onNotGranted(callback)

​onLoadingStateChange(callback)

​show()

​redeem()

​Examples

​Reward users at a moment your app detected

​Reduce churn at a named placement

​Related

Signature

PlacementOptions

Field Reference

PlacementBuilder

useCase(useCase)

headline(text) and subheadline(text)

onNotGranted(callback)

onLoadingStateChange(callback)

show()

redeem()

Examples

Reward users at a moment your app detected

Reduce churn at a named placement

Related