--- updatedAt: 2026-03-06T00:25:46.000Z agentTools: projectIndex: https://docs.pelcro.com/v2.4/llms.txt --- # Events Complete reference for all DOM events dispatched by the Pelcro JavaScript SDK, including boot sequence, triggers, and payload properties ## 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 ```javascript 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. | | | | ------------------ | ----------------------------------------------------- | | **Trigger** | SDK initialization, before site configuration loading | | **`event.detail`** | No payload | After this event, `window.Pelcro.deviceHash` is available. ```javascript 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. | | | | ------------------ | ------------------------------------------------------------------------- | | **Trigger** | After fingerprint and bot detection pass; before user session restoration | | **`event.detail`** | Site configuration object | **`event.detail` properties:** | Property | Type | Description | | -------------------------------------- | ------- | -------------------------------------------------------------------- | | `id` | number | Site ID | | `name` | string | Site name | | `default_currency` | string | Default currency code | | `settings` | string | Site mode: `"subscription"`, `"anti-adblock"`, or `"analytics-only"` | | `ecommerce_enabled` | boolean | Whether e-commerce is enabled | | `plans` | array | Available subscription plans | | `products` | array | Available products | | `restrictive_paywall_metatags_enabled` | boolean | Whether tag-based paywall restriction is enabled | ```javascript 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. | | | | ------------------ | ---------------------------------------------------------------- | | **Trigger** | Any operation that loads or refreshes user data (see list below) | | **`event.detail`** | User object | **Triggered by:** | Method | Context | | --------------------------------------- | -------------------------------------- | | `Pelcro.user.register()` | After registration | | `Pelcro.user.login()` | After login | | `Pelcro.user.idpLogin()` | After SSO login | | `Pelcro.user.authenticate()` | After token authentication | | `Pelcro.user.refresh()` | After session refresh (including boot) | | `Pelcro.user.update()` | After profile update | | `Pelcro.user.convert()` | After legacy account conversion | | `Pelcro.user.verifyEmailToken()` | After email verification | | `Pelcro.user.verifyLoginToken()` | After passwordless login | | `Pelcro.user.uploadProfilePicture()` | After picture upload | | `Pelcro.user.removeProfilePicture()` | After picture removal | | `Pelcro.user.resendEmailVerification()` | After resending verification | **`event.detail` properties:** | Property | Type | Description | | ---------------- | ------- | --------------------------- | | `id` | number | User's unique identifier | | `email` | string | User's email address | | `first_name` | string | User's first name | | `last_name` | string | User's last name | | `auth_token` | string | JWT authentication token | | `email_verified` | boolean | Whether email is verified | | `subscriptions` | array | User's active subscriptions | | `memberships` | array | User's memberships | | `addresses` | array | User's saved addresses | | `orders` | array | User's order history | | `metadata` | object | Custom metadata fields | ```javascript 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. | | | | ------------------ | ----------------------------------------------------------------------- | | **Trigger** | After site config loaded and user session restored; before paywall init | | **`event.detail`** | Array of product objects | | **Condition** | Only fires when `Pelcro.site.read().ecommerce_enabled === true` | ```javascript 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. | | | | ------------------ | ------------------------------------------------- | | **Trigger** | Once per page load, after all boot steps complete | | **`event.detail`** | No payload | ```javascript 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`. | | | | ------------------ | ----------------------------------------- | | **Trigger** | After ad blocker detection test completes | | **`event.detail`** | `0` (no blocker) or `1` (blocker present) | ```javascript 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. | | | | ------------------ | ------------------------------------------ | | **Trigger** | Ad blocker detection test returns positive | | **`event.detail`** | `1` | ```javascript document.addEventListener('PelcroAdBlockDetected', () => { showAdBlockMessage('Please disable your ad blocker to support our content'); }); ``` *** ## User Events ### PelcroUserRegister New user account created. | | | | ------------------ | ------------------------------------------------- | | **Trigger** | `Pelcro.user.register()`, `Pelcro.user.convert()` | | **`event.detail`** | User object | | **Also fires** | `PelcroUserLoaded` | **`event.detail` properties:** | Property | Type | Description | | ---------------- | ------- | ------------------------- | | `id` | number | User's unique identifier | | `email` | string | User's email address | | `first_name` | string | User's first name | | `last_name` | string | User's last name | | `auth_token` | string | JWT authentication token | | `email_verified` | boolean | Whether email is verified | | `metadata` | object | Custom metadata fields | ```javascript document.addEventListener('PelcroUserRegister', (event) => { const user = event.detail; console.log(`New user registered: ${user.email}`); }); ``` *** ### PelcroUserLoggedIn User successfully authenticated. | | | | ------------------ | ----------------------------------------------------------------------------- | | **Trigger** | `Pelcro.user.login()`, `Pelcro.user.idpLogin()`, `Pelcro.user.authenticate()` | | **`event.detail`** | User object with `loginType` field | | **Also fires** | `PelcroUserLoaded`, `PelcroUserLogin` (deprecated) | **`event.detail` properties:** | Property | Type | Description | | --------------- | ------ | -------------------------------------------------------------------- | | `loginType` | string | `"email"` or `"IDP"`. Not present when triggered by `authenticate()` | | `id` | number | User's unique identifier | | `email` | string | User's email address | | `first_name` | string | User's first name | | `last_name` | string | User's last name | | `auth_token` | string | JWT authentication token | | `subscriptions` | array | User's active subscriptions | | `memberships` | array | User's memberships | | `addresses` | array | User's saved addresses | | `orders` | array | User's order history | ```javascript 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. | | | | ------------------ | -------------------------------------------------------------------- | | **Trigger** | `Pelcro.user.logout()`, or session invalidation (401/403 on refresh) | | **`event.detail`** | Auth object | **`event.detail` properties:** | Property | Type | Description | | -------- | -------------- | ------------------------------------ | | `token` | string or null | The invalidated authentication token | ```javascript document.addEventListener('PelcroUserLogout', () => { clearUserDisplay(); hidePremiumContent(); }); ``` *** ### PelcroUserUpdated User profile data changed. | | | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Trigger** | `Pelcro.user.update()`, `Pelcro.user.uploadProfilePicture()`, `Pelcro.user.removeProfilePicture()`, `Pelcro.user.verifyEmailToken()`, `Pelcro.user.verifyLoginToken()`, `Pelcro.user.resendEmailVerification()` | | **`event.detail`** | User object | | **Also fires** | `PelcroUserLoaded` | **`event.detail` properties:** | Property | Type | Description | | ---------------- | ------- | ------------------------- | | `id` | number | User's unique identifier | | `email` | string | User's email address | | `first_name` | string | User's first name | | `last_name` | string | User's last name | | `phone` | string | User's phone number | | `profile_photo` | string | URL to profile photo | | `email_verified` | boolean | Whether email is verified | ```javascript document.addEventListener('PelcroUserUpdated', (event) => { const user = event.detail; updateProfileDisplay({ name: `${user.first_name} ${user.last_name}`, avatar: user.profile_photo }); }); ``` *** ### PelcroUserRefresh User session refreshed. | | | | ------------------ | ------------------------------------------------------------------ | | **Trigger** | `Pelcro.user.refresh()`, automatic session restoration during boot | | **`event.detail`** | User object | | **Also fires** | `PelcroUserLoaded` | **`event.detail` properties:** | Property | Type | Description | | --------------- | ------ | ------------------------------ | | `id` | number | User's unique identifier | | `email` | string | User's email address | | `auth_token` | string | Refreshed authentication token | | `subscriptions` | array | Current subscriptions | ```javascript document.addEventListener('PelcroUserRefresh', (event) => { const user = event.detail; console.log(`Session refreshed for: ${user.email}`); }); ``` *** ### PelcroEmailVerified Email verification completed. | | | | ------------------ | --------------------------------------- | | **Trigger** | `Pelcro.user.verifyEmailToken()` | | **`event.detail`** | User object | | **Also fires** | `PelcroUserLoaded`, `PelcroUserUpdated` | **`event.detail` properties:** | Property | Type | Description | | ---------------- | ------- | ------------------------------------ | | `id` | number | User's unique identifier | | `email` | string | Verified email address | | `email_verified` | boolean | `true` after successful verification | ```javascript document.addEventListener('PelcroEmailVerified', (event) => { const user = event.detail; showMessage(`Email verified: ${user.email}`); }); ``` *** ### PelcroMetadataUpdated User metadata saved. | | | | ------------------ | ------------------------------ | | **Trigger** | `Pelcro.user.saveToMetaData()` | | **`event.detail`** | User object | **`event.detail` properties:** | Property | Type | Description | | ---------- | ------ | ------------------------------------------------- | | `id` | number | User's unique identifier | | `metadata` | object | All user metadata including the newly saved value | ```javascript document.addEventListener('PelcroMetadataUpdated', (event) => { const user = event.detail; console.log('Metadata saved:', user.metadata); }); ``` *** ## Subscription Events ### PelcroSubscriptionCreate New subscription created. | | | | ------------------ | ------------------------------------------- | | **Trigger** | `Pelcro.subscription.create()` | | **`event.detail`** | User object (updated with new subscription) | **Key properties available on the subscription within the user object:** | Property | Type | Description | | ---------------------- | ------- | ---------------------------------------------- | | `id` | number | Subscription identifier | | `status` | string | Subscription status | | `plan` | object | The subscribed plan details | | `plan.id` | number | Plan identifier | | `plan.name` | string | Plan name | | `plan.interval` | string | Billing interval | | `current_period_start` | string | Current period start date | | `current_period_end` | string | Current period end date | | `cancel_at_period_end` | boolean | Whether subscription will cancel at period end | ```javascript 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. | | | | ------------------ | ---------------------------------------------------------- | | **Trigger** | `Pelcro.subscription.cancel()` | | **`event.detail`** | User object with additional `canceledSubscriptionId` field | **Additional `event.detail` properties:** | Property | Type | Description | | ------------------------ | ------ | -------------------------------------------- | | `canceledSubscriptionId` | number | The ID of the subscription that was canceled | ```javascript document.addEventListener('PelcroSubscriptionCancel', (event) => { const data = event.detail; console.log(`Subscription ${data.canceledSubscriptionId} canceled`); }); ``` *** ### PelcroSubscriptionRenewed Subscription renewed. | | | | ------------------ | ----------------------------------------------- | | **Trigger** | `Pelcro.subscription.renew()` | | **`event.detail`** | User object (updated with renewed subscription) | > **Note:** `Pelcro.subscription.renewGift()` does **not** fire this event. ```javascript document.addEventListener('PelcroSubscriptionRenewed', (event) => { console.log('Subscription renewed'); }); ``` *** ### PelcroSubscriptionReactivated Previously canceled subscription reactivated. | | | | ------------------ | --------------------------------------------------- | | **Trigger** | `Pelcro.subscription.reactivate()` | | **`event.detail`** | User object (updated with reactivated subscription) | ```javascript document.addEventListener('PelcroSubscriptionReactivated', (event) => { console.log('Subscription reactivated'); }); ``` *** ### PelcroSubscriptionUpdated Subscription modified (e.g., suspended, domains/IPs changed). | | | | ------------------ | ------------------------------------------------ | | **Trigger** | `Pelcro.subscription.update()` | | **`event.detail`** | User object (updated with modified subscription) | ```javascript document.addEventListener('PelcroSubscriptionUpdated', (event) => { console.log('Subscription updated'); }); ``` *** ### PelcroGiftRedeemed Gift subscription redeemed. | | | | ------------------ | ------------------------------------------------ | | **Trigger** | `Pelcro.subscription.redeemGift()` | | **`event.detail`** | User object (updated with redeemed subscription) | ```javascript document.addEventListener('PelcroGiftRedeemed', (event) => { console.log('Gift subscription redeemed'); }); ``` *** ## Payment Events ### PelcroSourceCreated Payment source added (legacy payment method system). | | | | ------------------ | ------------------------------------- | | **Trigger** | `Pelcro.source.create()` | | **`event.detail`** | User object (updated with new source) | *** ### PelcroSourceUpdated Payment source updated. | | | | ------------------ | --------------------------------- | | **Trigger** | `Pelcro.source.update()` | | **`event.detail`** | User object (updated source data) | *** ### PelcroPaymentMethodCreated Payment method added. | | | | ------------------ | -------------------------------- | | **Trigger** | `Pelcro.paymentMethods.create()` | | **`event.detail`** | Payment method API response | **`event.detail` properties:** | Property | Type | Description | | ---------------- | ------ | ----------------------------------- | | `id` | number | Payment method ID | | `type` | string | Payment method type | | `card` | object | Card details (if card payment) | | `card.brand` | string | Card brand (visa, mastercard, etc.) | | `card.last4` | string | Last 4 digits of card | | `card.exp_month` | number | Expiration month | | `card.exp_year` | number | Expiration year | *** ### PelcroPaymentMethodUpdated Payment method updated. | | | | ------------------ | --------------------------------------------------------------------- | | **Trigger** | `Pelcro.paymentMethods.update()`, `Pelcro.paymentMethods.verifyACH()` | | **`event.detail`** | Payment method API response | *** ### PelcroPaymentMethodDeleted Payment method removed. | | | | ------------------ | -------------------------------- | | **Trigger** | `Pelcro.paymentMethods.delete()` | | **`event.detail`** | Payment method API response | *** ### PelcroInvoicePay Invoice paid. | | | | ------------------ | ----------------------------------- | | **Trigger** | `Pelcro.invoice.pay()` | | **`event.detail`** | User object (updated after payment) | ```javascript document.addEventListener('PelcroInvoicePay', (event) => { console.log('Invoice paid'); }); ``` *** ## Address Events ### PelcroAddressCreated New address added. | | | | ------------------ | -------------------------------------- | | **Trigger** | `Pelcro.address.create()` | | **`event.detail`** | User object (updated with new address) | **Address properties available within the user's addresses array:** | Property | Type | Description | | ------------- | ------ | --------------- | | `id` | number | Address ID | | `line1` | string | Street address | | `city` | string | City | | `state` | string | State/province | | `postal_code` | string | Postal/ZIP code | | `country` | string | Country code | *** ### PelcroAddressUpdated Address modified. | | | | ------------------ | ------------------------------------------- | | **Trigger** | `Pelcro.address.update()` | | **`event.detail`** | User object (updated with modified address) | *** ## Password Events ### PelcroPasswordForgot Password reset requested. | | | | ------------------ | -------------------------- | | **Trigger** | `Pelcro.password.forgot()` | | **`event.detail`** | API response | *** ### PelcroPasswordReset Password reset completed. | | | | ------------------ | ------------------------- | | **Trigger** | `Pelcro.password.reset()` | | **`event.detail`** | API response | *** ### PelcroPasswordUpdate Password changed. | | | | ------------------ | -------------------------- | | **Trigger** | `Pelcro.password.update()` | | **`event.detail`** | API response | > **Side effect:** This event also triggers `Pelcro.user.logout()`, logging the user out after the password change. *** ## Newsletter Events ### PelcroNewsletterCreated Newsletter subscription created. | | | | ------------------ | ---------------------------- | | **Trigger** | `Pelcro.newsletter.create()` | | **`event.detail`** | Newsletter API response | **`event.detail` properties:** | Property | Type | Description | | --------------- | ------ | -------------------------- | | `id` | number | Newsletter subscription ID | | `newsletter_id` | number | The newsletter ID | | `email` | string | Subscribed email address | *** ## E-commerce Events ### PelcroOrderCreated Order placed. | | | | ------------------ | --------------------------------- | | **Trigger** | `Pelcro.ecommerce.order.create()` | | **`event.detail`** | Order object | **`event.detail` properties:** | Property | Type | Description | | ---------- | ------ | ---------------- | | `id` | number | Order ID | | `status` | string | Order status | | `total` | number | Order total | | `currency` | string | Currency code | | `items` | array | Order line items | > **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. | | | | ------------------ | ------------------------------------------------------------ | | **Trigger** | Paywall initialization evaluating page content against rules | | **`event.detail`** | Visit tracking record | **`event.detail` properties:** | Property | Type | Description | | ------------------------- | ------ | ------------------------------------------------- | | `count_of_articles_read` | number | Number of paywalled articles the user has visited | | `count_of_articles_left` | number | Free visits remaining | | `count_of_articles_limit` | number | Configured visit limit | ```javascript 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. | | | | ------------------ | ------------------------------------------------------------------------------ | | **Trigger** | `Pelcro.paywall.displayPaywall()`, or automatic paywall evaluation during boot | | **`event.detail`** | Paywall configuration object | ```javascript 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). | | | | ------------------ | --------------------------------------------- | | **Trigger** | Paywall evaluation when user has valid access | | **`event.detail`** | Paywall configuration object | ```javascript document.addEventListener('PelcroPaywallNotDisplayed', () => { showFullContent(); }); ``` *** ## Deprecated Events These events still fire but should not be used in new integrations. | Deprecated Event | Use Instead | Notes | | ------------------- | -------------------- | --------------------------------------------------------- | | `PelcroUserLogin` | `PelcroUserLoggedIn` | Fires alongside `PelcroUserLoggedIn` with the same detail | | `PelcroOrderCreate` | `PelcroOrderCreated` | Fires alongside `PelcroOrderCreated` with the same detail | *** # Sibling pages * [Modules](https://docs.pelcro.com/v2.4/docs/javascript-sdk-modules.md)