Updating to 2.x

Overview

2.x reduces the public API to a single dimension: why a placement presents. The composition, the copy slots, and the claim flow all follow from that, or are gone.

Read the change, not the version number. The current 2.x release carries a full public-API rewrite. Methods, options, and result shapes all changed, and the 1.x surface is removed rather than deprecated. Treat this upgrade the way you would treat a major version bump, whatever the number suggests.

Coming from 1.x, four things change:

The use case decides when the advertiser opens. redemptionMode is removed. A 'reduceChurn' claim is saved for redeem(), as 1.x’s default was; a 'rewardUsers' claim opens the advertiser at once.
PlacementOptions is one flat shape. headline and subheadline replace the nested header object.
layout is gone, along with the 'thankYou' composition and everything that dressed it. A new useCase option names the use case, which decides the sheet.
The builder’s show() takes no arguments, and a claimed result now carries offerId, campaignId, advertiserName, and transactionId.

Step 1: Update the package

Install the current 2.x release:

npm install @encorekit/web-sdk@latest

Use 2.0.6 or later. 2.0.0 still carries the 1.x API, and 2.0.1 to 2.0.4 have no redeem(). Check what you resolved to with npm view @encorekit/web-sdk version before pinning.

2.x removes the 1.x surface outright rather than deprecating it, so in TypeScript most call sites that need attention fail to typecheck. Run your type checker: the errors are your migration worklist, and each one maps to a step below. The Warning in Step 2 lists the changes a type checker can’t see. The removed API table maps every 1.x symbol to its replacement. JavaScript hosts get no such worklist. Work through the steps in order instead, and pay particular attention to Step 2.

Step 2: Remove `redemptionMode`

redemptionMode is removed from configure() and from placement options, and getConfiguration() no longer returns it. The use case now decides when the advertiser opens (The Claim Flow):

`useCase`	On claim	Your `redeem()` call
`'reduceChurn'` (default)	Saved, and the SDK shows its primer	Keep it. It shows the redemption screen, which opens the advertiser.
`'rewardUsers'`	The advertiser opens at once	Delete it. On that placement it resolves `unavailable`.

// 2.x, reduceChurn: the same two steps as 1.x's default
const result = await Encore.placement('cancel_flow').show();
if (result.status === 'claimed') {
  await runYourConversion();
  await Encore.placement('cancel_flow').redeem();
}

Three integrations change with no runtime error:

One that set redemptionMode: 'immediate' on configure() or a 1.x 'list' placement (now 'reduceChurn'): its claims are now saved, and nothing opens the advertiser until redeem() runs. Add the call after your own step.
One built on 2.0.1 to 2.0.4, which have no redeem(): the same applies. Add the call.
A 1.x 'thankYou' placement on the default deferred mode, now 'rewardUsers': its claims open the advertiser at once, and its redeem() resolves unavailable. Delete the call.

redeem(), placement(id).redeem() and getPendingTransaction() stay, with two changes: RedeemResult returns 'unavailable' where 1.x returned 'none' or 'expired', and a Transaction carries useCase in place of claimLayout. A branch on 'none' or 'expired' never matches on 2.x. Contract: redeem().

Step 3: Flatten the placement options

The nested header object is replaced by flat fields:

// 1.x
Encore.placement('milestone_reached', {
  header: { title: 'Nice work, Sam!', subtitle: 'That is your fifth week running' },
}).show();

// 2.x
Encore.placement('milestone_reached', {
  headline: 'Nice work, Sam!',
  subheadline: 'That is your fifth week running',
}).show();

The precedence is unchanged: a per-call override beats the copy Encore resolved for your app, which beats the copy shipped with the screen, each field resolving on its own, and a blank value still falls through rather than clearing the line. .onNotGranted() and .onLoadingStateChange() on the builder are unchanged.

Step 4: Replace the retired compositions

layout is removed. The new useCase option names the use case, which decides the sheet, and it defaults to 'reduceChurn', whose built-in sheet is the offer carousel your 1.x 'list' placements already showed. A placement that named no layout needs no change here. Drop the layout: 'list' option if you passed it explicitly; the default covers you. The 'thankYou' composition is retired, and with it the payment-status sheet a post-purchase surface could compose. If you presented one, the closest equivalent is the 'rewardUsers' composition:

// 1.x
Encore.placement('post_purchase', {
  layout: 'thankYou',
  redemptionMode: 'immediate',
  header: { icon: 'success', title: 'Payment Successful' },
  offerContext: { title: 'A little thank you, just for you.' },
  footer: { text: 'Secured by Acme' },
}).show({ receipt: { amount: '$9.99', purpose: 'Pro Plan' } });

// 2.x
Encore.placement('post_purchase', {
  useCase: 'rewardUsers',
  headline: 'Payment Successful',
  subheadline: 'You paid $9.99 for Pro Plan', // pre-format it yourself
}).show();

Four options stop working as they did in 1.x:

Removed	What to do instead
`receipt` (the composed “You paid for ” line)	Pre-format the sentence yourself and pass it as `subheadline`.
`offerContext` (the two-line lead-in that precedes the offers)	The reward composition suppresses that header. Put the copy in `headline` / `subheadline`, or render it in your own page.
`footer` (the trust line below the carousel)	Render it in your own page.
`display` / `HostDisplay`	Nothing to pass: the redemption screen and the primer read your app’s name, logo and trial length from your app’s settings in Encore. The `host` option on `redeem()` still overrides the name and logo.

Because display is gone, so is the display pre-flight that could resolve a deferred show() to dismissed with a CONFIGURATION_ERROR before anything rendered.

Step 5: Read the new claim result

A claimed result is no longer bare:

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

if (result.status === 'claimed') {
  // 2.x adds these four fields
  const { offerId, campaignId, advertiserName, transactionId } = result;
  await persistClaim({ transactionId, advertiserName });
}

transactionId is what carries attribution: it is how a completion landing days later is traced back to this user and app. Persist it when it is present. In 1.x the claimed result was bare, and the id lived only on the transaction record from getPendingTransaction(). It is optional because the transaction write can fail while the claim genuinely happened, in which case the SDK logs a warning rather than fabricating a placeholder id, and the result still resolves claimed. dismissed and unavailable are unchanged. show() still never rejects.

New in 2.x: reward a user, not just save one

1.x could only intervene when a user was about to leave. 2.x adds a second use case for the opposite moment, a user who just accomplished something:

await Encore.placement('streak_day_7', {
  useCase: 'rewardUsers',
  headline: 'Nice work, Sam!',
}).show();

Nothing forces you to adopt it. Leaving useCase unset keeps every placement on 'reduceChurn', which is the behavior your 1.x integration already had. See Post-Purchase Placements for the full walkthrough.

The values you type ('reduceChurn', 'rewardUsers') match the native SDKs. The values Encore sends and stores over the wire are separate frozen labels, so anything you have built on the use_case analytics property is unaffected.

Removed APIs at a glance

1.x	2.x
`redemptionMode`, on `configure()` and on placement options	Removed. The use case decides when the advertiser opens.
`RedeemResult` statuses `'none'` and `'expired'`	`'unavailable'`.
`Transaction.claimLayout`	`Transaction.useCase`.
`layout: 'list' \| 'thankYou'`	`useCase`: `'reduceChurn'` or `'rewardUsers'`.
`header.title`, `header.subtitle`	`headline`, `subheadline` on `PlacementOptions`.
`header.icon`	`statusIcon` on `PlacementOptions`. The default flips from `'success'` to `'none'`, so the check no longer renders unless you ask for it.
`offerContext`, `footer`, `receipt`, `ShowOptions`, `Receipt`	Removed. Render any other copy yourself.
`display`, `HostDisplay`	Removed. Your app’s settings in Encore supply the name, logo and trial length.
`show(options)` on the placement builder	`show()`, which takes no arguments.

Verify the migration

Your project type-checks, or (in JavaScript) no call site still references redemptionMode, layout, header, offerContext, footer, receipt, or display.
A 'reduceChurn' claim reaches the advertiser through your redeem() call, and a 'rewardUsers' claim opens it at once.
Your claimed branch reads and persists transactionId.
Your analytics still report against the same use-case values they always did, because the wire did not change.

The Claim Flow: the single-step flow in full.
placement(): the current PlacementOptions contract.
show(): the current ShowResult contract.
configure(): the current EncoreConfig contract.

iOS

Android

Web

Bridges

Updating to 2.x

Overview

Step 1: Update the package

Step 2: Remove `redemptionMode`

Step 3: Flatten the placement options

Step 4: Replace the retired compositions

Step 5: Read the new claim result

New in 2.x: reward a user, not just save one

Removed APIs at a glance

Verify the migration

​Overview

​Step 1: Update the package

​Step 2: Remove redemptionMode

​Step 3: Flatten the placement options

​Step 4: Replace the retired compositions

​Step 5: Read the new claim result

​New in 2.x: reward a user, not just save one

​Removed APIs at a glance

​Verify the migration

​Related

Overview

Step 1: Update the package

Step 2: Remove `redemptionMode`

Step 3: Flatten the placement options

Step 4: Replace the retired compositions

Step 5: Read the new claim result

New in 2.x: reward a user, not just save one

Removed APIs at a glance

Verify the migration

Related