show()

Presents the offer sheet and resolves when the sheet closes after a claim or a dismissal, or at once when no offers are eligible. A 'rewardUsers' claim opens the advertiser at once; a 'reduceChurn' claim is saved for redeem(). See The Claim Flow.

When to use this

Call show() at the moment you want to present an offer: a cancel flow, a paywall, an onboarding step, a celebration screen. Most integrations present via the fluent placement(id).show() builder, which resolves the same ShowResult; Encore.show() is the inline one-call variant, and the only form that accepts an onError callback.

Signature

function show(
  options?: {
    onNotGranted?: (reason: NotGrantedReason) => void;  // fires on 'dismissed'; same reason a dismissed result carries
    onError?: (error: EncoreError) => void;             // narrower than "any error result"; see the parameter table
  },
  placementOptions?: PlacementOptions,  // per-presentation use case, copy, and appearance; see placement()
  placementId?: string                  // the placement key attributed on the offers request
): Promise<ShowResult>

placementOptions and placementId mirror the fluent placement(id, options).show() form. The builder’s own show() takes no arguments at all: onNotGranted is set once via placement(id).onNotGranted(), and the builder has no onError equivalent. Use the inline form shown here if you need that callback.

Parameters

Parameter	Type	Required	Description
`options.onNotGranted`	`(reason: NotGrantedReason) => void`	No	Fires whenever the result is `dismissed`, carrying the same `reason`.
`options.onError`	`(error: EncoreError) => void`	No	Narrower than “every error result”. Fires only when the flow never started (`INITIALIZATION_ERROR` from calling `show()` before `configure()`, or `INVALID_REQUEST` from an unrecognized `useCase`) or when it threw (`UNKNOWN_ERROR`). An error the flow itself returns resolves `dismissed` with `reason.type === 'error'` and fires only `onNotGranted`. Never fires on a normal decline. See Errors.
`placementOptions`	`PlacementOptions`	No	Per-presentation use case, copy, and appearance. Full field contract in `placement()`.
`placementId`	`string`	No	Placement key attributed on the offers request.

ShowResult

type ShowResult =
  | {                                                   // user claimed an offer (see The Claim Flow for when the advertiser opens)
      status: 'claimed';
      offerId: string;
      campaignId: string;
      advertiserName: string;
      transactionId?: string;
    }
  | { status: 'dismissed'; reason?: NotGrantedReason }  // user closed/declined, or an internal error
  | { status: 'unavailable' };                          // no eligible offers, a control-cohort ghost trigger, or nothing to present for the requested useCase

`status`	When	Next step
`claimed`	User claimed an offer, including when they then close a post-claim screen	Persist `transactionId` when present (it is absent if its write failed). On `'rewardUsers'` the SDK has already opened the advertiser; on `'reduceChurn'`, call `redeem()` when your own step is done
`dismissed`	User closed the modal, clicked outside, or declined the last offer; or the flow failed (`reason.type === 'error'`)	Respect the decline; `reason` says which
`unavailable`	No eligible offers, the user is in a measurement control cohort, or nothing to present for the requested `useCase`	Show your fallback; do not assume which

reason (a NotGrantedReason) is one of 'userClosedModal', 'userClickedOutside', 'userDeclinedLastOffer', 'noOffersAvailable', 'notConfigured', 'alreadyPresenting', or { type: 'error', error }. Two of those describe a sheet that never appeared rather than one the user dismissed:

Reason	Meaning
`'notConfigured'`	`show()` was called before `configure()`.
`'alreadyPresenting'`	Another `show()` was already in flight. The second call resolves immediately without starting a competing flow. A post-claim screen counts as in flight until the user closes it.

Both names match the native SDKs’ vocabulary for the same conditions.

The claimed payload

Field	Type	Description
`offerId`	`string`	Identifies the offer that was claimed.
`campaignId`	`string`	Identifies the campaign it belongs to. On web this is distinct from `offerId`, and both are reported.
`advertiserName`	`string`	The merchant’s display name, for a confirmation message you render yourself.
`transactionId`	`string` (optional)	The claim’s durable handle: the id Encore keys on. It is how a completion landing days later is traced back to this user and app, so persist it when present.

The payload mirrors the iOS and Android ClaimedOffer field for field, so a cross-platform integration reads one shape everywhere.

transactionId is optional by design. The transaction write can fail while the claim itself genuinely happened. The SDK logs a warning naming the attribution consequence rather than fabricating a placeholder, and the result still resolves claimed: a failed write must not retroactively turn a real claim into a decline.

show() never rejects. There is no crash path and no try/catch needed: a failure resolves as { status: 'dismissed', reason: { type: 'error', error } }, and calling show() before configure() resolves as { status: 'dismissed', reason: 'notConfigured' }.

The result does not report a conversion. claimed means the user accepted an offer; the advertiser completion happens later, asynchronously, via server-side postbacks. Verify completions and entitlements server-side, by user, with Encore’s server-side entitlements API, never from the client, and never from this result.

Examples

Present and branch

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

const result = await Encore.show(undefined, { useCase: 'rewardUsers' }, 'milestone_reached');

switch (result.status) {
  case 'claimed':
    // The SDK has opened the advertiser. Keep result.transactionId.
    // (On 'reduceChurn', call Encore.redeem() after your own step.)
    if (result.transactionId) await persistClaim(result.transactionId);
    break;
  case 'dismissed':
    // result.reason === 'userClosedModal' | 'userDeclinedLastOffer' | { type: 'error', ... }
    break;
  case 'unavailable':
    showFallback();
    break;
}

With a use case and copy

const result = await Encore.show(
  { onNotGranted: (reason) => console.debug('no claim', reason) },
  {
    useCase: 'rewardUsers',
    headline: 'Nice work, Sam!',
    subheadline: 'That is your fifth week running',
  },
  'streak_day_7'
);

Gotchas

unavailable is overloaded. It means “no eligible offers”, “measurement control cohort (ghost trigger)”, or “nothing to present for the requested useCase”; the SDK keeps them indistinguishable on purpose so incrementality experiments aren’t contaminated. Don’t branch app behavior on a suspected control assignment; just show your normal fallback.
An unrecognized useCase fails loudly, not silently. A typo or an unsupported value (not 'reduceChurn' or 'rewardUsers') resolves dismissed with an INVALID_REQUEST error, firing both onError and onNotGranted immediately, before any presentation attempt. That’s an integration bug, not a normal outcome: don’t confuse it with the silent unavailable a valid useCase with nothing to present produces. The values Encore sends over the wire are not accepted here; passing one is exactly this error. See Errors.
onError doesn’t catch every error result. It fires when the flow never started or threw, not when the flow returns an error. Branch on reason.type === 'error' if you want to catch both classes.
Your confirmation is yours to render. See The Claim Flow.
show() doesn’t need a click handler. The advertiser tab opens inside a tap on a button in the SDK’s own sheet.
Claim is not a conversion. Never grant access off a claimed result; verify entitlements server-side, by user (see the preceding warning).

The Claim Flow: what a claim does, and what its payload carries.
placement: present at a named placement, and the full options contract.
Errors: the error-as-value contract.
redeem(): hand off a saved Reduce Churn claim.
Updating to 2.x: moving a 1.x integration onto 2.x.

iOS

Android

Web

Bridges

When to use this

Signature

Parameters

ShowResult

The claimed payload

Examples

Present and branch

With a use case and copy

Gotchas

​When to use this

​Signature

​Parameters

​ShowResult

​The claimed payload

​Examples

​Present and branch

​With a use case and copy

​Gotchas

​Related

When to use this

Signature

Parameters

ShowResult

The claimed payload

Examples

Present and branch

With a use case and copy

Gotchas

Related