Blox

Pelcro Integration Guide for Blox

A quick-start guide for Blox users to integrate Pelcro's subscription management, paywalls, and user authentication.


Table of Contents

  1. Adding the Pelcro Script
  2. Adding Login & Subscribe Buttons
  3. Implementing the Paywall
  4. Using URL Triggers
  5. Implementing the User Dashboard
  6. E-Reader Integration

1. Adding the Pelcro Script

Add this code to your site's <head> section:

<script>
  window.Pelcro = {};
  window.Pelcro.siteid = 1232; // replace with your PRODUCTION 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>

Do not self-host the script — always load from Pelcro's CDN to receive automatic updates.


2. Adding Login & Subscribe Buttons

Login Button

<button class="pelcro-login-button">Sign In</button>

Subscribe Button

<!-- Basic -->
<button class="pelcro-subscribe-button">Subscribe</button>

<!-- Pre-select a plan -->
<button class="pelcro-subscribe-button"
        data-product-id="123"
        data-plan-id="456">
  Subscribe to Premium
</button>

Save & Follow Button

You can save data to the user's metadata in order to retrieve it later in the future. This could be useful if you want to save the user's favorite articles, events, products, and more.

To save data to the user's metadata, add the class pelcro-save-button to the button. The key data attribute will be used as the category of the saved item, to later pull the saved data. You can save any property to the metadata by adding data-[name of the property to be saved].

Save articles or follow authors/topics:

<!-- Save an article -->
<button class="pelcro-save-button"
        data-key="articles"
        data-title="Article Title"
        data-link="https://yoursite.com/article/123"
        data-image="https://yoursite.com/image.jpg">
  Save Article
</button>

<!-- Follow an author -->
<button class="pelcro-save-button"
        data-key="authors"
        data-title="John Smith"
        data-link="https://yoursite.com/author/john-smith">
  Follow Author
</button>

<!-- Follow a topic -->
<button class="pelcro-save-button"
        data-key="topics"
        data-title="Technology"
        data-link="https://yoursite.com/topic/technology">
  Follow
</button>

Required Attribute:

  • data-key - Category identifier (articles, authors, topics, news, etc.)

Optional Attributes:

  • data-title - Display title
  • data-link - URL to navigate to
  • data-image - Thumbnail image URL

CSS State Classes:

  • pelcro-is-active - Item is saved (for toggle state styling)
  • pelcro-is-loading - Save operation in progress

Storage: Saved items are stored in user.metadata.metadata_saved_{key} as an array.


Saving state for the button

If you want to know the current state of the save buttons, whether it's loading or already saved, for styling proposes for example. We inject state classes to reflect the current state of the button. Clicking the button once will set the pelcro-is-loading class until it's saved, then we set the pelcro-is-active class. Clicking the button again would set the pelcro-is-loading class then remove pelcro-is-active when the item is removed from the metadata.

All Button Classes

ClassFunctionAttributes
pelcro-login-buttonLogin / Dashboarddata-login-text, data-dashboard-text
pelcro-register-buttonRegistration
pelcro-subscribe-buttonSubscription flowdata-product-id, data-plan-id
pelcro-dashboard-buttonUser dashboard
pelcro-gift-buttonGift purchasedata-product-id, data-plan-id
pelcro-cart-buttonShopping cart
pelcro-add-to-cart-buttonAdd to cartdata-sku-id (required)
pelcro-purchase-buttonDirect purchasedata-sku-id (required)
pelcro-update-newsletters-buttonNewsletter prefs
pelcro-offline-subscribe-buttonOffline plansdata-product-id, data-plan-id
pelcro-manage-members-buttonManage membersdata-subscription-id
pelcro-save-buttonSave/Followdata-key (required), data-title, data-link, data-image

3. Implementing the Paywall

Paywalls are configured in your Pelcro Dashboard.

  1. Go to Products → click ...Configure
  2. Set as Paywall Product
  3. Choose targeting: metered (X free articles) or premium (full restriction)

Paywall Types & Technical Implementation

Modal Paywall (default): Full-screen overlay with plan selection

Inline Paywall: Embedded within article - requires HTML setup (see below)

Meter Paywall: Shows "X articles remaining" counter

Modal vs Inline - How It's Triggered

Set in Pelcro Dashboard paywall configuration:

Config ValueBehaviorHTML Required
modalFull-screen popupNone
inlineRenders inside article<div id="pelcro-inline-paywall">

Inline Paywall HTML Setup

Blox Users: Wrap your article content in this div:

<div id="pelcro-inline-paywall">
  <!-- Your article content goes here -->
  <p>Article text...</p>
</div>

Pelcro will render the paywall inside this div when triggered.

Client-Side Content Protection

Blur specific content sections for non-subscribers:

<div data-pelcro-entitlements="premium">
  This content is blurred until user subscribes
</div>

<!-- With pre-selected plan for subscription -->
<div data-pelcro-entitlements="premium"
     data-product-id="123"
     data-plan-id="456">
  Protected content
</div>

Technical Details:

  • Applies filter:blur(3px) and pointer-events:none to content
  • Automatically unblurs on PelcroUserLoggedIn or PelcroSubscriptionCreate events
  • No page refresh needed

Login Flow Inside Paywall

  1. User sees paywall (modal or inline)
  2. Clicks "Sign in" link in paywall
  3. Separate login modal opens (not inside paywall)
  4. User authenticates
  5. PelcroUserLoggedIn event fires
  6. Paywall re-evaluates access and disappears if user has entitlement

No page refresh required - fully event-driven.

Paywall Display Priority

When multiple paywalls are configured, Pelcro shows in this order:

  1. Meter Paywall (if free article limit reached)
  2. Newsletter Paywall (if configured)
  3. Subscription Paywall (modal or inline based on config)

4. Using URL Triggers

Open Pelcro modals via URL parameters.

Basic Triggers

ActionURL
Login?view=login
Register?view=register
Plan Selection?view=plan-select
Gift Redemption?view=gift-redeem
Password Reset?view=password-forgot
Edit Profile?view=user-edit
Newsletter?view=newsletter

With Parameters

ActionURL
Specific Plan?view=plan-select&product_id=123&plan_id=456
Gift Purchase?view=plan-select&is_gift=true
Redeem Gift Code?view=gift-redeem&gift_code=ABC123
Update Payment?view=payment-method-update&source_id=XXX
Newsletter Update?view=newsletter-update&[email protected]
Cart with Items?view=cart&sku_id=32,33,34


5. Implementing the User Dashboard

Option A: Login Button (Recommended)

Shows login for guests, dashboard for authenticated users:

<button class="pelcro-login-button"
        data-login-text="Sign In"
        data-dashboard-text="My Account">
  Sign In
</button>

Option B: Dashboard Only

<button class="pelcro-dashboard-button">My Account</button>

Customization

<script>
  window.Pelcro = {};
  window.Pelcro.siteid = YOUR_SITE_ID;
  window.Pelcro.uiSettings = {
    enableLoginWithUsername: true,
    enableNameFieldsInRegister: true,
    newsletters: [
      { "id": "daily", "label": "Daily Digest" }
    ]
  };
</script>
<script defer src="https://js.pelcro.com/sdk/main.min.js"></script>

6. Save & Follow - Retrieving Saved Items

Get All Saved Items

const user = window.Pelcro.user.read();
const allMetadata = user.metadata;

// Get all saved categories
const savedItems = Object.entries(allMetadata || {})
  .filter(([key]) => key.startsWith("metadata_saved_"))
  .map(([key, value]) => ({
    category: key.replace("metadata_saved_", ""),
    items: value
  }));

console.log(savedItems);
// Example output:
// [
//   { category: "articles", items: [{title: "...", link: "..."}, ...] },
//   { category: "authors", items: [{title: "...", link: "..."}, ...] }
// ]

Get Specific Category

// Get saved articles
const savedArticles = window.Pelcro.user.read().metadata?.metadata_saved_articles || [];

// Get followed authors
const followedAuthors = window.Pelcro.user.read().metadata?.metadata_saved_authors || [];

// Get followed topics
const followedTopics = window.Pelcro.user.read().metadata?.metadata_saved_topics || [];

Displaying Saved Items

The dashboard automatically displays all saved items under "Saved & followed" menu. No additional code needed.


7. E-Reader Integration

Check Subscription Status

document.addEventListener('PelcroUserLoggedIn', function() {
  const subscriptions = window.Pelcro.subscription.list() || [];

  const hasAccess = subscriptions.some(sub =>
    ['active', 'trialing', 'extended'].includes(sub.status)
  );

  if (hasAccess) {
    // Grant e-Reader access
  }
});

Check Entitlement-Based Access

// If you've configured entitlements in Pelcro Dashboard
if (window.Pelcro.user.isEntitledTo('ereader-access')) {
  // Grant e-Reader access
}

Require Login for E-Reader

if (!window.Pelcro.user.isAuthenticated()) {
  window.location.href = '?view=login';
}

Subscription Status Reference

StatusDescription
activeActive subscription
trialingIn trial period
extendedGrace period access
past_duePayment overdue (optional)
canceledCanceled
expiredExpired

JavaScript Events

Events You Can Listen To (Verified in Codebase)

// User authentication events (from SDK)
document.addEventListener('PelcroUserLoggedIn', function() {
  console.log('User logged in');
});

document.addEventListener('PelcroUserLogout', function() {
  console.log('User logged out');
});

document.addEventListener('PelcroUserLoaded', function() {
  const user = window.Pelcro.user.read();
  console.log('User data loaded:', user);
});

// Subscription events (from SDK)
document.addEventListener('PelcroSubscriptionCreate', function(e) {
  console.log('New subscription:', e.detail.data);
});

// Site loaded (from SDK)
document.addEventListener('PelcroSiteLoaded', function() {
  const site = window.Pelcro.site.read();
  console.log('Site config loaded:', site);
});

// Modal opened (from React Elements)
document.addEventListener('PelcroModalDisplay', function(e) {
  console.log('Modal opened:', e.detail.modalName);
});

// Cart events (from React Elements)
document.addEventListener('PelcroElementsCartOpened', function() {
  console.log('Cart opened');
});

document.addEventListener('PelcroElementsCartClosed', function() {
  console.log('Cart closed');
});

document.addEventListener('PelcroElementsCartItemAdded', function(e) {
  console.log('Item added to cart:', e.detail);
});

document.addEventListener('PelcroElementsCartItemRemoved', function(e) {
  console.log('Item removed from cart:', e.detail);
});

Event Sources:

  • (from SDK) - Dispatched by Pelcro SDK (main.min.js)
  • (from React Elements) - Dispatched by this React library

Advanced Configuration

uiSettings Options

Configure in your Pelcro script:

<script>
  window.Pelcro = {};
  window.Pelcro.siteid = YOUR_SITE_ID;
  window.Pelcro.uiSettings = {
    enableLoginWithUsername: true,
    enableNameFieldsInRegister: true,
    requireNameFieldsInRegister: true,
    addNewslettersSelectionToRegistration: true,
    newsletters: [
      { "id": "daily", "label": "Daily Newsletter" }
    ],
    skipPaymentForFreePlans: true,
    enableDateOfBirth: true,
    hideGiftForAutoRenew: true
  };
</script>

Design Settings

Customize colors (configure in Pelcro Dashboard):

SettingDefaultPurpose
primary_color#f9f9f9Background/accent
text_color#000000Text color
button_color#141f6dButton background
button_text_color#ffffffButton text

SDK Methods Reference

These methods are available from the Pelcro SDK:

// Check if current article requires subscription
window.Pelcro.paywall.isArticleRestricted()

// Check if paywall should display
window.Pelcro.paywall.displayPaywall()

// Get remaining free article visits
window.Pelcro.paywall.freeVisitsLeft()

// Check user entitlement
window.Pelcro.user.isEntitledTo('entitlement-name')

// Get user subscriptions
window.Pelcro.subscription.list()

// Check authentication
window.Pelcro.user.isAuthenticated()

// Read user data
window.Pelcro.user.read()

Support



For Blox-specific placement instructions, consult Blox support.