Call integrations in an experience

This is for:

Developer

You can execute an integration directly from a Qubit Experience. This will allow your experience to perform advanced tasks such as retrieving information from external APIs, including authenticated endpoints, or schedule actions to be executed at a later point in time.

Linking your integration to an experience

To use an integration within an experience, we first need to link them together.

If you haven’t created an experience yet, you can learn about that here.

Step 1

Select Experiences from the side menu and open the experience you want to link to an integration

Step 2

Select Settings and then Edit in the Integrations card. Then select Add new integration and choose one from the list of your released integrations. Finally, select Save to commit your changes

Note

You can only link Integrations that have been released.

Integration API

Qubit’s Experiences come with a helper function that instantiates an Integration API, allowing you to easily interact with a linked integration. This function can be accessed through the options object provided to both the triggers.js and variation.js files, as shown in the following example:

// variation.js
module.exports = function variation (options) {
  const integration = options.integration('my-integration')
}

// triggers.js
module.exports = function triggers (options, cb) {
  const integration = options.integration('my-integration')
  cb(true)
}

Executing integrations immediately

Here is a example that will notify you on slack whenever someone spends over £100:

const md5 = require('md5')

module.exports = function variation (options) {
  const integration = options.integration('slack')

  // Wait for ecUser QP event so we have the user's email address
  options.uv.once('ecUser', (userEvent) => {

    // The key will be used to rate limit the number of executions per user
    const key = {
      // Hash the user's email so we don't expose PII
      email: md5(userEvent.user.email)
    }

    // Wait for ecBasketTransactionSummary event so we
    // know when someone has completed a purchase
    options.uv.on('ecBasketTransactionSummary', (transactionEvent) => {

      const { currency, value } = transactionEvent.basket.total

      if (currency === 'GBP' && value > 100) {

        // The payload passed to the integration
        const payload = `A user has just spent £${value}!`

         // Passing through the key allows the integration to
         // rate-limit the number of executions
        const options = { key }

        // Execute function returns a promise
        integration.execute(payload, options)
          .then(() => {
            options.log.info('Successfully pinged slack!')
          })
          .catch(options.log.error)
      }
    }).replay()

  }).replay()
}

Executing integrations at a later date

Integrations can also be scheduled to be executed in the future. We will discuss this in detail in Scheduling Integrations.