redeem()

Shows the SDK’s redemption screen for a claim the user already made, and opens the advertiser when the user taps that screen’s button. The SDK saved the claim when the user tapped Claim, then showed its primer, a screen that leads into your own offer. A 'reduceChurn' claim waits for this call; a 'rewardUsers' claim never does. When each one opens the advertiser: The Claim Flow.

When to use this

show() resolved claimed on a 'reduceChurn' placement, and your own step (a trial start, a completed cancel) is done.
A user comes back on a later page with a claim still waiting.

Signature

Encore.redeem(options?: RedeemOptions): Promise<RedeemResult>
Encore.placement(id).redeem(): Promise<RedeemResult>
Encore.getPendingTransaction(placementId?: string): Transaction | null

redeem() never rejects: a failure resolves dismissed with the error, and the claim stays saved for a later call.

RedeemOptions

interface RedeemOptions {
  placement?: string;   // redeem the claim made at this placement only
  host?: {              // override your product row on the redemption screen
    name?: string;
    status?: string;
    logoUrl?: string;
  };
}

Field	Type	Default	Description
`placement`	`string`	The most recent claim	The placement whose claim to redeem. It never takes another placement’s claim: with nothing saved there, `redeem()` resolves `unavailable`. `Encore.placement(id).redeem()` scopes the same way, and takes no `host`.
`host.name`	`string`	Your app’s name from Encore	The name on your own product’s row of the redemption screen. With no name from either, the screen has no row for your product.
`host.status`	`string`	`'Active'`	The status label on that row.
`host.logoUrl`	`string`	Your app’s logo from Encore	The logo on that row.

RedeemResult

type RedeemResult =
  | { status: 'redeemed' }                                  // the advertiser opened; the claim is used
  | { status: 'dismissed'; reason?: NotGrantedReason }      // closed without redeeming, or an error
  | { status: 'unavailable' };                              // no saved claim to redeem

`status`	When	Next step
`redeemed`	The user tapped the redemption screen’s button and the advertiser opened.	Nothing. The claim is used.
`dismissed`	The user closed the screen, or it failed (`reason.type === 'error'`).	The claim is still saved. Call `redeem()` again later if you want.
`unavailable`	No saved claim, including every `'rewardUsers'` claim.	Nothing to do.

reason is a NotGrantedReason.

getPendingTransaction()

Returns the claim redeem() would take, without showing anything, so you can render your own prompt before calling redeem(). Pass a placement id to look only at that placement. Returns null when nothing is saved, or before configure().

interface Transaction {
  id: string;                   // the same value as the claimed result's transactionId
  appAccountId: string;         // the account the claim is attributed to
  placementId?: string;         // the placement it was claimed at
  offer: {
    id: string;
    campaignId: string;
    advertiserUrl: string;      // the link template redeem() builds from; don't open it yourself
    advertiserName?: string;
    reward?: string;            // display copy, not an entitlement
    imageUrl?: string;
    logoUrl?: string;
    trackingParameters?: Record<string, string>;
  };
  useCase?: 'reduceChurn' | 'rewardUsers';
  status: 'claimed' | 'redeemed'; // getPendingTransaction() returns only 'claimed'
  createdAt: string;            // ISO 8601
  expiresAt: string;            // ISO 8601, when the claim stops being redeemable
  redeemedAt?: string;          // ISO 8601, set once redeemed
}

Fields you’ll use:

Field	Type	Description
`id`	`string`	The claim’s id, equal to `transactionId` on the claimed result.
`placementId`	`string`, optional	The placement the claim was made at, if it had an id.
`offer.advertiserName`	`string`, optional	The brand’s name, for a prompt you render yourself.
`offer.reward`	`string`, optional	The offer’s display copy. Not an entitlement.
`expiresAt`	`string`	When the claim stops being redeemable.

Examples

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

if (result.status === 'claimed') {
  await startTrial(); // your own step
  const redeemed = await Encore.placement('cancel_flow').redeem();
  if (redeemed.status === 'dismissed') {
    // The claim is still saved; offer it again later.
  }
}

On a later page:

if (Encore.getPendingTransaction('cancel_flow')) {
  showYourRedeemBanner(); // its button calls Encore.placement('cancel_flow').redeem()
}

Gotchas

A saved claim lasts 7 days. After expiresAt, redeem() resolves unavailable.
It belongs to this browser and origin, not the user. The claim is stored locally, so it survives a reload unless the browser blocks storage, but not a different browser, device, or origin. identify() does not clear it; call reset() at logout so the next user on the browser can’t redeem it.
The advertiser opens from the SDK’s button, not yours. redeem() shows a screen, and the tap on that screen opens the advertiser, so you can call redeem() from any moment. If the browser still blocks the new tab, redeem() resolves dismissed with an error and the claim stays saved.
claimed also means the user closed the primer. The claim is saved either way. If you call redeem() straight after show(), a user who closed the primer gets the redemption screen next.

The Claim Flow: when the advertiser opens for each use case.
show(): the claim that redeem() completes.
placement(): the placement id a claim is saved under.

iOS

Android

Web

Bridges

When to use this

Signature

RedeemOptions

RedeemResult

getPendingTransaction()

Examples

Gotchas

​When to use this

​Signature

​RedeemOptions

​RedeemResult

​getPendingTransaction()

​Examples

​Gotchas

​Related

When to use this

Signature

RedeemOptions

RedeemResult

getPendingTransaction()

Examples

Gotchas

Related