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 <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 along with 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.
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.
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 either 'simple' or 'select'. For more information on type, review Customizing your Offering
environment (string): the environment you are using. Defaults to 'production'. Pass in 'sandbox' to use Clyde's testing environment while you're getting set up.
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. Requests should be forwarded to and from 'https://sandbox-api.joinclyde.com' or 'https://sandbox-api.joinclyde.com', depending on your environment. 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 false 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() 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() returns the currently selected contract.
getActiveProduct() returns the current active product.
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() 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() 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() returns the call-to-action settings a user has selected in the Clyde dashboard.
checkReady() returns true after init() has finished running.
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:
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.
Product page prompt: A prompt on your page that allows a user to select a contract before clicking your 'add to cart' button.
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.
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.
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.