@justeattakeaway/cc-braze-adapter
v0.5.0
Published
The promotion card component of content cards
Downloads
52
Readme
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
| Key | Description | |----------------|-----------------------------------------------------------------------------| | apiKey | the api key for braze | | sdkEndpoint | which is the endpoint provided to the sdk for communication with brazes api | | userId | this is the global user id found inside the JWT | | loggingEnabled | which can be turned on or off to get logging output from braze |
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