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
- Adding the Pelcro Script
- Adding Login & Subscribe Buttons
- Implementing the Paywall
- Using URL Triggers
- Implementing the User Dashboard
- 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 titledata-link- URL to navigate todata-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
| Class | Function | Attributes |
|---|---|---|
pelcro-login-button | Login / Dashboard | data-login-text, data-dashboard-text |
pelcro-register-button | Registration | — |
pelcro-subscribe-button | Subscription flow | data-product-id, data-plan-id |
pelcro-dashboard-button | User dashboard | — |
pelcro-gift-button | Gift purchase | data-product-id, data-plan-id |
pelcro-cart-button | Shopping cart | — |
pelcro-add-to-cart-button | Add to cart | data-sku-id (required) |
pelcro-purchase-button | Direct purchase | data-sku-id (required) |
pelcro-update-newsletters-button | Newsletter prefs | — |
pelcro-offline-subscribe-button | Offline plans | data-product-id, data-plan-id |
pelcro-manage-members-button | Manage members | data-subscription-id |
pelcro-save-button | Save/Follow | data-key (required), data-title, data-link, data-image |
3. Implementing the Paywall
Paywalls are configured in your Pelcro Dashboard.
- Go to Products → click ... → Configure
- Set as Paywall Product
- 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 Value | Behavior | HTML Required |
|---|---|---|
modal | Full-screen popup | None |
inline | Renders 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)andpointer-events:noneto content - Automatically unblurs on
PelcroUserLoggedInorPelcroSubscriptionCreateevents - No page refresh needed
Login Flow Inside Paywall
- User sees paywall (modal or inline)
- Clicks "Sign in" link in paywall
- Separate login modal opens (not inside paywall)
- User authenticates
PelcroUserLoggedInevent fires- 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:
- Meter Paywall (if free article limit reached)
- Newsletter Paywall (if configured)
- Subscription Paywall (modal or inline based on config)
4. Using URL Triggers
Open Pelcro modals via URL parameters.
Basic Triggers
| Action | URL |
|---|---|
| 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
| Action | URL |
|---|---|
| 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
| Status | Description |
|---|---|
active | Active subscription |
trialing | In trial period |
extended | Grace period access |
past_due | Payment overdue (optional) |
canceled | Canceled |
expired | Expired |
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):
| Setting | Default | Purpose |
|---|---|---|
primary_color | #f9f9f9 | Background/accent |
text_color | #000000 | Text color |
button_color | #141f6d | Button background |
button_text_color | #ffffff | Button 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
- React Elements: https://docs-react-elements.pelcro.com
For Blox-specific placement instructions, consult Blox support.
Updated 17 days ago
