Poool Access - React SDK

The easiest way to add Poool Access to your React app ✨

ℹ️ You're looking at the documentation for the v2 of React Access. If you're looking for v1, please see the v1 docs.

Installation

yarn add @poool/react-access

Usage

import { useRef } from 'react';
import {
  AccessContext,
  RestrictedContent,
  Paywall,
  Pixel,
} from '@poool/react-access';

export default = () => {
  const contentRef = useRef();

  return (
    <>
      { /*
        Wrap everything with our AccessContext component. Note the withAudit
        prop which saves you from writing AuditContext inside of
        AccessContext
      */ }
      <AccessContext
        appId="insert_your_app_id"
        config={{ cookies_enabled: true }}
        withAudit={true}
      >
        { /* Wrap your content with our RestrictedContent component */ }
        <RestrictedContent ref={contentRef}>
          <div className="articleBody">
            <p>Your article content</p>
          </div>
        </RestrictedContent>

        { /*
          Place our <Paywall /> component where you want your paywall to be
          displayed
        */ }
        <Paywall contentRef={contentRef} />

        { /*
          Place our <Pixel /> component anywhere inside an <AuditContext />
          component (or <AccessContext withAudit={true} />) to track page-view
          events (used for native segmentation)
        */ }
        <Pixel type="page-view" data={{ type: 'premium' }} />
      </AccessContext>
    </>
  );
};

Usage with AuditContext

import { useRef } from 'react';
import {
  AccessContext,
  AuditContext,
  Paywall,
  RestrictedContent,
  Pixel,
} from '@poool/react-access';

export default () => {
  const contentRef = useRef();

  return (
    <AuditContext appId="insert_your_app_id">
      <AccessContext appId="insert_your_app_id">
        <RestrictedContent ref={contentRef}>
          <div className="articleBody">
            <p>Your article content</p>
          </div>
        </RestrictedContent>

        <Paywall contentRef={contentRef} />
        <Pixel type="conversion" />
      </AccessContext>
    </AuditContext>
  );
};

IE Compatibility

As part of a global effort to deprecate Internet Explorer, we decided not to include IE polyfills by default. You can still manually import a version containing all the necessary polyfills for IE >= 11:

import * as PooolReactAccess from '@poool/react-access/dist/ie/esm';

Please note that this build will probably add more than 150kb to your final bundle.

Documentation

<AccessContext />

Props

• appId {String} Your Poool App ID
• config {Object} (optional) Default paywall config (see the configuration documentation).
• styles {Object} (optional) Default paywall styles (see the styles documentation).
• texts {Object} (optional) Default paywall texts (see the texts documentation).
• events {Object} (optional) Paywall events listeners (see the events documentation).
• variables {Object} (optional) Paywall variables (see the variables documentation).
• scriptUrl {String} (optional, default: 'https://assets.poool.fr/access.min.js') Default Poool Access SDK url
• withAudit {Boolean} (optional, default: false) Whether to include AuditContext in AccessContext or not

<AuditContext />

Props

• appId {String} Your Poool App ID
• config {Object} (optional) Default audit config (see the configuration documentation).
• events {Object} (optional) Audit events listeners (see the events documentation).
• scriptUrl {String} (optional, default: 'https://assets.poool.fr/audit.min.js') Default Poool Audit SDK url

<RestrictedContent />

Props

• mode {String : 'excerpt' | 'hide'| 'custom'} (optional) Way to hide content see Access configuration for more informations.
• percent {Number} (optional) Percentage of content to hide.

<Paywall />

Props

• contentRef {React.Ref} Reference to the RestrictedContent component associated to this Paywall
• id {String} (optional, default: random id) Custom wrapper component ID
• pageType {String} (optional, default: 'premium') Current page type (supported types: page, premium, free, subscription)
• config {Object} (optional) Paywall config (see the configuration documentation).
• styles {Object} (optional) Paywall styles (see the styles documentation).
• texts {Object} (optional) Paywall texts (see the texts documentation).
• variables {Object} (optional) Paywall variables (see the variables documentation).
• events {Object} (optional) Paywall events listeners (see the events documentation)

<Pixel />

Props

• type {String} Event type (supported types: page-view, conversion)
• data{Object} (optional but mandatory when type is page-view) Data associated to the event (see the audit documentation)
• config {Object} (optional) Pixel config (see the configuration documentation).
• options {Object} (optional) Options to pass to the event (see the audit documentation)
• onDone {Function} (optional) Callback to execute when the event is done
• reuse {Boolean} (optional, default: false) Whether to reuse the same event or not

useAccess()

Can be used to retrieve some properties from the current access context, as well as the Access SDK itself.

Returns

• lib {Function} The entire Access sdk
• appId {String} Current app ID
• config {Object} Current access context config
• texts {Object} Current context texts
• styles {Object} Current context styles
• variables {Object} Current context variables
• events {Object} Current access context events listeners
• scriptURL {Object} Access SDK url

Example

const { appId, lib: access } = useAccess();

useAudit()

Can be used to retrieve some properties from the current audit context, as well as the Audit SDK itself.

Returns

• lib {Function} The entire Audit sdk
• appId {String} Current app ID
• config {Object} Current audit context config
• events {Object} Current audit context events listeners
• scriptURL {Function} Audit SDK url

Example

const { appId, lib: audit } = useAudit();

Contributing

Please check the CONTRIBUTING.md doc for contribution guidelines.

Development

Install dependencies:

yarn install

Run examples at http://localhost:63000/ with webpack dev server:

yarn serve

And test your code:

yarn test

License

This software is licensed under MIT.

v2 Migration

• <PaywallContext /> has been replaced with <AccessContext /> (used to show the paywall) and <AuditContext /> (used to track particular events)
• usePoool has been replaced with useAccess and useAudit, both respectively requiring the above contexts to be a parent component
• <Paywall /> now needs a contentRef prop to be able to lock/unlock the content, and the ref should be retrieved from <RestrictedContent />
• <Pixel /> has been added to avoid manual event tracking using the legacy poool() function

Basic example in v1:

import {
  PaywallContext,
  RestrictedContent,
  Paywall,
  usePoool,
} from '@poool/react-access';

export default () => {
  const { poool } = usePoool();

  useEffect(() => {
    poool('config', 'context', 'sports');
    poool('send', 'page-view', 'premium');
  }, []);

  return (
    <PaywallContext appId="test" config={{ cookies_enabled: true }}>
      <RestrictedContent><div>test</div></RestrictedContent>
      <Paywall />
    </PaywallContext>
  );
};

To be transformed in v2:

import { useRef } from 'react';
import {
  AccessContext,
  RestrictedContent,
  Paywall,
  Pixel,
} from '@poool/react-access';

export default () => {
  const contentRef = useRef();

  return (
    <AccessContext
      appId="test"
      config={{ cookies_enabled: true }}
      withAudit={true}
    >
      <RestrictedContent ref={contentRef}><div>test</div></RestrictedContent>

      <Paywall config={{ context: 'sports' }} contentRef={contentRef} />
      <Pixel type="page-view" data={{ type: 'premium' }} />
    </AccessContext>
  );
};