Supertab.js makes it simple to embed powerful monetization flows into your site. This guide will walk you through launching experiences and what information you receive about choices your customers make when interacting with a Supertab experience.

​
Before You Begin

Make sure that you have:

​
Initialize the Supertab.js Client

First, create a new Supertab instance using your client ID. 
const supertabClient = new Supertab({clientId: "client.your_client"});
Replace client.your_client with the live or test client ID associated with site you created when setting up your experiences. Supertab.js uses this client ID to make sure its running in the correct place.

​
Display a Paywall

The Paywall is a customizable experience that handles login, entitlement checks and purchase flows for you. You can launch it any time: on page load, after a user action or in response to app logic.
Quickstart

// First create the paywall
// Replace `experience.your_experience` with your experience ID
// Supertab.js will fetch the configuration of the paywall for you.
// No paywall is shown at this point, you must call .show()
const supertabPaywall = await supertabClient.createPaywall({
    experienceId: "experience.your_experience"
});

// Display the paywall to your user
// The paywall closes after a succesful purchase or on user abandonment
await supertabPaywall.show()

​
Options for createPaywall

Offerings available for sale, messaging text and styling are controlled from the Business Portal
KeyTypeRequiredDescription
experienceIdstringYesID of the Paywall experience created in the Business Portal
purchaseMetadataobjectNoKey-value pairs of custom information associated with the purchase.

​
PaywallExperienceResult

createPaywall returns a PaywallExperienceResult object containing the initial state of the Paywall and methods for showing it to users.
FieldTypeDescription
initialStateExperienceStateSummaryThe state of the paywall immediately after config is loaded, can be used to check if the user is logged in or has a prior entitlement already.
logIn() => Promise<ExperienceStateSummary>Launch an auth flow immediately, if necessary. The returned promise resolves when the login flow is completed.
show() => Promise<ExperienceStateSummary>Display the paywall to the user, the returned promise resolves when the paywall closes.
destroy() => voidClean up and remove all Supertab elements from the DOM.

​
Paywall Lifecycle

The state of the Paywall is generally returned to you as a promise which resolves when the Paywall exits. The Paywall may exit as a result of a successful purchase or as a result of user abandonment. Supertab Experiences uses an async programming paradigm. Each interaction returns a promise which resolves once the user has finished interacting with the Paywall. You can handle these promises through the use of async / await or through promise chaining with .then(). 
async function showPaywall() {
    const paywall = await supertabClient.createPaywall({ experienceId: "experience.your_experience" });

    const state = await paywall.show();

    // You can now work with the state
}
Examples on this page use async / await.

​
Checking for Purchases

The experience state will tell you if your user made a purchase from the paywall.
ExperienceStateSummaryTypeDescription
purchasePurchase | nullThe purchase made by the user.
paymentResultbooleantrue if the user made a payment to complete their purchase.
You can find detail about any purchase the user made by inspecting the purchase field.
PurchaseTypeDescription
idstringID of the purchase. You can use this with the Merchant API for backend checks the purchase is valid.
offeringIdstringID of the offering which was purchased.
descriptionstringDescription of the offering which was purchased
statusstringPossible values: completed, pending.

A purchase may be created as pending when the user is required to make payment. If handling entitlements yourself, only grant access when a purchase is completed.

The paywall will automatically launch the payment flow when necessary.
Check for a purchase

// Show the Paywall and wait for the promise to resolve.
// The promise resolves once the paywall has exited and is no longer showing to the user.
const state = await supertabPaywall.show();

if (!state.purchase) {
    // No purchase was made
    return
}

if (state.purchase.status === 'completed') {
    // A purchase has been made successfully!
    console.log("Customer made a purchase!", state.purchasedOffering.offeringId)
}

if (state.paymentResult) {
    // The user made a payment in order to complete their purchase
    console.log("Customer made a payment!")
}

​
Check For Prior Entitlement (Optional)

You may wish to check for any prior entitlement your user has purchased without immediately showing the paywall. This is achieved by inspecting the initial state of the paywall immediately after creating it.
ExperienceStateSummaryTypeDescription
priorEntitlementEntitlementStatus[] | nullArray of any prior entitlements the user has purchased.
EntitlementStatus contains information on which contentKeys the user has an entitlement for and when their entitlement expires.
EntitlementStatusTypeDescription
contentKeystringID of the content key which the user has an entitlement for.
expiresstringDate when the user’s entitlement expires. e.g 2025-01-01 00:00:00
hasEntitlementbooleantrue if the user has an entitlement for the content key.
Prior Entitlements
const supertabPaywall = await supertabClient.createPaywall({
    experienceId: "experience.your_experience"
});

const state = supertabPaywall.initialState;
const entitlements = state.priorEntitlement;

// contentKey we wish to check entitlement for
const checkFor = "site.your_site_id";

for (const entitlement of entitlements) {
    if (entitlement.contentKey === checkFor && entitlement.hasEntitlement) {
        // The user has an entitlement
        return true
    }
}

// The user does not have an entitlement
return false;
You may also check for entitlements after the paywall has exited by inspecting the priorEntitlement field of the resolves ExperienceStateSummary object.

​
Force LogIn (Optional)

It is only possible to check for prior entitlements without starting the paywall experience when the user is already logged in. You can force an immediate login by calling logIn on the paywall itself.
Force Login
const supertabPaywall = await supertabClient.createPaywall({
    experienceId: "experience.your_experience"
});

// Supertab SSO will open in a popup and return to you the new paywall state
// WARNING: You should only open a popup in response to user action to avoid the browser blocking the popup.
const state = await supertabPaywall.logIn()
Because .logIn() immediately opens a popup it should only be called in response to a user action.

​
Wrapping Up

We’ve covered:
  • How to create and show a paywall
  • The lifecycle of the paywall and its async programming model
  • How to work with the state of the paywall to check for purchases and entitlements