@waiverforever/embed-waiver

Waiverforever waiver embedding widget

This plugin provideds embedding waiver widget.

Usage

1. Pick a preferred waiver template at [https://app.waiverforever.com/templates]
2. Go to Waiver Template Setting Panel and active the Waiver Widget tab.
3. After the widget are configured properly, keep the templateId for next steps.
4. There are multiple importing schemes:

Reference widget script from CDN:

Widget could be loaded automatically or manually.

For automatically loading, add the HTML snippet to the main site:

<script src="https://cdn.waiverforever.com/qs3/ew.js?templateId=${templateId}" async defer></script>

1. Widget with its trigger button will be mounted as soon as possible. Scripting exposes the waiver instance as a global JavaScript variable named WF_EMBED_WAIVER.
2. The waiver instance has a .onReady(callback) hook which means the interactive occasion.
3. If it's non-necessary for using the the presetted trigger button, we could adding a query sdkMode=yes for disabling it: https://cdn.waiverforever.com/qs3/ew.js?templateId=${templateId}&sdkMode=yes

For manually loading, add the HTML snippet to the main site:

<script src="https://cdn.waiverforever.com/qs3/ew.js" async defer></script>

1. When the script src doesn't contain a specified templateId, scripting exposes the waiver constructor as a property of a global JavaScript variable named WF_EMBED_WAIVER.
2. We could manually initialize the waiver instance with pleasures. And use the interactive methods after .onReady(callback) hook has triggered.
3. In this way, it is better for using CDN cache mechanism.

We could also load the widget script dynamically， e.g. The AMD way：

require(['https://cdn.waiverforever.com/qs3/ew.js'], function ({ EmbedWaiver }) {
        const waiver = new EmbedWaiver({
            templateId: `${templateId}`,
            sdkMode: true
        })

        waiver.onReady(function(){
            myCustomButton.addEventListener('click', function () {
                waiver.toggle()
            })
        })
    })
})

Importing Widget into module system

Install widget by npm/yarn:

npm i --save @waiverforever/embed-waiver

// app.js
const EmbedWaiver = require('@waiverforever/embed-waiver')

const embedWaiver = new EmbedWaiver()

1. Full TypeScript supporting.
2. Definitions bring TS/JS users the better developing experience.
3. Could be used in ECMAScript module or Commonjs standards systems.
4. Could be dynamically loaded by third party bundler's code splitting feature.

Reference

Terms

• waiver constructor: In manually loading, dynamically loading schemes, scripting exposes a constructor named EmbedWaiver which is a property of global variable WF_EMBED_WAIVER. In module system, we could require or import it directly
• waiver instance: Output of waiver constructor. we could register events to its' hooks and manipulate its' behaviours by its' methods.
• SDK mode: Widget only displays waiver modal, we could bind waiver instance methods by ourself.
• window mode: Designed for mobile site integration, instead of showing waiver modal, a new waiver signing page will be opened.

API

EmbedWaiver constructor

interface EmbedWaiverOption {
    templateId: string;
    sdkMode?: boolean;  // by default is false
    windowMode?: boolean; // by default it depends on the useragent
    stylesheetURL?: string; // specify the stylesheet URL of the embedded waivers
}

type EmbedWaiver = (option?: EmbedWaiverOption): IEmbedWaiver;

usage:

const waiver = new EmbedWaiver({
    templateId: `${templateId}`,
})

EmbedWaiver instance

interface IEmbedWaiver {
    closeEmbedWaiverModal: () => void;  // Legacy API, for backward compatibility
    show: () => void; // Show waiver modal and hide trigger button(in non-sdk mode)
    close: () => void; // Opposite operation of show()
    toggle: () => void; // Toggle between show and close methods
    destroy: () => void; // Destroy the current waiver instance. After ensuring previous waiver instance is destroyed, we can re-initialize another waiver instance.
    onShowed: (callback: () => void) => void; // Event registry for modal showed hook
    onReady: (callback: (embedWaiver: IEmbedWaiver) => void) => void; // Event registry for waiver instance ready hook, an interactive waiver instance will be passed to the registered hook
    onSigned: (callback: () => void) => void; // Event registry for waiver signed
    onClosed: (callback: (signed: boolean) => void) => void; // Event registry for waiver modal close, the registered callback will receives a boolean type argument presents whether the user when it is triggered
    onDestroyed: (callback: () => void) => void; // Event registry for waiver destroyed hook
}

Advanced tips

If you don't like the callback style API, and Javascript Promise or async/await syntax is enabled in your developing environment, some highly recommend usages are here:

The waiver constructor and all event hooks are thenable/awaitable. We can wrap these API to a Promise Resolver. Specially for waiver constructor, the resolved waiver instance is a ready instance, it means we can manipulate all its methods without caring about whether it has been ready.

Let's see into a these convenient usages:

Thenable/Awaitable EmbedWaiver Constructor

// EmbedWaiver constructor cloud be chained by Promise
Promise.resolve(new EmbedWaiver({
    templateId: `${templateId}`,
})).then(function (embedWaiver) {
    embedWaiver.show()  // it's an appropriate occasion to call `.show` method
})

// note: use in async function, or some `top-level await` syntax enabled environment
const embedWaiver = await new EmbedWaiver({
    templateId: `${templateId}`,
})
embedWaiver.show()

Thenable/Awaitable ebedWaiver events hooks

Promise.resolve(embedWaiver.onShowed).then(() => {
    console.log('waiver showed!')
})

Promise.resolve(embedWaiver.onClosed).then((signed) => {
    console.log('waiver closed!')
    console.log('signed status:' signed)
})

// note: use in async function, or some `top-level await` syntax enabled environment
await embedWaiver.onShowed
console.log('waiver showed!')

// note: use in async function, or some `top-level await` syntax enabled environment
const signed = await embedWaiver.onClosed
console.log('waiver closed!')
console.log('signed status:' signed)