Skip to content
Arc XP
Product Documentation

How to Build a Server-side Paywall with Arc Subscriptions or an External System

The Arc XP Subscriptions paywall is a client-side rules engine that assesses various factors to decide if and how a particular pageview should be restricted. This method provides flexibility in targeting specific user segments, engagement levels, content areas, and more, ensuring that the most relevant marketing message is presented.

While the current paywall is optimized for speed and flexibility, there are drawbacks to this approach: because the rule evaluation happens client-side, it is susceptible to tampering that can result in crafty readers accessing content without a subscription.

Here are a few examples of where things can go amiss:

  • Publication A allows readers to sample five articles per month. To circumvent this budget, the reader could clear their local storage to renew their monthly allotment.
  • Publication B has a freemium model. When a reader without a subscription attempts to access a premium article, a pop-up appears with the latest offer. Depending on how the client implemented the paywall, it is possible that the article content is still on the page behind the modal and the reader can simply save the content to the Pocket queue, leverage Safari’s Reader mode, or pop open the developer console to hide the pop-up.
  • Publication C has a hard paywall model, but a local developer builds a Chrome extension that blocks the p.js paywall evaluator from downloading. When enabled, the paywall never executes because the extension prevents the script from being downloaded and executed.

Overview

Arc XP has an optional Server-Side Paywall (SSP) feature built into our CDN layer that customers using Arc Subscriptions or other third Party subscription platforms can use for the above cases. SSP checks at the CDN for the presence of a paywall cookie with entitlement status and then routes the request to relevant experience.

For example, a client could opt to return the first three paragraphs of the article followed by an inline subscription prompt to users who don’t have a subscription.

The implementation of each experience is up to the client. Arc Subscriptions does not offer a turnkey integration as customers control which audience bucket make sense for their business.

Customers using external paywall and subscription solutions, such as Poool, can opt to build middleware that sets the relevant cookie, too.

CDN Routing

The Arc XP offers the ability to route traffic at the CDN based on a paywall cookie.

A few examples of a reader attempting to access a piece of premium content:

  • If the reader does not have a valid subscription, they are served a truncated version of the article and prompted to subscribe or login
  • If the reader has an expired paywall cookie value, they’re routed to the login page and then redirected to the article page once they’ve authenticated
  • If the reader has a valid subscription, they reach the full article

The paywall cookie can be set on your site’s domain directly by your external Identity Provider (IdP) or by middleware. If you’re leveraging Arc Subscriptions, this customer-managed middleware will validate the user’s JWT with Arc Subscriptions and set the appropriate cookie based on reader’s subscription status. The customer must build this integration.

Strategy Considerations

There are a few limitations to be aware of with this approach:

  • All visitors must be sorted into one of three arbitrary buckets, such as “Anonymous”, “Authenticated”, and “Subscriber”
  • Given those three buckets, it is only possible to support two entitlement buckets, so you could offer an “All Access Subscription” and “Sports Only Subscription” but not “All Access Subscription”, “Sports Only Subscription”, and “Cooking Only”
  • If you’re using Arc’s client side paywall in conjunction to manage the marketing experience or serve a metered wall beyond a client side registration wall, it is your responsibility to manage the user experience between the two means of controlling access.
  • This approach can be used to deliver a hard registration wall or a hard paywall, but it is not possible to support a server-side metered wall with this solution.

SEO Considerations

Search engines must be able to access at least a sample of any content that you would like to be included in their indexes. When leveraging the server-side paywall outlined in this document, it is recommended that the paywalled version of the article includes enough content to enable search engine crawlers to establish a decent understanding of the content. The content included can be completely or partially obscured by a marketing prompt for readers.

Alternative approaches to allowing access to search engines opens easy-to-bypass backdoors or are technically not available within Arc’s CDN vendor.

Configuration

In order to leverage Arc’s integrated server-side paywall, you’ll need to manage three workstreams:

  • develop the middleware that evaluates the user’s status an sets the paywall cookie
  • provide the middleware URL to your Technical Account Manager
  • configure your PageBuilder set-up to support paywalled and non-paywalled experiences, that are routed by Arc CDN via the variant url parameter.

The third-party middleware service — as noted in the flow diagram above — is responsible for responding to incoming requests with a paywall cookie that can be processed by Arc CDN in this and future requests. This paywall cookie must include an expiration time to indicate the paywall cookie should be revalidated.

The value of the paywall cookie will be in the format of entitlement.expiration.hash. The expiration setting will use the current EPOCH (this is a Unix time stamp created by counting the number of seconds from January 1st 1970 UTC) time plus a revalidation period, such as 28800 seconds (8 hours) + current epoch. This will force revalidation after the added hours, but not before. The paywall cookie should be encrypted using SHA256 with the shared secret supplied by Arc. The value of the paywall cookie will be used to determine if the user has to be revalidated.

The client’s middleware sets the expiration value (or TTL) so that the middleware is consulted infrequently for each reader. It is a key goal of this approach to not make unnecessary pings to the middleware or introduce excessive latency to the content request flow.

If Arc CDN determines the reader’s paywall cookie is no longer valid when the cookie is present, they will be redirected (302) back to client-provided URL to re-validate the user’s paywall cookie. The 302 will include the referring URL as a URL query parameter the client’s system can use to redirect back to after extending the validation time stamp in the cookie. Example:

    HTTP/2 302
location: https://login.site.com/login?returnUrl=https://www.site.com/path/

To recap, the client IdP / middleware component will need to do the following:

  • Host the link to login to the site.
  • This should be under a subdomain of the primary domain. Example login.site.com can set the login cookie under site.com.
  • Host the link to register for the site and negotiate the login process.
  • This again will be under a subdomain like login.site.com. The registration process will need to work with site’s Identity Provider to create a new login with entitlements.
  • Create the paywall cookie under the primary domain that includes the entitlement and an EPOCH time stamp on when the paywall cookie will have to be revalidated.
  • The paywall cookie should also include HMAC-SHA256 signed cookie in this format: paywall cookie=1.1582838172.hashstring
  • If the desired revalidation period is 8 hours, 28,800 (8 hours * 60 minutes * 60 seconds) should be added to the current EPOCH time in the expiration place of the paywall cookie.
  • This paywall cookie should have An Expiration longer than the set EPOCH time stored in the expiration value within the paywall cookie. Arc recommends expiring the cookie after a month, which allows the cookie to still be there to show Arc this user has logged in before and just needs to be revalidated.
  • Host a revalidation link that Arc will redirect to when the expiration of the paywall cookie is less than the current EPOCH time.
  • When this URL is called, the query string will include the referring URL of the article the user wanted to read.
  • If the user still has a valid subscription, the paywall cookie should be recreated adding the proper number of time to the current EPOCH time and setting the proper entitlement.
  • If there is a problem with the user’s account, such as credit card didn’t process, you may want to send the user to their account information and ask them to update their credit card information.
  • If the user’s subscription has expired, you would want to link them to a page to renew.
  • You may even want to intercept a user that is valid at other times, such as when their subscription will expire soon to prompt them to renew.

The paywall cookie is generated server-side by your third-party middleware. The paywall cookie being sent should include two fields plus the HMAC-SHA256 hash signature.

For each site leveraging a server-side paywall, your Technical Account Manager will provide the pre-defined paywall cookie name (based on the site_id established in Site Service) along with a shared secret used to create the HMAC hash.

Cookie Explanation

Format: entitlement.timestamp.hash

Entitlement

This field is an integer that has the value of 1 or 2. The meaning of these entitlement values is up the client, and is given meaning by how the client configures their PageBuilder resolvers.

When a paywall cookie is present and the entitlement is 1 or 2, the entitlement number will be included in the variant URL parameter as part of the request to PageBuilder. When the paywall cookie is not present, then no variant URL parameter is sent to PageBuilder. For a resolver that is intended to serve paywalled content, when there is not a variant url param then you should render the paywall/shortened experience.

Entitlement ValueExample definitions
1Entitlement Option #1
2Entitlement Option #2

Timestamp

This EPOCH time value determines how often the CDN should re-validate with the third party service if the user entitlement is still valid. This timestamp should be small and must be less than 90 days in the future. Arc will not re-check the entitlement during this time frame, so it is important to be careful how long-lived to set the entitlement for. Arc will not offer cache-clearing or paywall cookie expiring functionality.

Hash

This is a base 64 encoded signed value generated using HMAC-SHA256.

Example:

    const secret = "MY-VERY-SECRET-SECRET";
const data = entitlement + "." + expiration;
const hash = CryptoJS.HmacSHA256(data, secret);
const hashInBase64 = CryptoJS.enc.Base64.stringify(hash);
const cookieVal = entitlement + "." + expiration + "." + hashInBase64 // final result

Once you’ve established middleware detailed above, you’ll need to provide your Technical Account Manager with URL of this service that is responsible for setting the cookie.

Finally, now that your middleware service is up and running and the CDN is configured, it is time to create experience variants within PageBuilder. CDN will pass the variant URL parameter into the request to PageBuilder and within PageBuilder’s resolver functionality you can control which template gets leveraged in accordance with the entitlement values the 3rd party middleware sets in the paywall cookie.

Note that the cache is bifurcated by the variant URL parameter values. CDN caches each version and serves users based on TTL. Not all requests execute on PageBuilder.