Workflow Hooks

The LoyaltyLion SDK provides the ability for you to hook into various workflows to further customise the user experience.

Overview

A hook is a promise-returning callback function that you provide and that the LoyaltyLion SDK executes when certain hook-enabled events occur.

Hooks enable you to ‘hook into’ certain frontend workflows, giving you an opportunity to make calls to other services, render your own UI, and influence the behavior of the LoyaltyLion SDK.

For example, you may provide a hook for the customers.rewards.claimed hook event that calls a storefront API to automatically add a discount to the cart, or make a call to your own app to trigger fulfillment of a custom reward.

Your hook should return a promise which resolves to an object which contains an action property. The action is a string that informs what the LoyaltyLion UI should do next.

Each kind of hook has its own set of supported actions, depending on the underlying use case and workflow.

Registering hooks

Hooks are registered using the loyaltylion.registerHook method. This method accepts two arguments:

• hookName - string, name of the hooked event to register
• callback - the function to be called when the hooked event occurs

Hooks should be registered once the LoyaltyLion SDK is ready, see below for an example.

Example usage

loyaltylion.on('ready', () => {
  loyaltylion.registerHook(
    'customers.rewards.claimed',
    async ({ claimedReward }) => {
      // do something with the claimed reward here
      if (claimedReward.redeemable.code) {
        await myCustomCartPlatform.setDiscount(claimedReward.redeemable.code)

        myCustomModal.open('Your discount has been applied!')
      }

      return { action: 'hide_claim_modal' }
    },
  )
})

Hook requirements

Your hook must return a response with a valid action within 5 seconds. If it returns an invalid payload or doesn’t resolve in time, the LoyaltyLion SDK uses the default action and proceed as if no hook was registered.

Supported hooks

We currently support the following hooks:

• customers.rewards.claimed

Customer reward claimed

This hook is called after a customer has successfully used their points to claim a reward. It enables you to implement things like automatically applying a reward to a cart if your platform supports this capability.

Callback payload

This hook is called with an object with a claimedReward property matching the schema of our rewards API.

{
  claimedReward: {...} // see claimed reward docs for detailed schema
}

Supported return actions

This action should be indicated by the return of your callback function, e.g.

return { action: 'hide_claim_modal' }

This hook supports two actions:

The show_claim_modal action is used as the default in case of invalid return value or timeout.