Embedding Checkout
You can embed our checkout experience on your website easily by using our integration script.
Embedding Options
The embedding scripts supports multiple operations as explained below. Depending on the operation, there are different number of arguments and each argument positions might mean something different.
All configurations always start with the operation name as the first argument (i.e sb({operationName}, ...{args})
)
Initializing the SiteId
(Required)You need to initialize the embedding script by specifying the "Site Id". You can do this by using the
siteId
operation as follows:
sb("siteId", "{your_siteId})");
Where:
{your_siteId}
is the case-sensitive site id you want to use, which contains the plans you need to attach. Your Subsbase Admin Portal link is in the form ofhttps://{siteId}.subsbase.io
Customizing Theme
(Optional)You can customize the primary color which is used in multiple parts of the checkout experience. You can do this by using the
theme
operation as follows:
sb("theme", "{theme})");
Where:
{theme}
is the primary color you want to use in hex format (i.e#FFFFFF
)
Adding a Callback
(Optional)When the payment process does not include redirection or if no payment is required, you can specify a certain action to happen, whether to communicate with your backend, trigger a redirection etc.
You can do this by using the
callback
operation as follows:
sb("callback", { actionToPerform });
Where
{actionToPerform}
is the action you want to perform after signup, written in Javascript. This argument could reference a globally available function. The function would receive and event having all signup details (i.e. InfoFields, CustomFields, PlanCustomization, etc.)- Example action
e => console.log("signup result:", {e})
This operation should exist only once, adding it more than once can lead to unexpected behavior.
Plan Checkout
There are two ways to integrate the checkout experience: (At least one is needed, unless plan picker is used)
- Attaching the subscription plans to clickable elements on your page
- Attaching the subscription plans inline to container elements
You can do this by using the attachPlan
or inlinePlan
operations as follows:
Attaching the subscription plans to clickable elements
sb(
"attachPlan",
"{planCode}",
"{clickableElementReference}",
["class|id"],
["{attachEvent}"]
);
Where:
{planCode}
is the case-sensitive plan code that needs to be attached. You define the 'Plan Code' while creating it{clickableElementReference}
is either the value of the class name or id added to the clickable element on which you want to attach a plan. If the clickable element reference is aclass
and placed on multiple elements, all elements will open the same plan."class|id"
should be either"class"
or"id"
. If not specified, default value is"id"
"attachEvent"
is a case-sensitive event name on which to trigger the checkout overlay. The event name has to be a valid HTML DOM Event, you can find more here and here If not specified, default value is"click"
Attaching Plan using Element's ID
Example
If you have the following element and want to attach it to a plan whose code is pro-plan
:
<button id="pro-plan-btn">Pro Plan</button>
You can use the following to attach using the id
sb("attachPlan", "pro-plan", "pro-plan-btn", "id");
Attaching Plan using Element's Classname
If you have the following element and want to attach it to a plan whose code is pro-plan
:
<button class="pro-plan-btn">Pro Plan</button>
You can use the following to attach using the class name
sb("attachPlan", "pro-plan", "pro-plan-btn", "class");
Attaching the subscription plans inline to container elements
In addition to the previous method of integrating the checkout experience, you can also inline the checkout experience in a page of your own by replacing the operation name attachPlan
by inlinePlan
to use the Inline Checkout Experience. This creates an iFrame element and injects it to the provided container element.
sb("inlinePlan", "{planCode}", "{containerElementReference}", ["class|id"]);
Where:
{containerElementReference}
is the provided container element reference, adiv
as an example."class|id"
should be either"class"
or"id"
. If not specified, default value is"id"
Setting Success Redirect Url
(Optional)Sometimes you need to have the checkout experience automatically redirect to your website after a successful checkout. You can do this by using the
queryParam
operation as follows:
sb("queryParam", "redirects[success]", "{url}");
Where:
"{url}"
the url you need to redirect toThis is an optional operation, and you can use it as many times as needed. Duplicated params might cause unexpected behavior.
Pre-filling Info Fields and Custom Fields
(Optional)Sometimes you need to attach some custom fields to the checking out clients (visible in the Subsbase Admin Portal) or pre-fill any of the info fields in the checkout experience. You can do this by using the
queryParam
operation as follows:
sb("queryParam", "{param}", "{value}");
Where:
"{param}"
is the parameter you wish to pre-fill/attach"{value}"
is the value you need to specify for that particular parameter
Pre-filling info fields
To pre-fill an info field the parameter should be infoFields[{fieldName}]
. For example, to pre-fill the name
field with the value John Doe
you would use:
sb("queryParam", "infoFields[name]", "John Doe");
Please note that
fieldName
is case-sensitive and should match the field name you chose while creating the plan. This will work on any field you have configured on your plans.
Prevent the user from editing info fields
You can make info fields uneditable by setting the disableInfoFields
parameter value to true
as shown below:
sb("queryParam", "disableInfoFields", true);
Pre-filling custom fields
To pre-fill an info field the parameter should be customFields[{fieldName}]
. For example, to attach a userAgent
custom field with the value navigator.userAgent
you would use:
sb("queryParam", "customFields[userAgent]", navigator.userAgent);
Setting Customer Identifiers
By default, a random identifier (customerId
) is automtically generated while creating a new customer that signs up. In some cases, it is needed to pre-set the customer identifier (customerId
) to match pre-existing info in your system or to follow a certain convention. In this case, you need to supply the desired customer for each customer as a pre-filled custom field as discussed above. The 'customerId` key is to be used as shown below:
sb('queryParam', "customFields[customerId]", {desired-customerId})
Putting it all together
Put the below script before your website's closing head tag </head>
.
<script>
(function (d, o, s, a, m) {
a = d.createElement(o);
m = d.getElementsByTagName(o)[0];
a.async = 1;
a.defer = 1;
a.src = s;
m.parentNode.insertBefore(a, m);
})(document, "script", "https://embed.subsbase.com/sb.min.js");
window.sb =
window.sb ||
function () {
(sb.s = sb.s || []).push(arguments);
};
sb("siteId", "{your_siteId}"); // Required
sb("theme", "{hex-code}"); // Optional. example: sb('theme', '#20407d')
sb("callback", (e) => console.log("signup result:", { e })); //Optional
sb(
"attachPlan",
"{planCode}",
"{clickableElementReference}",
["class|id"],
["{attachEvent}"]
); //At least one is required. can be repeated
sb("queryParam", "redirects[success]", "{url}"); //Optional
sb("queryParam", "{param}", "{value}"); // Optional. can be repeated.
sb("queryParam", "disableInfoFields", true); // Optional.
</script>