Choose your backend SDK
Don’t see an SDK in your preferred language? Let us know as we might already support it.
Step 1: Install the Bolt Embed Script
To use Ignite, install the Bolt Embed Script in the head of all your pages.
Script Options
<!--Place this inside your <head> tag-->
<script
id="bolt-embed"
type="module"
src="{BASE_URL}/embed.module.js"
data-publishable-key="{your-bolt-publishable-key}"
async
></script>
Base URL
Publishable Key
Initialize the Bolt Client
The Bolt client must be initialized before using any components.
// Consider wrapping this code in a reusable function
if (Bolt != null) {
initBolt()
} else {
document.head.querySelector("#bolt-embed").addEventListener("load", initBolt, { once: true });
}
function initBolt() {
const boltPublishableKey = YOUR_KEY;
Bolt.initialize(boltPublishableKey);
// start using Bolt
}
NOTE
Because you’re loading the Bolt ignite script as an async external package, the timing of when the script loads and the execution of your scripts is not guaranteed. So thats why you need to check and see if the Bolt global client object exists first. Otherwise, wait for the script to load before usage.
Step 2: Add the Bolt Login Modal
The Login Modal is how Bolt authenticates shoppers. This component should be added anywhere a shopper enters their email address on your site.
Common Placements
This component should be attached to all email fields, and it will automatically detect emails typed into them. This is called Automatic Email Detection.
If an email is recognized as a Bolt Account, they are prompted to input a one-time verification code (OTP) into the Login Modal or use a Passkey.
Implementation
Start by initializing Bolt with your publishable key.
Create the login modal and attach it to your email field.
<script>
async function initBolt() {
const loginModal = Bolt.create("login_modal");
await loginModal.attach("#email-form-group", { context: "checkout" });
Bolt.on("login_succeeded", (loginSuccessResponse) => {
// Use the results to call the Bolt OAuth endpoint in your backend
});
Bolt.on("login_failed", (loginFailResponse) => {
// Error means the user either dismissed the modal, or there was an error
});
}
</script>
<div id="email-form-group">
<input type="email" />
</div>
interface LoginSuccessResponse {
email: string;
result: {
authorizationCode: string;
scope: string;
state?: string;
}
}
interface LoginFailResponse {
email: string;
result: Error;
}
The Login modal will automatically pop up when a Bolt-recognized email is entered. When the proper credentials is entered, login will be completed and the event login_succeeded and login_complete (success state) will be fired.
The authorization code received from the Login Modal will enable your store to receive the necessary OAuth access tokens. These OAuth tokens will provide your store access to Bolt Account APIs. To enable your store to access Shopper Account data, see the OAuth reference for more information.
The store frontend should send the authorization code to your store backend and exchange the authorization code for the appropriate OAuth tokens using the OAuth Token endpoint.
Take careful note of handling successful authorization. You should only use authorization results once.
Implement Passwordless Forgot Password Flows
Add the Login Modal to your Forgot Password flow to save shoppers the hassle of recovering or resetting their password.
If a shopper forgets their password, your site might have a “Forgot Password” button to direct them to reset their password. Improve this experience by allowing them a chance to do passwordless login instead.
Placement
Attach this to your forgot password button in all of your sign in screens.
Implementation
<script>
async function initLogin(customerEmail) {
// Same code as above...
Bolt.on("forgot_password_continue", ({ context }) => {
// Proceed to your normal Forgot Password flow
});
}
</script>
<div id="email-form-group">
<input type="email" />
<button type="button" id="forgot-password">Forgot password</button>
</div>
If the shopper completes the Passwordless Forgot Password flow, a login_success event will fire. Otherwise, listen to forgot_password_continue event to proceed to reset password the shopper’s password as normal.
Additionally, if your shopper enters their passowrd incorrectly more than once, launch the login_modal to allow them to access their account without resetting or recovering their password.
Step 3: Add the Bolt Login Button
The Bolt Login Button is used to offer shoppers a quick and passwordless signin experience at multiple points during the shopping journey, including during account registration, account login, and checkout. Different variations of this button will appear depending on the login context.
On Sign In and Account Registration Pages
The login button will automatically mount below email fields that you have attached the Login Modal to if you used the Login modal with the default settings (autoDetectEmail is enabled by default).
Alongside Checkout Steps
The Autofill button is a variation of the Login button that allows the shopper to launch the Login modal at any point in checkout (dependent on your placement of the button).
INFO
Even when mounted, the Autofill Button button only appears if a shopper is recognized, but they declined to sign in at an earlier step.
Placement
Mount this component to an element in the top-right corner of checkout steps, specifically after the Payment step.
Implementation
To enable, call mountPasswordlessLoginButton whith the shopper email and a query selector target, which specifies where to mount the button.
await Bolt.getComponent("login_modal").mountPasswordlessLoginButton(
shopperEmail,
"#autofill-button-container",
"checkout"
);
Step 4: Add the Bolt Signed in Status Banner
About
The “Signed in with Bolt” button indicates to the shopper that they have successfully signed into your store and Bolt via their credentials and may now enjoy the benefits of their accounts. When clicked, this banner will display information about having a Bolt account.
Placement
Place this button near the top of your Checkout pages to indicate to the shopper they are signed in with Bolt.
Implementation
const loginStatusComponent = Bolt.create("logged_in_with_bolt");
await loginStatusComponent.mount("#logged-in-with-bolt-container");
Step 5: Implement API Requirements
To ensure seamless communication between your store and Bolt, there are 4 APIs to build and modify.
A successful implementation of Bolt Ignite integrates two categories of API requirements. These types of APIs work together to facilitate seamless communication between Bolt and your store.
- Merchant API requirements: Merchant-hosted endpoints Bolt calls get and update shopper data within your system.
- Bolt API Requirements: Bolt-hosted endpoints that your store will use to get and update data from Bolt.
Implement the Merchant Callback APIs
The Merchant Callback API is a custom implementation that you must build on your cart platform, that Bolt will send requests to in relation to as part of the shopper lifecycle.
Build the Get Account Endpoint
Build the Upsert Account Endpoint
Call Bolt Login APIs
We’ll only highlight the most important API endpoints to get you running, but you should refer to our full API documentation for more information.
Build the OAuth Login Endpoint
Build the Authorize Endpoint
Configure Shipping Restrictions (optional)
Step 6: Add the Bolt Payment Field Component
Use our customizable Payment Fields for Bolt’s out-of-the-box credit card tokenization.
About
Add payment fields to your store’s front end to leverage Bolt’s out-of-the-box credit card tokenization and enable Bolt account creation. Follow our Component Style Guide to completely customize this component’s inputs to match your site.
Implementation
Mount the payment fields component at the payment step of your checkout:
<script>
const paymentComponent = Bolt.create("credit_card_input");
paymentComponent.mount("#credit-card-fields");
document.querySelect("#submit-payment").addEventListener("click", () => {
const tokenize = await paymentComponent.tokenize();
// store these results for the final authorize payment
});
</script>
<section id="payment-section">
<div id="credit-card-fields"></div>
<button id="submit-payment">Continue</button>
</section>
Then, call paymentComponent.tokenize() when you are ready to retrieve a token for the entered payment information. It contains all the info necessary to populate the payment_method field in the Payment API.
Step 7: Add the Account Creation Checkbox
Add Bolt’s Account Creation Checkbox to the payment step of your checkout process to increase account creation back to your customer database and Bolt’s Shopper Network; this ensures that your shoppers gain access to Bolt’s One-Click Checkout on subsequent visits to your store.
About
When a shopper is not using one-click checkout and does not have a Bolt account, you should render Bolt’s account creation checkbox to collect their consent to create a Bolt account and store account, if applicable. If they accept, this enables a one-click checkout experience the next time they return to your store.
Shopper Experience
During checkout, shoppers without a pre-existing Bolt account have the option to opt out of creating one. Bolt provides an embedded component for collecting consent and displaying terms and conditions.
Implementation
Mount the checkbox at your payment or review step of your checkout.
const shouldCreateBoltAccount = true;
const accountCheckboxComponent = Bolt.create("account_checkbox", {
merchantName: "ABC Store",
defaultValue: shouldCreateBoltAccount,
});
accountCheckboxComponent.mount("#payment-section");
accountCheckboxComponent.on(
"change",
(checked) => (shouldCreateBoltAccount = checked)
);
You can build logic to determine the visibility of the checkbox based on whether the shopper is logged into their Bolt account as well as whether their email address is already associated with a Bolt account. For example:
const shopperEmail = ""; // This is the email the shopper entered during checkout
let hasBoltAccount = false;
let isSignedIntoBolt = false;
Bolt.on("account_check_complete", ({email, result}) => {
hasBoltAccount = email === shopperEmail && result;
}, { replayLast: true });
Bolt.on("login_succeeded", ({email}) => {
isSignedIntoBolt = email === shopperEmail;
}, { replayLast: true });
Bolt.on("logout", () => {
isSignedIntoBolt = false;
});
function onPaymentStep() {
if (!hasBoltAccount || !isSignedIntoBolt) {
accountCheckboxComponent.mount("#payment-section");
}
}
When calling Bolt’s Payment API
-
Pass the
create_accountvalue as part of the guest payment request. -
For logged in shoppers, this field is not present. Instead, use the logged in payment which expects an OAuth token and the shopper’s ID.
In the sample code, adding { replayLast: true } allows you to get results from the last login event. This is useful if you have a single page application with hot reloading. For example, you wish to conditionally show a profile widget based on if the user is Bolt logged in or not. You can rely on the login event as opposed to writing your own state management for Bolt.