Support

Developer documentation

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 Incentivize 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 Incentivize. 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 Incentivize 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.