LoyaltyLion SDK

The LoyaltyLion JavaScript SDK allows shoppers to see and interact with your loyalty program.

The simplest LoyaltyLion UI uses our combined Loyalty Panel component which can be embedded onto a page or opened as a modal on demand. If you need something more customised, there are many smaller components which can be used to construct your own interface.

Customisation

We’ve designed all our components to be easy to style with your own CSS as part of your normal workflow. Every component adopts BEM methodology so it’s easy to target individual elements without worrying about our default CSS doing anything weird.

To isolate our default styles from the rest of the page, we wrap all our components inside a container with id loyaltylion and target this element with our default CSS (class based isolation is also available, see below). Therefore, to target any of our elements with your own CSS you’ll need to ensure your selectors include #loyaltylion. For example:

/* all good */
#loyaltylion .lion-loyalty-panel-sidebar__title {
  font-weight: bold;
}

/**
 * will be ignored, because our default styles apply to the rule:
 * `#loyaltylion .lion-loyalty-panel-sidebar__title`
 */
.lion-loyalty-panel-sidebar__title {
  color: rebeccapurple;
}

Using class-based isolation

We apply a set of ‘isolation’ styles to ensure that our components look good regardless of a theme’s existing CSS. By default, this is implemented by rendering the root of our component trees with an id="loyaltylion" element, allowing us to target our isolation styles using #loyaltylion ... { ... } which enables robust and reliable isolation. This has the potential side effect of rendering more than one element on the page with the #loyaltylion id, which can raise warnings with some web standards validation tools.

If you prefer to use class-based isolation, you can use a configuration option to do so:

loyaltylion.configure({
  useClassIsolator: true,
})

This causes our components to render with a new lion-isolator, and subsequently your CSS customisations need to use this as well. From the example above, this now looks like:

/* instead of #loyaltylion */
.lion-isolator .lion-loyalty-panel-sidebar__title {
  font-weight: bold;
}

Note that class-based isolation is inherently less robust than id based isolation, and using it may require you to implement additional CSS overrides to address any conflicts that arise between your theme's styles and our components.

Previewing class-based isolation

To facilitate easy adoption of class-based isolation, you can enable it for a single pageview by adding a ?ll_use_class_isolator=1 query param. This allows you to try it out and see what additional CSS you may need to apply to address any style conflicts.

Disabling our default styles

It’s possible to prevent our default styles from loading entirely, so you can start from a completely blank slate. To do this, set the disableBundledCSS option to true when you configure the LoyaltyLion SDK:

loyaltylion.configure({
  disableBundledCSS: true,
})

Disabling our default fonts

By default, we load the Source Sans Pro font, when using your own font your should disable ours to avoid loading an unnecessary font. To do this, set the disableBundledFonts option to true when you configure the LoyaltyLion SDK:

loyaltylion.configure({
  disableBundledFonts: true,
})

Indicating your Shopify frontend type

By default, we’ll assume that you’re running on a native Shopify theme, and the SDK uses Shopify frontend APIs such as cart.js.

If you’re running a headless Shopify store, these APIs may not be available. To explicitly configure the SDK not to use these APIs, you can specify the shopifyFrontend configuration option. This turns off some features which depend on those APIs, such as in-cart rewards:

loyaltylion.configure({
  shopifyFrontend: 'unknown'
})