@encorekit/web-sdk 2.0.4 → 2.0.6

package/README.md

@@ -27,19 +27,20 @@ Or via CDN:
 
 ## Upgrading to 2.0.2
 
-2.0.2 removes the deferred redemption flow and the layout system. Claiming an
-offer now always redirects to the advertiser immediately, and the composition is
-derived from the placement's use case.
+2.0.2 removed the deferred redemption flow and the layout system. The layout
+removal stands. **The deferred-flow removal was a regression and is undone in
+2.0.5** — see *Deferred redemption* below; if you are on 2.0.2–2.0.4 and never set
+`redemptionMode`, that is the section that concerns you.
 
 | Removed | Replacement |
 |:--------|:------------|
-| `redemptionMode` — on `configure()` and on placement options | None. Redirect-on-claim is the only flow. |
-| `Encore.redeem()`, `placement(id).redeem()`, `getPendingTransaction()`, `RedeemOptions`, `RedeemResult` | None. There is no pending transaction to redeem. |
+| `redemptionMode` — on `configure()` and on placement options | None, and none is coming. **2.0.5 restores the deferred flow itself** (see below), but what a claim does with the handoff is data on the variant, never a publisher option. |
+| `Encore.redeem()`, `placement(id).redeem()`, `getPendingTransaction()`, `RedeemOptions`, `RedeemResult` | **Restored in 2.0.5** — see *Deferred redemption* below. |
 | `layout: 'list' \| 'thankYou'` | `useCase` — `'reduceChurn'` renders the offer carousel, `'rewardUsers'` the reward composition. |
 | `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` | None. Render any other copy yourself. |
-| `display` / `HostDisplay` | None. It only ever fed the deferred-flow screens; on the immediate path it resolved to nothing. |
+| `display` / `HostDisplay` | None as a publisher option. The deferred screens restored in 2.0.5 resolve the host's name, trial period and icon from remote config instead, and degrade when they are unset. |
 | `.headline()` / `.subheadline()` builder steps | The flat `headline` / `subheadline` options. `.useCase()` stays. |
 | `'churn-intervention'` / `'post-action-reward'` | `'reduceChurn'` / `'rewardUsers'` — a rename of the TypeScript symbols only; the values sent over HTTP are unchanged. |
 
@@ -64,10 +65,14 @@ Encore.identify('user-123', {
 // Present a placement — defaults to the 'reduceChurn' use case
 const result = await Encore.show();
 if (result.status === 'claimed') {
-  // The user claimed an offer and the advertiser opened in a new tab.
-  // Keep result.transactionId — it is how the conversion is traced back to
-  // this user and app, and what waitForVerification() / didGrant() take.
-  // The SDK renders nothing after a claim — show your own confirmation here.
+  // The user claimed an offer. Keep result.transactionId — it is how the
+  // conversion is traced back to this user and app, and what
+  // waitForVerification() / didGrant() take.
+  //
+  // WHEN the advertiser opens depends on the variant's claim behaviour:
+  // 'reduceChurn' defaults to deferred, so the claim is banked and you call
+  // Encore.redeem() after your own flow. 'rewardUsers' defaults to immediate,
+  // so the advertiser already opened in a new tab.
 } else {
   // 'dismissed' (with an optional reason) or 'unavailable' — nothing was claimed.
   console.log('Nothing claimed:', result);
@@ -344,6 +349,60 @@ and it has several causes — so do not read it as "not enabled":
 See [the use-case serving model](https://github.com/EncoreKit/web-sdk/blob/main/docs/architecture/use-case-serving.md)
 for the full design note.
 
+## Deferred redemption
+
+A claim and the advertiser handoff are two moments, and a placement decides
+whether they are the same moment. That is `claimBehavior`, and it is **data on the
+variant** — Encore configures it per placement. There is no publisher option for
+it, deliberately: `redemptionMode` was one until 2.0.2, and its default flipping
+underneath integrations that never set it is exactly the failure this replaces.
+
+| Behaviour | On claim | `redeem()` | Survives a reload |
+|:----------|:---------|:-----------|:------------------|
+| `immediate` | Redirects to the advertiser inside the tap gesture. Nothing is stored. | Resolves `unavailable` | n/a |
+| `deferred` | Banks the claim and shows a primer. No redirect. | Presents the claim, redirects on the CTA, marks it redeemed | Yes |
+| `deferredWhileAlive` | Holds the claim in memory for this page. | Presents it while the page lives | No, by design |
+
+Defaults: **`reduceChurn` is `deferred`**, **`rewardUsers` is `immediate`**.
+
+```typescript
+// A deferred placement: show() resolves once the user passes the primer.
+// Nothing has opened yet — the claim is banked.
+const result = await Encore.placement('cancel_flow').show();
+
+// ...your own cancellation flow runs, possibly on a later page load...
+
+// Phase 2. Presents the claim and sends the user to the advertiser.
+const redemption = await Encore.placement('cancel_flow').redeem();
+if (redemption.status === 'redeemed') {
+  // The advertiser opened inside the CTA gesture and the claim is consumed.
+}
+```
+
+`redeem()` never rejects. It resolves:
+
+| Result | Meaning |
+|:-------|:--------|
+| `{ status: 'redeemed' }` | The handoff happened and the claim is consumed. |
+| `{ status: 'dismissed', reason? }` | The user closed the sheet, or an internal failure occurred (`reason.type === 'error'`). The claim is untouched, so retrying later is safe. |
+| `{ status: 'unavailable' }` | Nothing is pending. Strictly that — never an error in disguise. Every `immediate` placement always resolves this. |
+
+To render your own CTA instead of the SDK's, read the pending claim first:
+
+```typescript
+const pending = Encore.getPendingTransaction('cancel_flow'); // or () for the latest
+if (pending) showMyOwnBanner(pending.offer.advertiserName);
+```
+
+Scoping is strict: `placement(id).redeem()` and `getPendingTransaction(id)` resolve
+only the claim made at that placement and never cross to another's. The bare forms
+take the most recent claim for the user.
+
+> **The provisional grant follows the handoff, not the claim.** On a deferred
+> placement it is sent when `redeem()` performs the redirect, not when the user
+> taps Claim. Verified access is server-side either way — check it on your backend,
+> never from the client.
+
 ## Browser Support
 
 - Chrome/Edge (last 2 versions)
@@ -351,22 +410,22 @@ for the full design note.
 - Safari (last 2 versions)
 - iOS Safari 15+
 
-## iOS HTML Tag Integration
+## iOS WebView Integration
 
-The **simplest possible** integration - just build a URL and open it in a WKWebView. No SDK, no dependencies, no complexity.
+The **simplest possible** integration: build a URL and open it in a `WKWebView`.
+No SDK, no dependencies, nothing to implement. Encore hosts the offer page and
+its query string is the entire configuration surface.
 
-### Quick Start (3 Lines of Code!)
+### Quick Start
 
 ```swift
-// 1. Build URL
-let url = EncoreURL.build(apiKey: "your_key", userId: "user_123")!
+// 1. Build the URL (copy EncoreURLBuilder.swift into your project)
+guard let url = EncoreURL.build(apiKey: "pk_live_...", userId: "user_123") else { return }
 
-// 2. Create WebView and load it
+// 2. Create a webview and load it
 let webView = WKWebView(frame: view.bounds)
 view.addSubview(webView)
 webView.load(URLRequest(url: url))
-
-// That's it! 🎉
 ```
 
 ### Complete Example
@@ -375,24 +434,26 @@ webView.load(URLRequest(url: url))
 import UIKit
 import WebKit
 
-// Copy EncoreURLBuilder.swift to your project (one file!)
 func showEncoreOffer() {
-    let url = EncoreURL.build(
+    guard let url = EncoreURL.build(
         apiKey: "pk_live_...",
         userId: currentUser.id,
         attributes: [
-            "email": currentUser.email,
-            "subscriptionTier": currentUser.tier
+            "subscriptionTier": currentUser.tier,
+            "countryCode": currentUser.countryCode
         ]
-    )!
-    
+    ) else { return }
+
     let webView = WKWebView(frame: view.bounds)
-    webView.backgroundColor = .clear
     view.addSubview(webView)
     webView.load(URLRequest(url: url))
 }
 ```
 
+Targeting attributes are coarse by design. `email`, `phoneNumber`, names,
+`dateOfBirth`, `gender` and precise location are refused, because a query string
+is written to webview history and to hosting access logs.
+
 ### SwiftUI Version
 
 ```swift
@@ -410,30 +471,41 @@ struct MyView: View {
 
 ### What You Get
 
-- ✅ **Zero dependencies** - Just one Swift file
-- ✅ **3 lines of code** - Build URL, create WebView, load
-- ✅ **Auto-initialization** - Embed handles everything
-- ✅ **Full features** - Offers, entitlements, tracking
-- ✅ **Works everywhere** - UIKit, SwiftUI, any iOS app
+- **Zero dependencies**: one Swift file to copy
+- **Three lines of code**: build URL, create webview, load
+- **Works everywhere**: UIKit, SwiftUI, and any other platform with a webview
+- **Nothing to maintain**: the page is hosted, so the contract is the URL
 
-### Documentation
-- **[EncoreURLBuilder.swift](examples/ios-webview/EncoreURLBuilder.swift)** - URL builder (copy this!)
-- **[SimpleExample.swift](examples/ios-webview/SimpleExample.swift)** - Working examples
+### Knowing when a user earned something
 
-### Advanced: With Callbacks
+The page does not call your app back. There is no native bridge on any platform.
+Your backend asks Encore instead:
 
-Need callbacks when offers complete? Use the [full bridge integration](examples/ios-webview/README.md).
+```
+GET https://api.encorekit.com/encore/publisher/sdk/v1/entitlements/server?userId=<userId>
+```
+
+authenticated with your API key plus an HMAC signature you compute with your
+API secret. The secret itself is never sent.
+
+### Documentation
+
+- **[EncoreURLBuilder.swift](examples/ios-webview/EncoreURLBuilder.swift)** - URL builder (copy this!)
+- **[SimpleExample.swift](examples/ios-webview/SimpleExample.swift)** - UIKit usage
+- **[SimpleEncoreView.swift](examples/ios-webview/SimpleEncoreView.swift)** - SwiftUI wrapper
+- **[examples/ios-webview/README.md](examples/ios-webview/README.md)** - full parameter reference
 
 ### When to Use
 
-| Feature | Simple (URL) | [Native iOS SDK](https://github.com/encore/swift-sdk) |
-|---------|-------------|------------|
+| Feature | Hosted page (URL) | [Native iOS SDK](https://github.com/EncoreKit/swift) |
+|---------|-------------------|------------|
 | Integration | 3 lines | ~50 lines |
 | Dependencies | None | Requires SPM |
-| Callbacks | No | Yes |
-| Works? | ✅ | ✅ |
+| Native entitlement callbacks | No, poll from your backend | Yes |
+| StoreKit and offline handling | No | Yes |
 
-**Use simple integration** for 99% of cases. Only need the full bridge if you require granular callbacks.
+Use the hosted page when you want the smallest integration. Use the native SDK
+when you need entitlement callbacks inside the app.
 
 ## Documentation