Starting experiences

Supertab.js provides a low-code way to start experiences on your pages. See the guide on setting up experiences for more details on how to create and configure experiences. When you need more control over what happens with experiences you can use Supertab.js to recieve callbacks for specific events, entitlement statuses, or error conditions.

Pre-requisites

You have created an experience in the business portal.
Supertab.js is installed on your page.

Initialization

const supertabClient = new Supertab({clientId: "client.your_client"});

Paywall: `supertab.createPaywall`

Invoke the Paywall on page load or in response to user action.

const supertabClient = new Supertab({ clientId: "test_client.abc" });

const supertabPaywall = await supertabClient.createPaywall({
  experienceId: "experience.abc",
});

supertabPaywall.show()

Parameters

createPaywall accepts an object with the following properties:

string

required

ID of the paywall experience created in Business Portal.

object

Key-value pairs of custom information associated with the purchase.

Return value

A promise which resolves with an object with following properties:

function

Show the paywall UI.Returns a promise which resolves with the paywall summary.

If current user has prior entitlement to the content, the paywall will not show.

Show StateSummary

EntitlementStatus | null

Any prior entitlement of the current user. null if user has no prior entitlement.

Show prior entitlement

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

AuthStatus

Current authentication status of the user. Possible values: missing, expired, valid.

Purchase | null

Purchase object if launching the flow resulted in a purchase. null otherwise.

Show purchase object

string

ID of the purchase.Example: "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"

string

ID of the purchased offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string | null

Date and time of the purchase.Example: "2025-04-30T12:00:00Z"

string | null

Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.Example: "2025-04-30T12:00:00Z"

string

A summary of the purchase, usually including the website name and the type of a given entitlement.Example: "The Leek - 24 Hours Time Pass"

Price

Price object of the purchase.

Show Price object

number

Amount in currency base units.Example: 5000

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

PurchaseStatus

Status of the purchase. Possible values: completed, pending, abandoned.

Metadata

Key-value pairs of custom information associated with the purchase.

EntitlementStatus | null

The customer’s access (if any) as a result of this purchase.

Show Entitlement status object

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

Offering | null

Offering object if user has purchased an offering. null otherwise.

Show offering object

string

ID of the offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string

Description of the offering.Example: "24 Hours Time Pass to The Leek"

EntitlementDetails

Specifies the nature and duration of purchased entitlement.Where you have chosen to have Supertab manage entitlements for you, customer’s purchasing such an offering will be granted entitlement to the content associated with the offering for the length of time specified.

Show Entitlement details object

string

The duration of the entitlement as {length}{unit}.Examples:

{
  // 1 year
  "duration": "1y",
  // 2 months
  "duration": "2M",
  // 3 weeks
  "duration": "3w",
  // 4 days
  "duration": "4d",
  // 5 hours
  "duration": "5h",
  // 6 minutes
  "duration": "6m",
  // 7 seconds
  "duration": "7s"
}

boolean

Whether the entitlement is sold on a recurring basis (subscription).

string

The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

Price

Price object of the offering.

Tab

The users tab

Show Tab object

boolean

Whether the tab is in test mode.

Currency

The currency of the tab.

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The total amount of the tab.

Show Total object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The limit of the tab. When reached, the payment will be required.

Show Limit object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Array<Purchase>

Details of all purchases made by the customer through your merchant account. Purchases made with other merchant accounts are shown as a single purchase, which accumulates all totals into one and has a null value instead of a purchase ID.Each purchase in the array has the same structure as the previously described Purchase object.

boolean

If a purchase required payment, this will be true if payment was successful. false otherwise.

function

Hide the paywall UI.Returns a promise which resolves with the paywall summary.

Show StateSummary

EntitlementStatus | null

Any prior entitlement of the current user. null if user has no prior entitlement.

Show prior entitlement

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

AuthStatus

Current authentication status of the user. Possible values: missing, expired, valid.

Purchase | null

Purchase object if launching the flow resulted in a purchase. null otherwise.

Show purchase object

string

ID of the purchase.Example: "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"

string

ID of the purchased offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string | null

Date and time of the purchase.Example: "2025-04-30T12:00:00Z"

string | null

Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.Example: "2025-04-30T12:00:00Z"

string

A summary of the purchase, usually including the website name and the type of a given entitlement.Example: "The Leek - 24 Hours Time Pass"

Price

Price object of the purchase.

Show Price object

number

Amount in currency base units.Example: 5000

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

PurchaseStatus

Status of the purchase. Possible values: completed, pending, abandoned.

Metadata

Key-value pairs of custom information associated with the purchase.

EntitlementStatus | null

The customer’s access (if any) as a result of this purchase.

Show Entitlement status object

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

Offering | null

Offering object if user has purchased an offering. null otherwise.

Show offering object

string

ID of the offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string

Description of the offering.Example: "24 Hours Time Pass to The Leek"

EntitlementDetails

Show Entitlement details object

string

The duration of the entitlement as {length}{unit}.Examples:

{
  // 1 year
  "duration": "1y",
  // 2 months
  "duration": "2M",
  // 3 weeks
  "duration": "3w",
  // 4 days
  "duration": "4d",
  // 5 hours
  "duration": "5h",
  // 6 minutes
  "duration": "6m",
  // 7 seconds
  "duration": "7s"
}

boolean

Whether the entitlement is sold on a recurring basis (subscription).

string

The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

Price

Price object of the offering.

Tab

The users tab

Show Tab object

boolean

Whether the tab is in test mode.

Currency

The currency of the tab.

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The total amount of the tab.

Show Total object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The limit of the tab. When reached, the payment will be required.

Show Limit object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Array<Purchase>

boolean

If a purchase required payment, this will be true if payment was successful. false otherwise.

function

Starts the login flow. Opens Supertab SSO popup window if user is unknown. Otherwise will log user in silently if auth data are found but has expired.Returns a promise which resolves with the paywall summary.

Show ExperienceStateSummary

EntitlementStatus | null

Any prior entitlement of the current user. null if user has no prior entitlement.

Show prior entitlement

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

AuthStatus

Current authentication status of the user. Possible values: missing, expired, valid.

Purchase | null

Purchase object if launching the flow resulted in a purchase. null otherwise.

Show purchase object

string

ID of the purchase.Example: "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"

string

ID of the purchased offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string | null

Date and time of the purchase.Example: "2025-04-30T12:00:00Z"

string | null

Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.Example: "2025-04-30T12:00:00Z"

string

A summary of the purchase, usually including the website name and the type of a given entitlement.Example: "The Leek - 24 Hours Time Pass"

Price

Price object of the purchase.

Show Price object

number

Amount in currency base units.Example: 5000

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

PurchaseStatus

Status of the purchase. Possible values: completed, pending, abandoned.

Metadata

Key-value pairs of custom information associated with the purchase.

EntitlementStatus | null

The customer’s access (if any) as a result of this purchase.

Show Entitlement status object

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

Offering | null

Offering object if user has purchased an offering. null otherwise.

Show offering object

string

ID of the offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string

Description of the offering.Example: "24 Hours Time Pass to The Leek"

EntitlementDetails

Show Entitlement details object

string

The duration of the entitlement as {length}{unit}.Examples:

{
  // 1 year
  "duration": "1y",
  // 2 months
  "duration": "2M",
  // 3 weeks
  "duration": "3w",
  // 4 days
  "duration": "4d",
  // 5 hours
  "duration": "5h",
  // 6 minutes
  "duration": "6m",
  // 7 seconds
  "duration": "7s"
}

boolean

Whether the entitlement is sold on a recurring basis (subscription).

string

The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

Price

Price object of the offering.

Tab

The users tab

Show Tab object

boolean

Whether the tab is in test mode.

Currency

The currency of the tab.

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The total amount of the tab.

Show Total object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The limit of the tab. When reached, the payment will be required.

Show Limit object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Array<Purchase>

boolean

If a purchase required payment, this will be true if payment was successful. false otherwise.

ExperienceStateSummary

Initial state of the paywall.

Show ExperienceStateSummary

EntitlementStatus | null

Any prior entitlement of the current user. null if user has no prior entitlement.

Show prior entitlement

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

AuthStatus

Current authentication status of the user. Possible values: missing, expired, valid.

Purchase | null

Purchase object if launching the flow resulted in a purchase. null otherwise.

Show purchase object

string

ID of the purchase.Example: "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"

string

ID of the purchased offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string | null

Date and time of the purchase.Example: "2025-04-30T12:00:00Z"

string | null

Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.Example: "2025-04-30T12:00:00Z"

string

A summary of the purchase, usually including the website name and the type of a given entitlement.Example: "The Leek - 24 Hours Time Pass"

Price

Price object of the purchase.

Show Price object

number

Amount in currency base units.Example: 5000

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

PurchaseStatus

Status of the purchase. Possible values: completed, pending, abandoned.

Metadata

Key-value pairs of custom information associated with the purchase.

EntitlementStatus | null

The customer’s access (if any) as a result of this purchase.

Show Entitlement status object

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

Offering | null

Offering object if user has purchased an offering. null otherwise.

Show offering object

string

ID of the offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string

Description of the offering.Example: "24 Hours Time Pass to The Leek"

EntitlementDetails

Show Entitlement details object

string

The duration of the entitlement as {length}{unit}.Examples:

{
  // 1 year
  "duration": "1y",
  // 2 months
  "duration": "2M",
  // 3 weeks
  "duration": "3w",
  // 4 days
  "duration": "4d",
  // 5 hours
  "duration": "5h",
  // 6 minutes
  "duration": "6m",
  // 7 seconds
  "duration": "7s"
}

boolean

Whether the entitlement is sold on a recurring basis (subscription).

string

The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

Price

Price object of the offering.

Tab

The users tab

Show Tab object

boolean

Whether the tab is in test mode.

Currency

The currency of the tab.

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The total amount of the tab.

Show Total object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The limit of the tab. When reached, the payment will be required.

Show Limit object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Array<Purchase>

boolean

If a purchase required payment, this will be true if payment was successful. false otherwise.

function

Destroy paywall instance. This removes all nodes related to paywall from DOM.

Purchase Button `supertab.createPurchaseButton`

Fill a container element with the Purchase Button

<div id="supertab-button-container"></div>

const supertabButton = supertabClient.createPurchaseButton({
  containerElement: document.getElementById("supertab-button-container"),
  experienceId: "experience.abc",
});

Parameters

Element

required

Container element to render purchase button in. Elements are appended to the container, so original contents are not replaced.

string

required

ID of the purchase button experience created in Business Portal.

object

Key-value pairs of custom information associated with the purchase.

function

Callback function called when user leaves the purchase flow either as a result of successful purchase or cancellation.Returns a promise which resolves with the purchase button summary. See Purchase button summary for more details.

Return Value

A promise which resolves with an object with following properties:

function

Destroy Supertab button instance. This removes all nodes related to Supertab button from DOM.

ExperienceStateSummary

Initial state of the purchase button. See Purchase button summary for more details.

Purchase button summary

Both the returned initialState object and the object passed as an argument to the onDone callback contain the following properties:

Show ExperienceStateSummary

EntitlementStatus | null

Any prior entitlement of the current user. null if user has no prior entitlement.

Show prior entitlement

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

AuthStatus

Current authentication status of the user. Possible values: missing, expired, valid.

Purchase | null

Purchase object if launching the flow resulted in a purchase. null otherwise.

Show purchase object

string

ID of the purchase.Example: "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"

string

ID of the purchased offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string | null

Date and time of the purchase.Example: "2025-04-30T12:00:00Z"

string | null

Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.Example: "2025-04-30T12:00:00Z"

string

A summary of the purchase, usually including the website name and the type of a given entitlement.Example: "The Leek - 24 Hours Time Pass"

Price

Price object of the purchase.

Show Price object

number

Amount in currency base units.Example: 5000

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

PurchaseStatus

Status of the purchase. Possible values: completed, pending, abandoned.

Metadata

Key-value pairs of custom information associated with the purchase.

EntitlementStatus | null

The customer’s access (if any) as a result of this purchase.

Show Entitlement status object

string

The content key of the entitlement.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

boolean

Whether the customer has entitlement to the content key.

string

When the customer’s access will expire.Example: "2025-04-30T12:00:00Z"

string

If this access is a result of a subscription, this will be the date and time when the next billing period starts.Example: "2025-04-30T12:00:00Z"

Offering | null

Offering object if user has purchased an offering. null otherwise.

Show offering object

string

ID of the offering.Example: "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

string

Description of the offering.Example: "24 Hours Time Pass to The Leek"

EntitlementDetails

Show Entitlement details object

string

The duration of the entitlement as {length}{unit}.Examples:

{
  // 1 year
  "duration": "1y",
  // 2 months
  "duration": "2M",
  // 3 weeks
  "duration": "3w",
  // 4 days
  "duration": "4d",
  // 5 hours
  "duration": "5h",
  // 6 minutes
  "duration": "6m",
  // 7 seconds
  "duration": "7s"
}

boolean

Whether the entitlement is sold on a recurring basis (subscription).

string

The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.Example: "site.cf637646-71a4-430d-aaea-a66f1a48a83c"

Price

Price object of the offering.

Tab

The users tab

Show Tab object

boolean

Whether the tab is in test mode.

Currency

The currency of the tab.

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The total amount of the tab.

Show Total object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Price

The limit of the tab. When reached, the payment will be required.

Show Limit object

number

Amount in currency base units.Example: 50

Currency

Show Currency object

string

Currency code.Example: "USD"

string

Currency name.Example: "United States Dollar"

string

Currency symbol.Example: "$"

number

Base unit of the currency.Example: 100

Array<Purchase>

boolean

If a purchase required payment, this will be true if payment was successful. false otherwise.

Example

const supertabButton = await supertabClient.createPurchaseButton({
  containerElement: document.getElementById("supertab-button-container"),
  experienceId: "experience.abc",
  onDone: ({ priorEntitlement, purchase }) => {
    if (priorEntitlement) {
      // User has prior entitlement to the content.
      return;
    }

    if (purchase) {
      if (purchase.status === "completed") {
        // Purchase was completed successfully.
      } else {
        // Purchase was not completed. User may have
        // canceled the payment dialog if purchase
        // required payment.
      }
    } else {
      // User has canceled the flow and did not
      // attempt to purchase the offering.
    }
  }
});

Supertab.js

Experiences

API Reference

Pre-requisites

Initialization

Paywall: `supertab.createPaywall`

Parameters

Return value

Purchase Button `supertab.createPurchaseButton`

Parameters

Return Value

Purchase button summary

Example

​Pre-requisites

​Initialization

​Paywall: supertab.createPaywall

​Parameters

​Return value

​Purchase Button supertab.createPurchaseButton

​Parameters

​Return Value

​Purchase button summary

​Example

Pre-requisites

Initialization

Paywall: `supertab.createPaywall`

Parameters

Return value

Purchase Button `supertab.createPurchaseButton`

Parameters

Return Value

Purchase button summary

Example