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

<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:

Signal	Example use case
User agent	Show a simplified paywall on mobile devices
Geographic region	Adjust pricing or currency by country
Authentication state	Show a login-only paywall to readers who have an account but no subscription
Referral source	Offer a discount to readers arriving from social media
Visit frequency	Show 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

POST /paywalls/strategies/:strategyId/execute adds these fields to the upstream strategy request automatically:

{
  "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 are calendar buckets, separate from the existing per-paywall leaky allowance. The tally IDs are article-reads:day and article-reads:week; expired buckets are treated as empty during strategy execution and replaced on the next read, so history does not accumulate.

The existing POST /paywalls/:paywallId/access call records the article server-side after access is granted. sesamy-js already makes this request through paywalls.registerAccess(). Its request and response shapes are unchanged; there is no separate read-registration endpoint or additional browser call. POST /paywalls/:paywallId/access/check, blocked requests, and failed grants do not record reads. Repeated grants for the same publisher content ID count once per bucket.

The counts represent successful access grants, not confirmation that content was rendered in the browser. Unlocks that bypass this endpoint, such as direct subscription or Capsule unlocks, do not populate these buckets.

To offer login access for the first X articles, configure the upstream strategy to select a LOGIN paywall while the relevant count is below X and a subscription paywall when it reaches X. For combined limits, select the subscription paywall when either limit is reached. The current article is counted when access is granted, so a limit of 3 changes the selection for the fourth new article. Preserve subscription entitlement access independently of the strategy.

The upstream strategy engine must support user and articleReads in its rule context. This proxy supplies the context; it does not create or change strategy rules. Your integration must apply the resolved paywall to its access decision. A static LOGIN paywall still grants login-based access as before.

These counters support paywall selection. The existing per-paywall leaky allowance remains separate, and tally KV updates are not atomic across concurrent requests. Selecting a different paywall does not by itself change the server's access policy.

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

• Leaky Paywall -- Offer free articles before requiring a subscription
• Content Protection -- How content is locked and unlocked
• CMS Integration Overview -- The full recommended setup