Fan Pass Web Components Library README

A lightweight bundle for loading Cirkay components via CDN. This bundle provides three main components: FanPassClaim, FanPassUnlock, and MobilePass.

Using via Cirkay Fan Pass CDN

Installation

UMD Bundle (Standalone)

The UMD bundle includes all components and dependencies in a single file. Add the following script tag to your HTML:

<!-- Latest -->
<script src="https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-standalone-umd.umd.js"></script>

<!-- Pinned (replace <version>) -->
<script src="https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-standalone-umd.<version>.umd.js"></script>

ES Modules (Standalone or Modular)

Use ES Modules if you prefer import (or if your app already provides shared dependencies like Lit).

<script type="module">
  // Standalone ES module (includes dependencies)
  import { FanPassClaim, FanPassUnlock, MobilePass } from 'https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-standalone-es.esm.js';

  // Or pinned (replace <version>)
  // import { FanPassClaim, FanPassUnlock, MobilePass } from 'https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-standalone-es.<version>.esm.js';

  // Modular ES module (excludes dependencies like lit / push-web-components)
  // import { FanPassClaim, FanPassUnlock, MobilePass } from 'https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-modular-es.esm.js';
  //
  // Or pinned (replace <version>)
  // import { FanPassClaim, FanPassUnlock, MobilePass } from 'https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-modular-es.<version>.esm.js';
</script>

Components

FanPassUnlock

A component that handles the unlocking of Fan Pass content.

<fp-unlock
  apiKey="your-api-key"
  otp-email-template="Your Magic Template Name"
  fanPassTitle="Fan Pass"
  buttonLabel="Connect"
  :logoSet="{
    large: { src: 'path/to/large-logo.png' },
    medium: { src: 'path/to/medium-logo.png' },
    small: { src: 'path/to/small-logo.png' },
    alt: 'Fan Pass Logo'
  }"
  :inline="false"
  :loading="false"
  :staging="false"
  :debugLogging="false"
  :cta="false"
  ctaText="Connect to unlock"
  btnBackgroundColor="#D60455"
  btnTextColor="#FFFFFF"
></fp-unlock>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | String | '' | Your Cirkay API key | | otpEmailTemplate (otp-email-template) | String | '' | Optional Magic OTP template name | | fanPassTitle | String | 'Fan Pass' | Title of the Fan Pass | | buttonLabel | String | 'Connect' | Label for the connect button | | logoSet | Object | See default | Logo configuration for different sizes | | inline | Boolean | false | Whether to display inline | | loading | Boolean | false | Loading state | | staging | Boolean | false | Whether to use staging environment | | debugLogging | Boolean | false | Enable debug logging | | cta | Boolean | false | Show call-to-action | | ctaText | String | 'Connect to unlock' | Text for the CTA | | btnBackgroundColor | String | '#D60455' | Button background color | | btnTextColor | String | '#FFFFFF' | Button text color |

Events

| Event | Description | Event Detail | |-------|-------------|--------------| | fp-unlock-initialising | Dispatched when component is initializing | { status: 'initialising' } | | fp-unlock-initialised | Dispatched when component is initialized | { status: 'initialised' } | | fp-unlock-started | Dispatched when unlock flow starts | { status: 'started' } | | fp-unlocked | Dispatched when unlock is completed | { status: 'unlocked', data: {...} } | | fp-unlock-complete | Dispatched when unlock process is complete | { status: 'complete', data: {...} } | | fp-mobile-data | Dispatched with mobile pass data | { data: {...} } |

FanPassClaim

A component for claiming Fan Passes.

<fp-claim
  apiKey="your-api-key"
  otp-email-template="Your Magic Template Name"
  fanPassTitle="Fan Pass"
  :logoSet="{
    large: { src: 'path/to/large-logo.png' },
    medium: { src: 'path/to/medium-logo.png' },
    small: { src: 'path/to/small-logo.png' },
    alt: 'Fan Pass Logo'
  }"
  :modal="false"
  :validateAfterModal="false"
  redeemCode=""
  successUrl="https://example.com/success"
  successUrlTarget="_blank"
  :autoRedirect="false"
  :showRedeemInput="true"
  :staging="false"
  :debugLogging="false"
  btnBackgroundColor="#D60455"
  btnTextColor="#FFFFFF"
></fp-claim>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | String | '' | Your Cirkay API key | | otpEmailTemplate (otp-email-template) | String | '' | Optional Magic OTP template name | | fanPassTitle | String | 'Fan Pass' | Title of the Fan Pass | | logoSet | Object | See default | Logo configuration | | modal | Boolean | false | Display as modal | | validateAfterModal | Boolean | false | Validate after modal display | | redeemCode | String | '' | Code for redeeming Fan Pass | | successUrl | String | '' | URL to redirect after success | | successUrlTarget | String | '_blank' | Target attribute for success URL link ('_blank', '_self', '_parent', or '_top') | | autoRedirect | Boolean | false | Auto redirect after success | | showRedeemInput | Boolean | true | Show redeem code input | | staging | Boolean | false | Use staging environment | | debugLogging | Boolean | false | Enable debug logging | | btnBackgroundColor | String | '#D60455' | Button background color | | btnTextColor | String | '#FFFFFF' | Button text color | | defaultOptInLabel | String | '' | Copy for the default Fan Pass opt-in consent. With requireDefaultOptIn false, shown as informational text and default opt-in is implied when the user claims. With requireDefaultOptIn true, the same copy appears beside the default checkbox (bold); if empty or whitespace-only, that checkbox is not shown and that consent is not collected via the built-in control, unless you supply a custom checkbox via the optin slot. | | defaultOptInLegalText | String | '' | Additional legal copy shown for the default opt-in block. | | defaultOptInPrivacyUrl | String | '' | If set, appends a “Privacy Policy” link after defaultOptInLabel and in default legal copy. | | extraOptInLegalText | String | '' | Extra opt-in legal text. | | extraOptInPrivacyUrl | String | '' | Extra opt-in privacy URL. | | extraOptInLabel | String | '' | Label for an optional second (CRM) opt-in checkbox. If empty, that checkbox is not shown and the extra opt-in is not collected. | | requireDefaultOptIn | Boolean | false | When true, the user must check the default opt-in before email submit—only when the default opt-in checkbox is visible (non-empty defaultOptInLabel or a valid optin slot). If the label is blank so no default checkbox is shown, submit and claim are still allowed (this flag cannot block the flow when there is no opt-in to complete). |

Events

| Event | Description | Event Detail | |-------|-------------|--------------| | fp-claim-claiming | Dispatched when claim flow starts | { status: 'claiming' } | | fp-claim-claimed | Dispatched when claim is finished | { status: 'claimed', data: {...} } |

MobilePass

A component for displaying mobile pass information.

<fp-mobile-pass
  fanPassTitle="Fan Pass"
  androidLink="https://play.google.com/store/apps/details?id=com.example"
  appleLink="https://apps.apple.com/app/example"
  downloadLink="https://example.com/download"
  :displayIntro="false"
  :debugLogging="false"
></fp-mobile-pass>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | fanPassTitle | String | 'Fan Pass' | Title of the Fan Pass | | androidLink | String | '' | Link to Android app | | appleLink | String | '' | Link to iOS app | | downloadLink | String | '' | Link to download page | | displayIntro | Boolean | false | Show introduction text | | debugLogging | Boolean | false | Enable debug logging |

Event Handling

Example of handling events:

// Listen for unlock events
document.querySelector('fp-unlock').addEventListener('fp-unlock-complete', (event) => {
  console.log('Unlock complete:', event.detail);
});

// Listen for claim events
document.querySelector('fp-claim').addEventListener('fp-claim-claimed', (event) => {
  console.log('Claim complete:', event.detail);
});

Bundle Types

The CDN publishes multiple bundles. Choose the one that matches your setup:

| Bundle | Format | Includes dependencies | Latest | Pinned (replace <version>) | |---|---|---|---|---| | Standalone UMD | <script> | Yes | https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-standalone-umd.umd.js | https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-standalone-umd.<version>.umd.js | | Standalone ES | import | Yes | https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-standalone-es.esm.js | https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-standalone-es.<version>.esm.js | | Modular ES | import | No | https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-modular-es.esm.js | https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-modular-es.<version>.esm.js |

Production

For production, use the minified versions:

<!-- UMD -->
<script src="https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-standalone-umd.umd.js"></script>

<!-- UMD (Pinned - replace <version>) -->
<script src="https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-standalone-umd.<version>.umd.js"></script>

<!-- ES Modules -->
<script type="module">
        // Load main bundle
        import { FanPassClaim, FanPassUnlock, MobilePass } from 'https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/latest/cirkay-fan-pass-standalone-es.esm.js';

        // Or pinned (replace <version>)
        // import { FanPassClaim, FanPassUnlock, MobilePass } from 'https://cdn.n3xus.services/fan-pass-cdn/cirkay-components/<version>/cirkay-fan-pass-standalone-es.<version>.esm.js';
    </script>

Browser Support

The components are built using modern web standards and support all modern browsers:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Dependencies

The components require the following dependencies:

• Lit (for web components)
• Push Web Components (for UI elements)

These are included in the standalone bundle but need to be loaded separately when using the modular bundle.

Fan Pass Web Components Library Via NPM Beta

Welcome to the Fan Pass Web Components library! This library provides a collection of UX frontend components designed to be fast, reusable, and highly customisable for any project, without relying on proprietary technologies or frameworks. These components leverage standard Web APIs and are compatible with all modern browsers.

Installation

Requires Node v20.0+ minimum.

1. Install Node.js globally using one of the following methods:

• Mac: NVM
• Windows: NVM for Windows
• Direct download: Node.js

2. Install PNPM globally using one of the following methods:

• Mac: brew install pnpm
• Windows PowerShell: Run the command iwr https://get.pnpm.io/install.ps1 -useb | iex

Build scripts

We've provided the following build scripts to streamline the development process:

Fan Pass application:

• Develop main library: pnpm fan-pass:serve
• Build main library: pnpm fan-pass:build
• Build main library docs: pnpm fan-pass:build:docs

Importing components into your project

Our components are written as ES6 modules for seamless integration into your project without the need for transpilation through tools like Webpack or Babel. You can still use pre-processors like Vite, Webpack, or Roll-up for tree shaking and minification while preserving ES modules.

To initialise a web component and render it in your HTML and the DOM, simply import the component script within your page's entry scripts or as a script tag directly inside your page.