Skip to content

Paywall Strategies ​

How Sesamy lets you control which paywall is shown to which readers, enabling A/B testing and targeted conversion optimisation.

Overview ​

When a reader visits a premium article and lacks access, Sesamy decides which paywall to show. Because Sesamy controls this decision, you can serve different paywalls to different readers without changing your CMS templates.

This is handled through the paywall settings configured in the Sesamy dashboard and fetched by the <sesamy-paywall> component via its settings-url.

How it works ​

  1. The <sesamy-paywall> component loads its configuration from a settings-url endpoint
  2. The endpoint returns the paywall template, pricing, and display options
  3. Sesamy can vary the response based on reader attributes -- user agent, geography, authentication state, or custom segments
  4. The reader sees a paywall tailored to their profile
html
<sesamy-paywall
  settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
></sesamy-paywall>

A/B testing paywalls ​

You can create multiple paywall variants in the Sesamy dashboard and let Sesamy distribute readers across them. This lets you test:

  • Different templates -- article-style vs. box-style vs. login-only
  • Different pricing -- monthly vs. annual, different price points
  • Different messaging -- benefit-focused vs. urgency-focused copy
  • Different call-to-action placement -- inline vs. modal vs. notification bar

Sesamy tracks which variant each reader saw and correlates it with conversion outcomes, giving you data to optimise your paywall strategy.

Targeting by user segment ​

Paywall selection can consider:

SignalExample use case
User agentShow a simplified paywall on mobile devices
Geographic regionAdjust pricing or currency by country
Authentication stateShow a login-only paywall to readers who have an account but no subscription
Referral sourceOffer a discount to readers arriving from social media
Visit frequencyShow a more assertive paywall to frequent visitors

These rules are configured in the Sesamy dashboard and evaluated server-side, so no client-side code changes are needed.

Reader context and article counts ​

The unified content access operations resolve strategies internally and add these fields to the upstream strategy request automatically:

json
{
  "user": { "sub": "acme-reader", "scope": "openid profile" },
  "articleReads": { "day": 2, "week": 5 }
}

user is the user object from authentication middleware: verified token claims for signed-in readers, { "id": "...", "type": "anonymous" } for Basic-auth visitors, or null without an identity. It is not a separately fetched profile. The proxy loads counts from storage; callers cannot supply a user or override the counts in the strategy request.

Both counters are enabled by default for signed-in readers and scoped to the reader and vendor. They count unique articles granted access through the existing paywall access endpoint. Repeated strategy evaluations and access checks do not record reads. Anonymous readers have zero counts.

The day resets at midnight UTC. The week resets on Monday at midnight UTC. These counts are separate from the existing per-paywall leaky allowance.

Behind the two counts, Sesamy keeps a log of the reader's recent articles in a single tally, article-reads:log, with the time each article was last read. The day and week counts are derived from it, so other intervals can be added later without changing what is stored. The log keeps the last 31 days and at most 50 articles per reader; older reads are dropped first, so history does not accumulate. Counts therefore never exceed 50, so a strategy rule can only use limits up to 50 articles, within a window of at most 31 days.

Use sesamy.content.hasAccess() for a non-consuming check and sesamy.content.unlock() to authorize delivery and record a successful read. Both accept an optional paywall reference. Fixed paywalls and strategies use the same client contract.

At the HTTP layer, POST /content/has-access returns a boolean. POST /content/unlock returns Capsule keys, a scoped proxy token, or a token-free encoded decision according to the delivery mode. Capsule policy grants require a verified publisher descriptor; an editable browser policy cannot authorize an arbitrary proxy token or decryption key.

Legacy strategy execution and registration endpoints remain callable with their original responses, but are deprecated. Calling /execute any number of times does not record reads. Legacy /access endpoints continue to register successful grants under their established authorization rules.

Integration with Capsule ​

When using Capsule encryption, paywall strategies work transparently. If the reader lacks access, sesamy-js automatically injects the paywall configured for that article. The paywall component fetches its settings from the endpoint, which applies the targeting rules.

The flow:

  1. sesamy-js detects DCA content and checks entitlements
  2. Reader lacks access -- sesamy-js injects <sesamy-paywall> with the configured settings-url
  3. The paywall settings endpoint returns the variant selected for this reader
  4. The paywall renders with the appropriate template, pricing, and messaging

Next Steps ​

Released under the MIT License.