Documentation
- Platform Integrations
- Merchant Operations
- Customer Operations
- Marketing & Compliance
Getting Started with Widget
Loading the Widget
In order to use the Clyde widget you’ll first need to include it on any page where a user will be adding product protection. This is best done by loading the script in your page’s <head>, and initializing the Clyde object at the end of the </head><body>. Once the script has loaded you’ll need to initialize it by calling Clyde.init() with an options object that must include your client key alongside any other appropriate options. Once the widget is initialized it exposes a number of functions you can use to interact with the various calls-to-action it provides.</body>
<script src="https://js.joinclyde.com/widget.js"></script>
Using the Widget
Clyde.init(options, callback)
Use Clyde.init() to initialize the widget on your page and register callbacks for certain user interactions. The function takes an `options` object with the following keys accepted:
key (required) (string): your API client key, used for fetching contract info for products.
defaultSelector (string): default css selector for appending Clyde’s product page prompt.
type (string): optionally override the prompt type set in your Clyde Dashboard. Must be 'simple', 'select', or 'list'. For more information on type, review Customizing your Offering.
baseUrl (string): a base URL that requests will be sent to. Use this if you want to use your server as a proxy to load contract information. Be sure to forward request headers.
skipGeoIp (boolean): by default, the client's IP address is checked when fetching contracts in order to only show contracts available in the detected region. Set this option to true to skip this check.
pageKey (string): this option prevents the Clyde object from initializing if the passed-in key corresponds to a location option turned 'off' in your Clyde dashboard. Must be one of 'productPage', 'modal', or 'cart'.
skuList (array): optionally provide a list of SKUs that will be used in an initial contract load when the Clyde object initializes. This is not necessary, but can improve performance when selecting a product because the product's information is pre-loaded.
onShowModal (function): a default callback to be triggered when the modal is shown.
onCloseModal (function): a default callback to be triggered when the modal is dismissed.
onSelectedContract (function): callback to be triggered when a user selects a contract.
The init function accepts an optional callback as a second argument that runs after initialization finishes. You can use this, for example, to call Clyde.setActiveProduct() on the default product on the page.
setActiveProduct(productSku, cb)
setActiveProduct() will load the contracts Clyde has matched to your product. In the case that no contracts are available for the provided product, the page prompt will be hidden. Once a product has been fetched its contracts will be stored in memory on the page, so even if a user is switching between products API requests are kept to a minimum. This function also accepts a callback that will run after the product has been loaded either from memory or from the API.
getSelectedContract()
getSelectedContract() returns the currently selected contract.
getActiveProduct()
getActiveProduct() returns the current active product.
appendToSelector(selector, type, shouldHide)
appendToSelector() appends the product page prompt using the specified selector. If a default selector is specified in init() you don’t need to invoke this function. The type argument can be used to override the type set in init().
appendToSelectorWithSku(productSku, selector, modalCloseCb)
appendToSelectorWithSku() appends a simple prompt with a product SKU pre-selected (if the SKU has available contracts). When the prompt is clicked, a modal prompt displays with the available contracts. The modalCloseCb is a callback that runs when the modal closes. Use this to check for a selected contract and add it to cart if it exists. This function is intended for use on cart/catalog pages where multiple products are shown at once.
showModal(openCb, closeCb)
showModal() displays the Clyde modal. The two optional callback arguments can be used to override the default callbacks that fire when the modal is opened and after this instance of the modal is closed, respectively.
getSettings()
getSettings() returns the call-to-action settings a user has selected in the Clyde dashboard.
checkReady()
checkReady() returns true after init() has finished running.
Implementation Checklist
There are several key steps to implementing the Clyde widget. While your integration will be unique to your website, use the points below as a checklist and/or guide for putting the pieces in place. Here's what a typical integration looks like:
1. Initialize the Clyde object.
See the above init options for what to pass in. You can use the init callback, for example, to run setActiveProduct() with your product's SKU, so a prompt is ready to be shown as soon as possible. See below for an example:
Clyde.init({
key: 'ck_live_my-client-key',
type: 'list',
skuList: ['SKU_XXX', 'SKU_YYY'],
pageKey: 'productPage'
}, function() {
Clyde.appendToSelector('#prompt-container-element');
// Get the product SKU currently active on the page.
var productSku = 'SKU_XXX';
// Set the active product.
Clyde.setActiveProduct(productSku);
});
2. Choose what kind of prompt(s) you want to use:
Product page prompt: A prompt on your page that allows a user to select a contract before clicking your 'add to cart' button.
- There are two types of product page prompt available: "simple" and "select". If you pass in a defaultSelector and one of these types on init, the widget will use that to find an element to append the prompt to.
- You can also append the prompt using appendToSelector() after init.
- When the user selects a contract from one of these prompts, the widget makes the selected contract available via getSelectedContract(). When a user hits "Add to cart", you should check for a selected contract, and if it exists, add a contract to the cart.
Modal prompt: The modal prompt is typically triggered by a user hitting an "add to cart" button. This kind of prompt gives the customer the opportunity to add a protection plan to their purchase before moving on.
- To use this prompt, you can modify your add-to-cart code to first check if the selected product has contracts (e.g. getActiveProduct().contracts.length > 0).
- If it does, call showModal(). You can pass in an on-close callback as the second argument, which runs when the modal closes. In this callback, check if there is a selected contract via getSelectedContract(), add it to cart if it exists, then continue with your normal add-to-cart process.
Cart prompt: Prompts can be added to the cart with the function appendToSelectorWithSku(). This gives your customer one last chance to add a protection plan before checkout.
- To build cart prompts, call appendToSelectorWithSku() once per-item in the cart, passing in the SKU of the item, a selector for where the prompt should be appended, and the callback that runs after the customer clicks "Add protection" or "decline". As in the the modal prompt example, this callback should check if there is a selected contract via getSelectedContract(), and if there is, add it to the cart.
- Note: When the user clicks the cart prompt, the SKU passed in to appendToSelectorWithSku() is used to set the active product.
3. Track the page's active product:
Make sure to call 'setActiveProduct' every time the active product on your page changes. This will ensure that the customer is offered contracts for the product SKU they currently have selected, and will prevent cases of someone adding a contract to their cart that does not match the added product.
Using the Widget on Shopify
If you're using Clyde's Shopify app and the widget for a custom front-end integration, things work a little differently. Shopify partners provide Shopify variant IDs instead of product SKUs when calling `setActiveProduct`, and the return value of `getSelectedContract` includes a `shopifyVariantId`, so you can easily add the right variant to your cart. This also affects the optional `skuList` init option.
Using the Widget on BigCommerce
BigCommerce widget implementations must provide the BigCommerce variant ID instead of product SKU when using functionality that relies on SKU values. You'll also need to build the contract add-to-cart code correctly the ensure Clyde's order processing will work correctly:
Every Clyde contract launched to your shop has three fields:
1. `SKU`: a field with options, each of which defines a variant
2. `Product`: a text field that should be filled in with the name of the covered product, so users can see which contract goes with which contract in their cart.
3. `covered-product-code`, a text field that indicates which product is covered by the contract being added to the cart. This field must be populated correctly in order for Clyde to process the customer's purchase.
- Calling `getSelectedContract` after selecting a contract in a CTA will return the variant id of the contract to add (`getSelectedContract().bcVariantId`), and the value that should go in the custom 'covered-product-code' field when adding that variant to cart (`getSelectedContract().coveredProductCode`).
- You may want to modify your cart theme in order to hide the `covered-product-code` field (if it's visible in your default theme) to prevent user error and customer confusion. Your widget implementation must use the above values correctly in order for Clyde to process orders with contracts accurately.