@encorekit/web-sdk 2.2.1 → 2.4.0

package/README.md

@@ -231,9 +231,30 @@ react to a claim or a dismissal.
 | Status | Meaning |
 |:-------|:--------|
 | `{ status: 'claimed', offerId, campaignId, advertiserName, transactionId? }` | The user claimed an offer. The advertiser opened in a new tab inside the tap gesture and the SDK renders nothing afterwards — the host owns that moment, so render your own confirmation if you want one. The payload mirrors iOS's and Android's `ClaimedOffer` field-for-field. **`transactionId` carries the attribution** — it is how a completion that lands days later is traced back to this user and app, and it is the argument `didGrant()` and `waitForVerification()` take. It is optional because the transaction write can fail while the claim genuinely happened; the SDK logs a warning when that occurs. |
-| `{ status: 'dismissed', reason? }` | The sheet closed without a claim. Failures land here too, carrying `reason.error`. |
+| `{ status: 'dismissed', reason? }` | The sheet closed without a claim. Failures land here too, carrying `reason.error`. `reason: 'alreadyCompleted'` means the server refused the claim because this user already completed the offer; see below. |
 | `{ status: 'unavailable' }` | Nothing was presented — no eligible offers, or the surface did not resolve. |
 
+#### When the user already completed the offer
+
+If the user taps Claim on an offer they already completed, the server refuses the
+claim. `show()` resolves:
+
+```typescript
+{ status: 'dismissed', reason: 'alreadyCompleted' }
+```
+
+It is an expected outcome, not a failure. Nothing is granted, nothing is sent to
+error tracking, and the advertiser tab opened for the claim is closed again.
+`onNotGranted` receives the same `'alreadyCompleted'`, and `presentOffer()`
+resolves `{ granted: false, reason: 'alreadyCompleted' }`. It comes from the
+server's `offerAlreadyCompleted` code. The app-wide trial limit
+(`userAlreadyConverted`) refuses every offer, so it stays an `{ type: 'error' }`
+reason, as does a refusal from a backend that sends no code.
+
+For the rest of the session (until the user id changes), the SDK leaves that
+campaign out of the session's offer list, so it is not offered again. A claim
+that started but has not completed does not hide the offer.
+
 `claimed` deliberately makes no assertion about advertiser conversion: that is
 asynchronous and server-authoritative. Verify entitlements and conversions
 server-side, by user, never from the client.
@@ -375,6 +396,50 @@ 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.
 
+## Language
+
+Encore's copy and offers follow one language per session. By default that is the
+browser's `Accept-Language`. To choose one yourself, call `Encore.setLanguage()`
+after `configure()` with a BCP 47 language tag, such as `'fr'` or `'pt-BR'`:
+
+```typescript
+Encore.configure({ apiKey: 'your-api-key-here' });
+Encore.setLanguage('pt-BR');
+```
+
+The same language goes on the config request and the offers request, so the
+sheet's copy and its offers are always in one language, and analytics events carry
+the locale Encore served. Only languages Encore has enabled for your app are
+served; any other language falls back to `Accept-Language`, then your app's
+default. Any case is accepted and stored in BCP 47 case (`'PT-br'` becomes
+`'pt-BR'`), and a deprecated code is replaced (`'iw'` becomes `'he'`). A value that is not a well-formed tag (`'english'`, `'pt_BR'`,
+`' fr'`) is ignored with one console warning, never thrown, and the current
+language stays.
+
+The choice is kept on this device until you clear it: a later `configure()`, a
+reload, `reset()` and `identify()` with another user keep it. Changing it drops the cached copy and offers, asks
+for the copy again at once, then fetches the offers again in the new language.
+
+To go back to the browser's language, call `Encore.clearLanguage()`. It forgets
+the choice on this device, drops the cached copy and offers, and asks for the copy
+again at once. It does nothing when no language was set.
+
+`UserAttributes.language` is deprecated and will be removed in the next major
+version. Until then a `language` passed to `setUserAttributes()` or `identify()`
+is forwarded to `setLanguage()`, with one console warning per page load, and is not
+kept or sent as an attribute. It then behaves like `setLanguage()`, so `reset()`
+keeps it too. There, and only there, a locale identifier reads as its tag
+(`'pt_BR'`, `'de_DE@currency=EUR'`), as the server accepted it. A language an earlier SDK version stored that way is moved into the
+device setting once, on the first `configure()`.
+
+The sheet carries `lang` and `dir` for the served language (right to left for
+the same 18 languages as the iOS and Android SDKs, among them Arabic, Hebrew,
+Persian, Urdu, Pashto, Sindhi, Uyghur, Yiddish and Sorani Kurdish) and formats
+dates and numbers in it. Words the
+SDK says itself are served translated where Encore has an approved translation;
+any other string stays in English. A headline or subheadline you pass at runtime
+is shown exactly as you wrote it.
+
 ## Deferred redemption
 
 A claim and the advertiser handoff are two moments, and a placement decides