EntitlementScope - Encore SDK

Overview

EntitlementScope determines which set of entitlements isActive() inspects. It exists because Encore grants entitlements in two phases — a fast provisional grant for instant UX, followed by a backend-verified grant for correctness.

Definition

public enum EntitlementScope: Sendable {
    case verified
    case all
}

Two-phase entitlements (provisional vs verified)

When a user completes an offer, the entitlement doesn’t appear all at once:

Provisional — granted immediately so the user sees their reward without waiting. With the default UnlockMode.optimistic, this happens the moment the user returns from the offer flow. A provisional grant can later be revoked if the backend can’t verify the underlying transaction (e.g. the purchase was refunded, fraudulent, or never confirmed).
Verified — granted once the backend confirms the transaction (via the App Store Server Notification webhook). A verified grant is durable.

How each scope reads the two phases

Scope	What it inspects	Returns `true` for a provisional grant?
`.all` (default)	The merged set of everything currently granted to the user — provisional and verified. Broadest and fastest.	Yes
`.verified`	The provisional set or the verified set, triggering a smart refresh when a provisional grant nears expiry to pick up verification.	Yes

Both scopes surface provisional grants — neither is “verified-only.” The difference is that .verified actively refreshes against the backend’s verified set as provisional grants age, making it the right scope to drive toward a confirmed outcome. Use it when you want the SDK to chase verification; use .all for the cheapest “did the user just earn something” check.

Which scope should I gate on?

Reversible / instant UX — unlocking a screen, flipping a “premium” badge, hiding an upsell. Gate on .all. If a provisional grant is later revoked, you simply re-lock the UI; nothing was lost.
if await Encore.shared.isActive(.freeTrial(), in: .all) { showPremiumTab() // safe to reverse later }
Irreversible / expensive grants — minting durable credits, shipping a physical reward, writing a permanent server-side flag. Prefer .verified so the SDK is driving toward (and refreshing against) the backend’s confirmed state before you commit. For grants you can never take back, wait until verification actually lands rather than acting on the first provisional signal.
if await Encore.shared.isActive(.credit(), in: .verified) { grantDurableCredits() // only after verification }

When verification fails

A provisional grant that the backend can’t verify is revoked — the entitlement disappears from both scopes. To react in real time, subscribe with isActivePublisher(for:in:) and re-lock whatever you optimistically unlocked:

Encore.shared
    .isActivePublisher(for: .freeTrial, in: .all)
    .sink { isActive in
        isActive ? showPremiumTab() : hidePremiumTab()
    }
    .store(in: &cancellables)

If you only ever want to act on confirmed grants — never on provisional ones that might be revoked — configure the SDK with UnlockMode.strict, which withholds the grant until the advertiser postback verifies the conversion.

isActive() — query a scope once.
isActivePublisher() — observe a scope reactively.
configure() → Unlock mode — choose optimistic vs strict granting.

​Overview

​Definition

​Two-phase entitlements (provisional vs verified)

​How each scope reads the two phases

​Which scope should I gate on?

​When verification fails

​Related

Overview

Definition

Two-phase entitlements (provisional vs verified)

How each scope reads the two phases

Which scope should I gate on?

When verification fails

Related