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 Paygate

The Paygate 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 paygate
// Replace `experience.your_experience` with your experience ID
// Supertab.js will fetch the configuration of the paygate for you.
// No paygate is shown at this point, you must call .show()
const supertabPaygate = await supertabClient.createPaygate({
    experienceId: "experience.your_experience"
});

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

​
Options for createPaygate

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

​
PaygateExperienceResult

createPaygate returns a PaygateExperienceResult object containing the initial state of the Paygate and methods for showing it to users.
FieldTypeDescription
initialStateExperienceStateSummaryThe state of the paygate immediately after config is loaded, can be used to check if the user is logged in or has a priort 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 paygate to the user, the returned promise resolves when the paygate closes.
destroy() => voidClean up and remove all Supertab elements from the DOM.

​
Paygate Lifecycle

The state of the Paygate is generally returned to you as a promise which resolves when the Paygate exits. The Paygate 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 Paygate. You can handle these promises through the use of async / await or through promise chaining with .then(). 
async function showPaygate() {
    const paygate = await supertabClient.createPaygate({ experienceId: "experience.your_experience" });

    const state = await paygate.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 paygate.
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 paygate will automatically launch the payment flow when necessary.
Check for a purchase

// Show the Paygate and wait for the promise to resolve.
// The promise resolves once the paygate has exited and is no longer showing to the user.
const state = await supertabPaygate.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 paygate. This is achieved by inspecting the initial state of the paygate 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 supertabPaygate = await supertabClient.createPaygate({
    experienceId: "experience.your_experience"
});

const state = supertabPaygate.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 paygate 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 paygate experience when the user is already logged in. You can force an immediate login by calling logIn on the paygate itself.
Force Login
const supertabPaygate = await supertabClient.createPaygate({
    experienceId: "experience.your_experience"
});

// Supertab SSO will open in a popup and return to you the new paygate state
// WARNING: You should only open a popup in response to user action to avoid the browser blocking the popup.
const state = await supertabPaygate.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 paygate
  • The lifecycle of the paygate and its async programming model
  • How to work with the state of the paygate to check for purchases and entitlements