Arc XP - Poool (Paywall & Engage) Components

Example code is provided by a community of developers. They are intended to help you get started more quickly, but are not guaranteed to cover all scenarios nor are they supported by Arc XP.

These examples are licensed under the MIT license: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Reiterated from license above, all code in this example is free to use, and as such, there is NO WARRANTY, SLA or SUPPORT for these examples.

No Warranty: All code in this example is provided "as is" with no warranty, SLA, or support guarantees.

Table of Contents

• Overview
• Getting Started
• Environment Configuration Structure
• Precedence Order
• DOM & Data Layer Events
• Consent Handling
• Default Configuration
• Troubleshooting Guide
  • Overriding Values

Overview

This project provides Arc XP Fusion feature components that integrate Poool Access (paywall) and Poool Engage (engagement widgets) as separate, configurable components while sharing a unified environment configuration structure. For complete details about Poool, reivew Poool Developer Documentation

Getting Started

Prerequisites

• Arc XP Experience Required: Familiarity with Poool services and the Arc XP PageBuilder environment, plus experience with Fusion feature development, component architecture, and site configuration management
• A valid Poool App ID from your Poool dashboard
• Access to your site's environment/index.json configuration file
• Understanding of your site's article structure and CSS selectors
• Knowledge of React/JSX for component customization (if needed)

Quick Setup

1. Configure Environment Settings

   Add the Poool configuration to your environment/index.json:

   {
     "poool": {
       "appId": "YOUR_POOOL_APP_ID",
       "scriptOrigin": "https://assets.poool.fr",
       "paywall": {
         "enabled": true,
         "target": "#poool-widget",
         "content": ".article-content",
         "mode": "excerpt",
         "percent": 75
       },
       "engage": {
         "enabled": true,
         "autoCreate": true
       }
     }
   }

2. Install Components

   Copy the component folders from this repository to your bundle's components/features/ directory:

   • poool-engage/
   • poool-paywall/

3. Add Components to Your Pages

   Add the Paywall and/or Engage components to your page templates through PageBuilder. For the Paywall component, ensure the target field in your configuration points to the content container you want to protect.

4. Deploy and Test

   • Deploy your changes to your Arc XP environment
   • Visit an article page where components are active
   • Verify that paywall and engagement components are functioning as expected

Available Components

This repository provides two sets of components:

Component Path	Description
poool-paywall/default.jsx	Poool Access paywall component
poool-engage/default.jsx	Poool Engage widgets component

Note: There are also block architecture variants (poool-paywall-block/ and poool-engagement-block/) available. All variants support the same configuration structure.

Environment Configuration Structure

The environment/index.json contains a root poool object with module-specific sub-configs:

{
  "poool": {
    "appId": "XXXXX-XXXXX-XXXXX-XXXXX",
    "scriptOrigin": "https://assets.poool.fr",
    "paywall": {
      "enabled": true,
      "appId": "XXXXX-XXXXX-XXXXX-XXXXX",
      "scriptOrigin": "https://assets.poool.fr",
      "deferUntil": "DOMContentLoaded",
      "cookiesEnabled": true,
      "target": "#poool-widget",
      "content": ".b-article-body",
      "mode": "excerpt",
      "percent": 80,
      "pageType": "premium",
      "emitDomEvents": false,
      "emitDataLayer": false,
      "dataLayerName": "dataLayer"
    },
    "engage": {
      "enabled": true,
      "appId": "XXXXX-XXXXX-XXXXX-XXXXX", 
      "scriptOrigin": "https://assets.poool.fr",
      "deferUntil": "DOMContentLoaded",
      "autoCreate": true,
      "autoCreateFilters": [],
      "autoCommitPageView": false,
      "config": {
        "cookies_enabled": true
      }
    }
  }
}

Precedence Order

For both Paywall and Engage components, each field resolves in this order (highest first):

1. Custom fields (if provided through Page Builder / block props)
2. Site-level overrides (future: siteProperties.poool.paywall or siteProperties.poool.engage)
3. Sub-config (poool.paywall or poool.engage)
4. Root poool object (shared defaults)
5. Component hardcoded base defaults

App ID fallback: If a sub-config lacks appId, it inherits poool.appId. Same fallback applies for scriptOrigin, emitDomEvents, emitDataLayer, and dataLayerName in Engage; and for paywall these are flattened during merge.

DOM & Data Layer Events

When enabled:

• Paywall emits DOM event poool:paywall-created and pushes { event: 'poool_paywall_created', ... }.
• Engage emits events per enabled events flags as poool:engage:<event> and pushes { event: 'poool_engage_event', engageEvent: <name>, payload } plus an init event { event: 'poool_engage_initialized', ... }.

Consent Handling

If poool.consentRequired is true and window.__pooolConsentGranted === false, initialization is skipped.

Default Configuration

{
  "poool": {
    "appId": "XXXXX-XXXXX-XXXXX-XXXXX",
    "scriptOrigin": "https://assets.poool.fr",
    "paywall": {
      "enabled": true,
      "appId": "XXXXX-XXXXX-XXXXX-XXXXX",
      "scriptOrigin": "https://assets.poool.fr",
      "deferUntil": "DOMContentLoaded",
      "cookiesEnabled": true,
      "target": "#poool-widget",
      "content": ".b-article-body",
      "mode": "excerpt",
      "percent": 80,
      "pageType": "premium",
      "emitDomEvents": false,
      "emitDataLayer": false,
      "dataLayerName": "dataLayer"
    },
    "engage": {
      "enabled": true,
      "appId": "XXXXX-XXXXX-XXXXX-XXXXX",
      "scriptOrigin": "https://assets.poool.fr",
      "deferUntil": "DOMContentLoaded",
      "autoCreate": true,
      "autoCreateFilters": [],
      "autoCommitPageView": false,
      "config": {
        "cookies_enabled": true
      }
    }
  }
}

Note: Replace XXXXX-XXXXX-XXXXX-XXXXX with your actual Poool App ID from your Poool dashboard.

Troubleshooting Guide

Symptom	Likely Cause	Action
401 on Poool requests	Missing/incorrect appId	Verify poool.appId or module override and rebuild cache (.fusion clean)
Paywall not appearing	Disabled flag or consent gating	Check poool.paywall.enabled, feature flag, consent state

Overriding Values

• Environment: Edit environment/index.json under poool.
• Per-site: Add entries to blocks.json values.sites[site].siteProperties.poool.paywall/engage (future usage).
• Runtime (Page Builder custom fields): Provide matching prop names (e.g., mode, percent, autoCommitPageView, elements etc.).

---

Summary

This Arc XP - Poool integration provides a comprehensive solution for implementing paywalls and engagement widgets on Arc XP sites. The components are designed to be:

• Flexible: Support multiple configuration levels (environment, site, component)
• Production-ready: Built with best practices for Arc XP Fusion development
• Well-documented: Detailed configuration examples and troubleshooting guides

For additional support, refer to the Poool documentation and your Arc XP technical resources.

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Last updated: 2025-10-22