How client-side content locking works
Understand how sesamy-js finds an article, checks access, unlocks its content, and records a read in your browser integration.
Default component access and legacy opt-out
Updated sesamy-js and components use the content API for non-public access decisions and grants by default. This includes embed mode: the container authorizes display before exposing the existing DOM nodes, without copying the article or replacing ads and iframes. Successful policy-based embed grants now count toward applicable reader limits. Checks never count, and subscriptions and URL-delivered signed grants retain their bypasses.
The paywall component checks content.hasAccess() and renders the selected server paywall from that decision. Its child renderers do not make a second entitlement-based visibility decision. Strategy resolution stays on the server. Rendering/layout requests may still fetch settings when no selected policy is available.
To keep an integration on the prior behavior, set the top-level option before initialization:
await sesamy.init({
clientId: 'acme',
vendorId: 'acme',
legacyContentAccess: true,
// Existing integration configuration
});The opt-out preserves legacy client checks and local display without new embed read registration. An older sesamy-js bundle without the new metadata marker also keeps the legacy component flow. Deploy the API first, then the SDK/sesamy-js release, then the component release. This is a minor behavior change, not merely a refactor: readers can start reaching limits that were previously not consumed.
When no explicit article policy exists, paywall discovery is enabled by default. It prefers a unique resource-ID/URL match or a unique paywall within the article; ambiguous or unrelated matches are ignored. A discovered <sesamy-paywall> supplies its paywall attribute, or its settings-url when it has none. A settings-url counts only when it is a Sesamy paywall ID, strategy ID or Sesamy paywall URL. A URL to the publisher's own paywall document is ignored for the access check, though the component still renders it. Explicit paywall-url and content configuration win. Set enablePaywallSettingsUrlFallback: false on the matching content entry to disable discovery alone. legacyContentAccess: true restores the previous default (discovery disabled unless explicitly enabled).
A fixed subscription paywall remains a fixed reference. Discovering its settings URL does not automatically substitute a strategy: configure the strategy reference for the desired three-read flow.
Start with the content API
After sesamy-js has initialised, use the content API for the article on the page:
// Optional: check whether access is currently available.
const available = await window.sesamy.content.hasAccess();
// Authorise and unlock the article when you want to display it.
const html = await window.sesamy.content.unlock();You do not need to execute a strategy, register a read, or handle decryption keys yourself when using the bundled Capsule plugin. hasAccess() is optional; calling it before unlock() can add requests and does not reserve access.
| Operation | What you get | Records a read? |
|---|---|---|
content.hasAccess() | A truthy availability result, or null when access is unavailable | No |
content.unlock() with Capsule | Decrypted HTML, also rendered into the manifest's target elements | On a successful metered or LOGIN policy grant |
content.unlock() through the HTML/proxy path | HTML for your integration to inject | When its registration endpoint grants metered access |
hasAccess() can return an entitlement object or a boolean, so test its truthiness rather than comparing it with true. Its result is advisory. The consuming unlock operation must authorise access again because the reader's session, counters, or strategy outcome may have changed.
How the article is selected
Both methods accept an element or CSS selector:
await window.sesamy.content.hasAccess('#acme-article');
await window.sesamy.content.unlock(document.querySelector('#acme-article'));When you omit that argument, sesamy-js tries these sources in order:
- The first article found by your configured content selectors. The default article selector is
sesamy-article. - The container around the first Capsule manifest if no configured article was found.
- The page body if Sesamy meta tags are present.
It rejects if no content element can be identified. On a page with several articles, pass the intended element explicitly rather than relying on document order.
Within that element, Capsule resource metadata takes priority. Configured selectors and element or ancestor attributes supply other fields, followed by Sesamy meta tags and content configuration fallbacks. If the article has no URL, sesamy-js falls back to the current page URL. See metadata resolution for the individual fields and selectors.
Reading metadata in the browser is discovery, not signature verification. The Capsule server verifies the signed resource before trusting its policy.
What is actually locked
The delivery format determines what a reader can obtain before authorisation:
| Format | What is on the page initially | How content becomes readable |
|---|---|---|
| Capsule | Encrypted article data, its manifest, and any public preview | The server authorises key delivery; the browser decrypts and renders the article |
| HTML/proxy | A preview or placeholder | The integration fetches authorised HTML and injects it |
Legacy container encode | Reversibly encoded content | Updated containers register a read through content.unlock() before local decoding |
Legacy container embed | Content already included in the page source | The container controls whether its content slot is displayed |
Legacy container event or signedUrl | Depends on your integration | Your event handler or signed-URL delivery supplies the content |
Reversible encoding and embedded content do not provide Capsule's encryption boundary. Updated lock-mode="encode" containers call content.unlock(article, { encodedContent: base64 }). This registers a strategy read and decodes locally without minting a signed delivery token. See the container reference for its attributes and modes.
Capsule: one authorisation and key-delivery request
With the bundled Capsule plugin enabled, content.unlock() detects the manifest and handles this flow:
The client sends the signed resource JWT and key descriptors from the manifest. It does not upload the article's encrypted body. The server reads the permitted strategy or paywall from signed data.paywallUrl; a browser-selected LOGIN paywall cannot replace the policy bound to that article.
An existing subscription permission or ordinary signed link can authorise access directly. Otherwise, the server evaluates the bound strategy against the reader and current counters, then applies the selected paywall. A LOGIN outcome requires a signed-in reader; an enabled leaky allowance can grant an anonymous free read.
This is one Capsule authorisation/key-delivery request. Initialisation, token refresh, and an optional hasAccess() check can make additional requests. Completed key responses and wrap keys are not cached across unlock calls, so a later read reaches policy evaluation again. Concurrent processing of the same root and override shares its in-flight operation.
The bundled plugin also processes Capsule content automatically during initialisation and relevant session or page updates. Manual unlock() calls are useful when your integration controls when an article should be displayed.
Publisher requirements
The new policy flow requires a verified publisher signature and article-specific encryption under content:${encodeURIComponent(resourceId)}. Signed data.entitlementScopes can list alternative subscription permissions separately from that encryption scope. Releasing a shared tier key for one free article would expose other articles in that tier, so shared-tier content must be re-encrypted before enabling a bound policy.
Your client does not construct these claims. Your publisher integration supplies them when rendering the manifest. Follow publisher setup and signed content policies.
Older manifests without a verified policy reference retain their legacy entitlement and signed-link access. Adding paywall-url to editable HTML does not enable new policy-based Capsule grants.
HTML/proxy delivery and existing calls
An explicit locked-content selector preserves the existing proxy transport, including migration pages that also contain a Capsule manifest:
const html = await window.sesamy.content.unlock('#acme-article', '.locked-content');
document.querySelector('#acme-content').innerHTML = html;The equivalent options form lets you supply the policy reference for that call:
const html = await window.sesamy.content.unlock('#acme-article', {
lockedContentSelector: '.locked-content',
paywall: 'st_acme',
});
document.querySelector('#acme-content').innerHTML = html;This path obtains an existing entitlement token or registers metered access, then fetches HTML through the proxy. It does not use Capsule's key endpoint. Its legacy browser-selected policy does not gain a trusted content descriptor in this release.
For policy-enabled Capsule, an optional { paywall: 'st_acme' } override must match the signed reference. When both are URLs, their origins must also match; a bare ID remains valid. If the content binds a strategy, pass that strategy rather than the paywall selected during an earlier check. Legacy Capsule manifests without a verified policy ignore this hint and still require their existing entitlement or signed-link grant. You can omit the article while supplying options with content.unlock(undefined, options).
API access operations
The browser uses two server operations. Fixed paywalls and strategies are both supplied as the optional paywall reference; the client never executes a strategy or interprets a paywall template to decide access.
POST /content/has-accessreturns a boolean without recording a read.POST /content/unlockauthorizes delivery and records applicable successful reads.delivery: "capsule"returns keys after validating the signed descriptor,delivery: "proxy"returns a scoped token, anddelivery: "encoded"ordelivery: "embed"returns an authorization result without a key or token.
The standard check response is a boolean. sesamy-js uses a compatibility media type internally to preserve its existing entitlement/boolean/null return values and token-less leaky hints. content.unlock() continues to return HTML. Legacy strategy execution and registration endpoints remain callable but are deprecated; repeated execution never counts a read. Direct sesamy-js paywalls.executeStrategy() calls retain their once-per-instance deprecation warning.
Proxy LOGIN grants still require a trusted authorization path; a browser-selected LOGIN reference cannot mint a proxy token. The encoded decision only governs reversible, locally available base64 content. Capsule continues to require a verified article-bound policy for policy-based key delivery. Subscription and ordinary signed-link paths retain their existing scope and behavior.
When a read counts
Successful metered grants consume the relevant leaky allowance. Signed-in policy grants also update the article-read log used for daily and weekly strategy counters. Anonymous leaky readers have an allowance, but do not populate the signed-in article counters.
Checks and denied requests do not record reads. Capsule records a policy grant after generating keys successfully. An HTML/proxy grant can be recorded before the subsequent HTML fetch finishes. Counts therefore represent access grants, not confirmation that the reader saw the article. Existing subscription and ordinary signed-link paths bypass metered registration.
Repeated grants for the same article do not add another unique article to the same counter window. A later read can update its read time and count in a new window. See strategy article counters for the UTC boundaries and storage limits.
Legacy local decoding does not automatically register a read
A container that only calls hasAccess() and then decodes locally does not register a read. Upgrade the container together with sesamy-js to use the encoded unlock path:
const html = await sesamy.content.unlock(article, { encodedContent: base64 });For a strategy reference, this calls POST /content/unlock. The server evaluates the current counters, requires a signed-in reader for LOGIN, and records a distinct article only when allowed. Three granted articles therefore produce counts of three before the next article is evaluated. Subscription entitlements bypass this registration. Denials return no HTML from unlock(); the component must keep the article hidden. This endpoint returns no signed link or key, so a browser-selected LOGIN policy cannot authorize proxy delivery or Capsule decryption.
Deploy the API first, then the SDK, sesamy-js, and updated legacy container. Older containers continue to decode locally without registration. The HTML/proxy /access endpoint retains its existing authorization rules.
Handling denial and request failures
For Capsule, the SDK renders decrypted content itself. If you call it manually, handle rejection and leave the protected content locked. renderPaywall below is your application's rendering callback:
try {
await window.sesamy.content.unlock();
} catch (error) {
if (error.status === 403 && error.paywall) {
renderPaywall(error.paywall);
} else {
// Keep the preview visible and offer your integration's retry or error UI.
console.error('Could not unlock the article', error);
}
}A policy denial can include status, paywallId, and paywall on the error. Authentication failures, policy mismatches, and network failures may not include a renderable paywall. None of these failures should be treated as permission to display protected content.
Next Steps
- Content API: method signatures, options, and return values
- Content metadata: selectors and fallback sources
- Publisher setup: sign and encrypt Capsule content
- Paywall strategies: policy selection and article counters