Events

Overview

This is the complete reference for all custom DOM events dispatched by the Pelcro JavaScript SDK. Use these events to respond to SDK initialization, user actions, and paywall decisions.

Events are dispatched at two distinct times:

1. Boot-time events - fire during SDK initialization, in a defined sequence
2. User-action events - fire in response to user interactions and API calls

Listening to Events

All events follow this pattern:

• Dispatched on the document object
• Data available in event.detail
• Events bubble and are not cancelable

document.addEventListener('PelcroUserLoggedIn', (event) => {
  const user = event.detail;
  console.log('User logged in:', user.email);
});

Boot Sequence

Boot-time events fire in this order during SDK initialization:

PelcroFingerprintReady
    |
PelcroAdBlockTestComplete -> PelcroAdBlockDetected (if blocker found)
    |
PelcroSiteLoaded
    |
PelcroUserLoaded (if session exists)
  |  PelcroUserRefresh (if session exists)
    |
PelcroEcommerceProductsLoaded (if e-commerce enabled)
    |
PelcroPaywallMatch (if content matches a paywall rule)
  |  PelcroPaywallDisplayed or PelcroPaywallNotDisplayed
    |
PelcroBootComplete

Boot-Time Events

PelcroFingerprintReady

Device fingerprinting is complete. This is the earliest boot-time event.

After this event, window.Pelcro.deviceHash is available.

document.addEventListener('PelcroFingerprintReady', () => {
  console.log('Device hash:', window.Pelcro.deviceHash);
});

PelcroSiteLoaded

Site configuration loaded from the API. Most SDK APIs are available after this event, but the user session may not yet be restored.

event.detail properties:

document.addEventListener('PelcroSiteLoaded', (event) => {
  const site = event.detail;
  console.log(`Site: ${site.name}, Currency: ${site.default_currency}`);
});

PelcroUserLoaded

User data loaded or updated. Fires both during boot (session restoration) and after any user action that updates user data. This is the most frequently fired user event.

Triggered by:

event.detail properties:

document.addEventListener('PelcroUserLoaded', (event) => {
  const user = event.detail;

  updateUserDisplay({
    name: `${user.first_name} ${user.last_name}`,
    email: user.email
  });
});

Tip: To distinguish boot-time firing from user-action firing, check whether PelcroBootComplete has already occurred.

PelcroEcommerceProductsLoaded

E-commerce products loaded during SDK initialization.

document.addEventListener('PelcroEcommerceProductsLoaded', (event) => {
  const products = event.detail;
  console.log(`${products.length} products loaded`);
});

PelcroBootComplete

SDK has completed its full initialization sequence. This is the safest event to wait for before interacting with any SDK feature.

document.addEventListener('PelcroBootComplete', () => {
  if (Pelcro.user.isAuthenticated()) {
    console.log('User:', Pelcro.user.read().email);
  }

  Pelcro.paywall.displayNewsletterModal();
});

AdBlock Detection Events

These events fire during boot when the SDK tests for ad blocker presence.

PelcroAdBlockTestComplete

Ad blocker detection test finished. Always fires first, before PelcroAdBlockDetected.

document.addEventListener('PelcroAdBlockTestComplete', (event) => {
  const hasAdBlocker = event.detail === 1;
  console.log('Ad blocker:', hasAdBlocker ? 'detected' : 'not detected');
});

PelcroAdBlockDetected

An ad blocker is active. Only fires when an ad blocker is found.

document.addEventListener('PelcroAdBlockDetected', () => {
  showAdBlockMessage('Please disable your ad blocker to support our content');
});

User Events

PelcroUserRegister

New user account created.

event.detail properties:

document.addEventListener('PelcroUserRegister', (event) => {
  const user = event.detail;
  console.log(`New user registered: ${user.email}`);
});

PelcroUserLoggedIn

User successfully authenticated.

event.detail properties:

document.addEventListener('PelcroUserLoggedIn', (event) => {
  const user = event.detail;
  console.log(`Welcome back, ${user.first_name}!`);

  if (user.loginType) {
    console.log(`Login method: ${user.loginType}`);
  }
});

PelcroUserLogout

User logged out or session invalidated.

event.detail properties:

document.addEventListener('PelcroUserLogout', () => {
  clearUserDisplay();
  hidePremiumContent();
});

PelcroUserUpdated

User profile data changed.

event.detail properties:

document.addEventListener('PelcroUserUpdated', (event) => {
  const user = event.detail;
  updateProfileDisplay({
    name: `${user.first_name} ${user.last_name}`,
    avatar: user.profile_photo
  });
});

PelcroUserRefresh

User session refreshed.

event.detail properties:

document.addEventListener('PelcroUserRefresh', (event) => {
  const user = event.detail;
  console.log(`Session refreshed for: ${user.email}`);
});

PelcroEmailVerified

Email verification completed.

event.detail properties:

document.addEventListener('PelcroEmailVerified', (event) => {
  const user = event.detail;
  showMessage(`Email verified: ${user.email}`);
});

PelcroMetadataUpdated

User metadata saved.

event.detail properties:

document.addEventListener('PelcroMetadataUpdated', (event) => {
  const user = event.detail;
  console.log('Metadata saved:', user.metadata);
});

Subscription Events

PelcroSubscriptionCreate

New subscription created.

Key properties available on the subscription within the user object:

document.addEventListener('PelcroSubscriptionCreate', (event) => {
  const data = event.detail;
  console.log('Subscription created');
});

PelcroSubscriptionCancel

Subscription canceled. Canceled subscriptions typically remain active until the end of the current billing period.

Additional event.detail properties:

document.addEventListener('PelcroSubscriptionCancel', (event) => {
  const data = event.detail;
  console.log(`Subscription ${data.canceledSubscriptionId} canceled`);
});

PelcroSubscriptionRenewed

Subscription renewed.

Note: Pelcro.subscription.renewGift() does not fire this event.

document.addEventListener('PelcroSubscriptionRenewed', (event) => {
  console.log('Subscription renewed');
});

PelcroSubscriptionReactivated

Previously canceled subscription reactivated.

document.addEventListener('PelcroSubscriptionReactivated', (event) => {
  console.log('Subscription reactivated');
});

PelcroSubscriptionUpdated

Subscription modified (e.g., suspended, domains/IPs changed).

document.addEventListener('PelcroSubscriptionUpdated', (event) => {
  console.log('Subscription updated');
});

PelcroGiftRedeemed

Gift subscription redeemed.

document.addEventListener('PelcroGiftRedeemed', (event) => {
  console.log('Gift subscription redeemed');
});

Payment Events

PelcroSourceCreated

Payment source added (legacy payment method system).

PelcroSourceUpdated

Payment source updated.

PelcroPaymentMethodCreated

Payment method added.

event.detail properties:

PelcroPaymentMethodUpdated

Payment method updated.

PelcroPaymentMethodDeleted

Payment method removed.

PelcroInvoicePay

Invoice paid.

document.addEventListener('PelcroInvoicePay', (event) => {
  console.log('Invoice paid');
});

Address Events

PelcroAddressCreated

New address added.

Address properties available within the user's addresses array:

PelcroAddressUpdated

Address modified.

Password Events

PelcroPasswordForgot

Password reset requested.

PelcroPasswordReset

Password reset completed.

PelcroPasswordUpdate

Password changed.

Side effect: This event also triggers Pelcro.user.logout(), logging the user out after the password change.

Newsletter Events

PelcroNewsletterCreated

Newsletter subscription created.

event.detail properties:

E-commerce Events

PelcroOrderCreated

Order placed.

event.detail properties:

Also fires: PelcroOrderCreate (deprecated)

Paywall Events

These events can fire during boot (automatic paywall evaluation) or at runtime (manual trigger).

PelcroPaywallMatch

Content matches a paywall rule. Fires before the paywall display decision is made.

event.detail properties:

document.addEventListener('PelcroPaywallMatch', (event) => {
  const visits = event.detail;
  console.log(`Articles read: ${visits.count_of_articles_read}/${visits.count_of_articles_limit}`);
});

PelcroPaywallDisplayed

Paywall shown to user because they do not have access to the content.

document.addEventListener('PelcroPaywallDisplayed', (event) => {
  const paywall = event.detail;
  console.log('Paywall displayed');
});

PelcroPaywallNotDisplayed

Paywall skipped because the user has access (valid subscription, matching entitlement, or blocked path).

document.addEventListener('PelcroPaywallNotDisplayed', () => {
  showFullContent();
});

Deprecated Events

These events still fire but should not be used in new integrations.