@justeattakeaway/cc-braze-adapter/README.md

The promotion card component of content cards

# 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

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

Example adapter call:

```js
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.

```js
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.

```js
adapter.source
```