show()

Presents the offer carousel and resolves when the user claims an offer, dismisses the carousel, or no offers are eligible. Claiming opens the advertiser in a new tab inside the claim gesture; the SDK renders nothing after a claim, and the host owns the post-claim moment.

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. There is no second call to make afterward. 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; the advertiser tab was opened
      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	Nothing is required: the advertiser tab is already open. Persist `transactionId`, and render your own confirmation if you want one
`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 double-clicked claim button is the usual cause.

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 makes no conversion claim. claimed means the user accepted an offer and was handed off; 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();

switch (result.status) {
  case 'claimed':
    // The advertiser tab is already open, opened inside the claim gesture.
    // The SDK renders nothing after the claim; show your own confirmation here
    // if you want one, and keep result.transactionId for attribution.
    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.
Nothing renders after a claim. There is no built-in success screen; if that flow needs a confirmation moment, render it yourself when the result is claimed.
show() doesn’t need a click handler. The advertiser tab opens inside the user’s tap on Claim, within the SDK’s own sheet, so popup blockers have nothing to catch.
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.
Updating to 2.x: moving off the two-phase flow.

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