Merchants use many different apps to fulfill their business needs. Apps are often built in isolation and do not work well together. Merchants do not care about technical complexities and rightfully expect apps to be seamless working together. We built Incentives with this philosophy in mind. Below are some configuration options and hooks to for you to integrate an app with ours.
Configuration options
To start using these configuration options, you'll need to open up your theme's code editor. Navigate to /admin/themes, click “Actions” on the copy of our theme, and then click “Edit code”.
You’ll be looking for the theme.liquid file in your layout folder. At the bottom of that file, start by adding this:
<script>
window.ObsidianConfig = {
};
</script>
Inside the object is where you'll be able to add your configuration options.
addToCartSelector
By default, our app looks for a Add to cart button inside your product form. Sometimes you might have it outside of the form but still want our app to trigger properly — maybe a sticky cart on mobile or an additional Add to cart at the bottom of the page.
<script>
window.ObsidianConfig = {
addToCartSelector: '.your-selector'
};
</script>
disabledUrls
If you want to disable the app on specific pages, you can pass in the URLs as an array. This prevents the add to cart button from opening the cart drawer, but leaves the app enabled if a user clicks the cart link in the header.
This URL format will work for multi-language sites as well.
<script>
window.ObsidianConfig = {
disabledUrls: ['/collections/build-your-own-bundle', '/products/handle']
};
</script>
maxUpsells
You can limit the number of upsells manually. Default is a max of 4.
<script>
window.ObsidianConfig = {
maxUpsells: 1
};
</script>
integrations
By default, we automatically detect other apps and integrate with them when we can. You can disable auto-integration by setting autolink to false.
<script>
window.ObsidianConfig = {
integrations: [
{id: 'product-customizer', autolink: false},
],
};
</script>API events
Next, we built an event-based API for you to hook into Incentives. Events are an easy mechanism for apps to talk to each other. We have events that your app can listen to and events that your app can dispatch for Incentivs to take an action. Knowing both apps and using a combination of both will make for the best integration.
obsidian:upsell:open
Trigger this event to open the cart drawer.
document.dispatchEvent(
new CustomEvent('obsidian:upsell:open')
);
obsidian:upsell:close
Trigger this event to close the cart drawer.
document.dispatchEvent(
new CustomEvent('obsidian:upsell:close')
);
obsidian:upsell:refresh
Trigger this event to force fetch a new cart.
document.dispatchEvent(
new CustomEvent('obsidian:upsell:refresh')
);
obsidian:upsell:initialized
Subscribe to this event to know when Incentivize is initialized and ready.
document.addEventListener('obsidian:upsell:initialized', () => {
// your code
});
obsidian:upsell:opened
Subscribe to this event to know when the cart drawer has opened.
document.addEventListener('obsidian:upsell:opened', () => {
// your code
});
obsidian:upsell:closed
Subscribe to this event to know when the cart drawer has closed.
document.addEventListener('obsidian:upsell:closed', () => {
// your code
});
obsidian:upsell:updated
Subscribe to this event for any updates to the cart. A custom object is returned with information about the cart. Note, this is not the same as Shopify's default cart object.
document.addEventListener('obsidian:upsell:updated', (evt) => {
// evt.detail contains some helpful cart information:
// evt.detail.count - number of items in cart
// evt.detail.cents - total cart value in cents
// evt.detail.currency - cart's currency ISO code
});
obsidian:upsell:quantity
Subscribe to this event for any quantity changes in the cart.
document.addEventListener('obsidian:upsell:quantity', () => {
// your code
});
As more use cases come up, we'll expand this list. If there's something you'd like to see added, please reach out to us here.