@justeattakeaway/cc-braze-adapter v0.5.0

Braze Adapter

Summary

This package is used to supply braze content cards to the frontend website. The package is built in typescript and is the replacement for the older adapter contained in the fozzie components repository.

index.ts is the entry point for the package and contains the main adapter function brazeAdapter which conforms to the interface Adapter. This interface is used to ensure that all adapters conform to the same pattern so that when used together can be looped over within the consuming application.

The brazeAdapter function contains 4 parameters

The brazeAdapter function returns an object that contains 3 functions initialise, handleCardClick and handleCardView . It also returns the source so the consuming application knows which adapter returned which cards.

Before returning the object the initialize method from braze sdk (note this is different from the initialise function) is called with api key and sdk endpoint.

initialise

The initialise function has 3 parameters filters, callback and errorCallback.

Filters (filters) are to allow the consuming application to further filter down the cards returned from braze. Put simply they are functions that take cards and return cards or an empty array. These get processed by the pipe function after the removeDuplicateContentCards method is called.

Callback (callback) is the function supplied to be called when cards are returned with the cards returned as a parameter of this function. The consuming application would handle the response from this callback to display the cards.

Error callback (errorCallback) is called when no cards are returned.

Inside the initialise function we call requestContentCardsRefresh method from brazes sdk, this ensures that we always get the latest up-to-date content cards returned.

Right after we then call subscribeToContentCardsUpdates braze method to listen for when content cards are received. Inside this method we transform the cards into a usable format using the transformCardData, this function essentially creates an object representing each card for each card returned from braze.

After this the cards are filtered and returned via the passed callback. After the subscribeToContentCardsUpdates function we call the changeUser method to tell braze which user ID is using the session, then finally we open the session by calling the openSession method.

handleCardClick

The handleCardClick function allows us to track when users click on any of the content cards. It uses the provided cards ID, which will come from the consuming applications call of handleCardClick, we then call the braze method logCardClick to log the event with braze. Afterwards requestImmediateDataFlush is called to ensure that events are not logged twice.

handleCardView

The handleCardView function allows us to track impressions of cards so that we know if a card has been viewed by the user. Here we take a slightly different approach than above by pushing impressions onto an array, then calling a function to process this array of impressions. That function call is debounced to reduce loads and requests to the braze API.

Installing the Adapter

To install the package run one of the following:

yarn add @justeattakewaway/cc-braze-adapter

npm install @justeattakewaway/cc-braze-adapter

You will also need to install the peer dependency of @braze/web-sdk:

yarn add @braze/web-sdk

npm install @braze/web-sdk

Instantiating the Adapter

To use the adapter you first have to call the function with an Object containing following parameters

{
    apiKey: "THIS IS THE BRAZE API KEY",
    sdkEndpoint: "ENDPOINT FOR BRAZE SDK",
    userId: "THE GLOBAL USER ID"
}

Example adapter call:

import brazeAdapter from "@justeattakeaway/cc-braze-adapter";

const adapter = brazeAdapter({
  apiKey: 'THIS IS THE BRAZE API KEY',
  sdkEndpoint: 'ENDPOINT FOR BRAZE SDK',
  userId: 'THE GLOBAL USER ID'
});

Using the adapter

Getting Cards

Once the adapter function has been called you then need to do the following to use the adapter. Callback have been used instead of promises as cards maybe returned more than once (updates to cards return if braze gets updates). This is something that you should factor into integration.

adapter.initalise(
  [], // filters
  (cards) => {
  // do somthing with cards
  }, (error) => {
  // do somthing with errors
  }
)

Getting Adapter Source

The adapter source can get obtained by using the source attribute on adapter.

adapter.source