JavaScript SDK

Include the Pelcro.js script on every page of your site. To ensure you always receive the latest features and security updates, you must load the Pelcro.js script directly from https://js.pelcro.com . Do not bundle the script or host it yourself, as this will prevent you from receiving critical updates.

⚠️
To protect the security and stability of our platform, we reserve the right to block traffic from outdated and unsupported versions of the SDK. Self-hosting or bundling the script will eventually lead to your integration becoming outdated, which could cause it to stop working without notice.

Including Pelcro.js

To install the SDK, copy and paste the code below on every page of your site. You can find your configured script on the integration page from the settings of the platform.

Recommended Snippet

<script>
  window.Pelcro = {};
  window.Pelcro.siteid = 1232; // replace with your site ID
  window.Pelcro.environment = {
    domain: "https://www.pelcro.com",
    ui: "https://ui.pelcro.com/bundle.js",
    stripe: "pk_live_Wdef2LjEQXsgFWult6IVFobB"
  };
</script>
<script defer src="https://js.pelcro.com/sdk/main.min.js" type="text/javascript"></script>

Reference

Parameter	Description
`siteid`	Your Pelcro site id.
`domain`	The base domain for all the requests. The example uses our production. If you want to interact with our staging environment, you need the change this to `https://staging.pelcro.com`.
`ui`	The example uses the latest version of our production UI. If you interact with our staging environment, you need to use `https://ui.pelcro.com/staging/bundle.js`.
`stripe`	The Stripe publishable key. The example uses the live key. If you interact with our staging environment, you need to use the test key `pk_test_aThAAdvPHgIdAziZweywBWNk`.

Placement in Your HTML

For the best performance and user experience, you should always include Pelcro.js in the <head> of your pages, with defer. Loading the script in the head ensures that the SDK download begins immediately while the browser is parsing your HTML, reducing the delay before Pelcro is ready. By including the defer attribute, you prevent the script from blocking rendering, since it will only execute once the DOM has finished parsing. This combination achieves the fastest and most predictable initialization of Pelcro features such as paywalls, login prompts, and offers.

⚠️
If you load the SDK at the bottom of <body>, the UI will only initialize after the entire page finishes rendering, adding visible delay before modals or paywalls appear.

Optimizing with Preconnect

To speed up Pelcro’s initialization, you can add preconnect hints in the <head> of your pages. Preconnect establishes early network connections (DNS, TCP, TLS) to Pelcro’s servers and other third-party services, so that when the SDK or UI bundle is requested, the browser can start downloading immediately instead of waiting to set up a new connection.

<!-- Resource hints -->
<link rel="preconnect" href="https://js.pelcro.com" crossorigin>
<link rel="preconnect" href="https://ui.pelcro.com" crossorigin>
<link rel="preconnect" href="https://www.pelcro.com" crossorigin>

<!-- If you process payments with Stripe -->
<link rel="preconnect" href="https://js.stripe.com" crossorigin>
<link rel="preconnect" href="https://m.stripe.network" crossorigin>

Why it matters: Preconnect can save hundreds of milliseconds on first-time visits, reducing the time it takes for Pelcro modals and paywalls to appear. Place these tags before your Pelcro configuration and SDK script. They are safe to include on all pages, even if Pelcro is not used everywhere — browsers only establish the connections they need.

Browser Support

Our SDK supports all recent versions of major browsers on desktop and mobile, covering 92% of global browser usage. To ensure the best security, performance and user experience, we do not support legacy browsers without security updates.

Supported

Chrome, Firefox, Safari, and Edge: Latest versions plus the previous major version.
Mobile browsers: Recent versions of Chrome Mobile, Safari Mobile, Samsung Internet, and other modern mobile browsers.

Not Supported

Internet Explorer 11 and earlier.
Browsers without security updates for 24+ months.
Browsers that don't support modern JavaScript features (ES6 modules, Promises, TLS 1.2).

Technical Requirements

For browsers not explicitly supported, we require a modern environment that includes support for TLS 1.2, JavaScript Promises, and ES6 module loading. While our SDK may work on other browsers, we do not proactively test them but may respond to bug reports.

If you have an issue with our JavaScript SDK on a specific browser, please contact us so we can improve its support.

Events

Listen to triggered events from the SDK and add your own reactions. You can use these events to customize reactions for different events, integrate them with an analytics provider, or customize the user experience based on them.

Event	Description
PelcroSiteLoaded	Emitted when the site configuration has been loaded in the JS-SDK and hence window.Pelcro.site.read(); is now available.
PelcroUserRegister	Emitted when a user registers.
PelcroUserRefresh	Emitted when an authenticated user loads or reloads a page.
PelcroUserLoggedIn	Emitted when a user logs in.
PelcroUserLoaded	Emitted when the user object is updated with the most up-to-date data from the API.
PelcroUserLogout	Emitted when a user logs out.
PelcroUserUpdated	Emitted when the user is updated.
PelcroEmailVerified	Emitted when a user verifies their email.
PelcroSubscriptionCreate	Emitted when a subscription is created.
PelcroSubscriptionRenewed	Emitted when a subscription is renewed.
PelcroSubscriptionCancel	Emitted when a subscription is canceled.
PelcroSubscriptionReactivated	Emitted when a subscription is reactivated.
PelcroGiftRedeemed	Emitted when a gift is redeemed.
PelcroAddressCreated	Emitted when a user creates an address.
PelcroAddressUpdated	Emitted when user updated an existing address.
PelcroSourceCreated	Emitted when a payment source is created.
PelcroPasswordForgot	Emitted when the password forgot is requested.
PelcroPasswordReset	Emitted when the password gets reset.
PelcroEcommerceProductsLoaded	Emitted when the e-commerce products are loaded from the backend.
PelcroOrderCreated	Emitted when a successful e-commerce order is created by a user and includes the order object in the event detail.
PelcroPaywallMatch	Emitted when it's possible to display the meter paywall. It's calculated based on the free articles limit specified for the website, and the users' visits to that particular website. It returns an object that contains this data: `count_of_articles_read`, `count_of_articles_left` and `count_of_articles_limit`.
PelcroPaywallDisplayed	Emitted when paywall is displayed and the `displayPaywall` method return true.
PelcroNewsletterCreated	Emitted when a newsletter is created.
PelcroPaywallNotDisplayed	Emitted when paywall is not displayed and `displayPaywall` method return false.

Helpers

getURLParameter

Gets a specific URL parameter value from the current URL.

Example

const giftCode = window.Pelcro.helpers.getURLParameter("gift_code");
console.log(giftCode);

loadSDK

Loads JavaScript into the document.

Example

window.Pelcro.helpers.loadSDK(
  "https://js.stripe.com/v3",
  "pelcro-sdk-stripe"
);

loadCSS

Loads CSS into the document.

Example

Pelcro.helpers.loadCSS(
  "https://js.stripe.com/v3/integrations/812.css",
  "pelcro-css-stripe"
);

Authentication Token & JWT Expiry

The pelcro.user.auth.token cookie has a lifetime of 60 days and is extended every time the user reloads the page.
The JWT (JSON Web Token) TTL is also 60 days, but it does not get extended on page reloads.

As a result, even if the cookie is extended, the JWT will expire exactly 60 days after the user first logs in, requiring them to re-authenticate.

Customizable Membership Status Access

The JS SDK gives you more control over who can access your gated content. You can define which membership statuses should be allowed access by using the new Pelcro.uiSettings.membershipSubscriptionStatusAccess setting.

If you don’t configure this setting, the SDK will default to the following allowed statuses: ["active", "extended", "trialing", "past_due"]

To customize which statuses are allowed, simply update your configuration like so:

Pelcro.uiSettings = { membershipSubscriptionStatusAccess: ["active"] // Only allow active members to view content };

FAQ

What should I do if I want to use Pelcro's SDK only without the UI?

Simply replace the UI environment property with empty whitespace.

window.Pelcro.environment.ui = " ";

How do I deal with errors coming from calling Pelcro's SDK methods?

Requests will be validated by the API using server-side validations. Error messages returned by the API are accessible as follows:

window.Pelcro.user.login({
    email: "[email protected]",
    password: "INVALID_PASSWORD",
}, (error, response) => {
    if (error) {
    	console.log("error", error.response.data.error.message); // "Invalid credentials! Please try again."
    	console.log("error", error.response.data.error.status); // 404
    }
})

API status for errors will be either 4xx or 5xx depending on the severity of the error. Validation errors will be 4xx while server errors will be 5xx.