Integrations

There are three ways to add Paperwall to a site. Choose based on how much of the paywall you want to build.

• Standalone — add a <script> tag and use the default Paperwall wall.
• Ghost — the same tag with wallType: "ghost", plus a Ghost admin key so Paperwall can restore the full post.
• BYO Wall — install the paperwall package and render your own interface using the SDK.

The portal generates the snippet for whichever you choose. Open your site and select Configure your code. Use the generated snippet rather than the examples in these pages: it includes your site token and is pinned to a loader version and integrity hash that have been verified.

Shared configuration

All three integrations take the same configuration object. The script-tag integrations pass it to buildWall(); the SDK integration passes it to initPaperwall().

The snippets the portal generates contain only what a given integration needs. Everything else below is optional and can be added when you want it.

{
  mode: "live",              // "live" | "sandbox" | "local"
  wallType: "standalone",   // script tag only: "standalone" | "ghost"
  siteToken: "YOUR_SITE_TOKEN",
  articleFinder: {
    selector: "blog-post",       // id (or .class) of your article element
    postUrls: [/\/posts\/.*/],   // regexes matching your article URLs
    excludeUrls: [/\/posts\/draft-/],  // optional
  },
  theme: {                   // optional
    siteName: "Your Publication",
    siteLogo: "https://your-site.com/logo.png",
  },
}

Reference

Key	Required	Description
mode	Yes	Which Paperwall environment to use.
siteToken	Yes	Identifies your site.
wallType	Script tag only	Which prebuilt bundle to load.
articleFinder.selector	Yes*	Locates the article body.
articleFinder.postUrls	Yes*	Which URLs are articles.
articleFinder.excludeUrls	No	URLs to exclude after postUrls matches.
theme.siteName	No	Overrides the site title on the wall.
theme.siteLogo	No	Overrides the site logo on the wall.

* Not required on Ghost. The Ghost bundle supplies the whole of articleFinder, and anything you set overrides it field by field. See Ghost.

mode

Selects the Paperwall environment: live (paperwall.io), sandbox (sandbox.paperwall.io), or local for development against a local stack. The generated snippet sets this for you.

siteToken

Identifies your site. The token is public and appears in your page source. The private token and any integration credentials are stored separately and are never sent to the browser.

articleFinder

Controls which pages Paperwall acts on, and where the article body is on those pages. Most reports of a wall not appearing come down to these values.

• postUrls — an array of regular expressions. If the current path matches none of them, Paperwall takes no action: no wall, no request, no recorded visit.
• selector — locates the article body in the DOM. A leading . is treated as a class name; any other value is an element id.
• excludeUrls — an optional array of regular expressions applied after postUrls matches, for pages that a broad include pattern would otherwise catch. Both lists accept regular expression literals or strings, and are matched unanchored.

theme

Optional. siteName and siteLogo control the publication name and logo shown on the default wall.

Neither is required, and the generated snippets omit the block. When it is absent, the wall uses the title and logo from your Paperwall site settings, which is usually what you want: one place to change them, and no placeholder values to replace in your page.

Set theme only when the wall should display something different from your site settings. Each key falls back independently, so you can override just the logo and leave the name to the site record.