placement()

Creates a placement builder for presenting offers. This is the only way to present in 2.0, and it matches the builder across every Encore SDK.

Signature

placement(placementId: string): PlacementBuilder

interface PlacementBuilder {
  useCase(useCase: UseCase): PlacementBuilder;
  headline(text: string): PlacementBuilder;
  subheadline(text: string): PlacementBuilder;
  show(): Promise<PresentationResult>;
}

Each option returns a new builder, so a builder can be reused or shared without one call site mutating the configuration of another.

Parameters

Name	Type	Description
`placementId`	string	The placement identifier configured in the Encore Dashboard

show()

const result = await Encore.placement('cancel_flow').show();

show() never rejects. Every failure, including “nothing was presented”, is a value on the returned PresentationResult:

const result = await Encore.placement('cancel_flow').show();

if (result.status === 'presented' && (result.claim !== null || result.publisher === 'purchased')) {
  grantAccess();
} else {
  proceedWithCancellation();
}

Pass a purchase controller to configure() if your flows include an in-app purchase. Without one the SDK never attempts a purchase, and every presentation records publisher: 'not_attempted'.

Use cases

useCase() selects which Encore surface the placement presents. It defaults to UseCase.reduceChurn.

import Encore, { UseCase } from '@encorekit/react-native';

await Encore.placement('milestone_reached')
  .useCase(UseCase.rewardUsers)
  .headline("That's three days in a row staying informed 🔥")
  .subheadline("Here's a little thank you from us")
  .show();

Case	Wire value	Surface
`UseCase.reduceChurn`	`churn-intervention`	Second-chance monetization after a paywall decline. The default
`UseCase.rewardUsers`	`post-action-reward`	A brand-funded reward at a moment the user just accomplished something. Claim-only; never presents IAP

The keys name the capability; the values are the sdui_use_case labels the backend stores. They are pinned explicitly rather than derived from the keys, so renaming a key can never silently change what goes over the wire. UseCase is declaration-merged, so it is both the value you reach through and the type you annotate with.

A use case with no enabled variant resolves not_presented with reason.type === 'use_case_unavailable' rather than falling back to the churn-intervention sheet. An in-app-purchase screen at a moment the user was meant to be rewarded is worse than presenting nothing.

Copy overrides

headline() and subheadline() override the sheet’s copy for one presentation, on every use case. The native side writes the value into the variable the active template reads. Priority order, first one set wins: this value, then the copy Encore resolved for your app, then the shipped template default. A blank string is ignored, so the chain falls through rather than rendering an empty line. You pass the finished string, so localization, pluralization, wording, and emoji stay yours.

PresentationResult, what show() resolves to.
PurchaseController, the purchase path a presented offer runs through.
Reward Users and Reduce Churn for what each surface is for.

iOS

Android

Web

Bridges

Signature

Parameters

show()

Use cases

Copy overrides

​Signature

​Parameters

​show()

​Use cases

​Copy overrides

​Related

Signature

Parameters

show()

Use cases

Copy overrides

Related