Readme: n-exponea

This is a component for managing and including on-site messages from Exponea ("weblayers") in FT.com pages.

It includes:

In the future, it will include:

• Server- and client- side code for correctly including and initialising the Exponea SDK, and allowing it to identify users

NOTE: Exponea messages are not in the Web App.

Ownership

This repo replaces n-messaging-client. It's co-owned by the Customer Products Platforms (inclusion of the Exponea script + templates) and Internal Products Marketing Technology teams (Exponea system e.g. message content, message display rules etc).

Support

For most queries (e.g. "Why isn't my message showing" or "How can I add / alter this message") the first port of call is #ip-martech for engineers, product, marketing etc. The majority of issues seen are usually only addressable by those with access to the Exponea interface i.e. the MarTech team.

Then, if the MarTech team need our help as they they will contact Customer Products and we can support them directly.

Using in FT.com apps

If you need to implement the Exponea SDK in your app, please talk to the Platforms team and Customer Products tech leadership so we can understand your use case and implement appropriate performance testing.

Install the component:

npm install --save @financial-times/n-exponea

Output the SDK script and slot components in the appropriate places for your app:

import { ExponeaMessage, ExponeaSDKScript } from '@financial-times/n-exponea'

// ...in the page head, e.g. using Page Kit's `additionalMetadata`:
<ExponeaSDKScript projectToken={process.env.EXPONEA_PROJECT_TOKEN} />

// ...somewhere in the page header:
<ExponeaMessage slot='top' />

// ...at the end of the body:
<ExponeaMessage slot='bottom' />

During the transition from Ammit messaging, these components should only be output if the exponeaOnsiteMessaging flag is enabled, otherwise you should fall back to outputting the n-messaging-client slots.

Import the message styles into your app's Sass:

@import '@financial-times/n-exponea/main';
@include nExponea();

These styles must come before n-messaging-client, if present.

Add the code to initialise Exponea messages in your client/main.js (only show Ammit/n-messaging-client messages if Exponea isn't available):

import * as nExponea from '@financial-times/n-exponea'

//...once the page has loaded:

if(nExponea.canShowExponea(flags)) {
    nExponea.init()
}
nMessagingClient.init()

Development

This repo currently contains no tests, and there's no way to view the templates locally. To test them, you'll need access to the Exponea dashboard. Create your own "sandbox" weblayer, copy the current template HTML and Javascript over, and use the Exponea preview, then copy your changes back here and commit them.

Updating the templates in Exponea for general usage is a manual process. See the templates readme for more info.

Project structure

• components: JSX templates for outputting message placeholder slots into apps
• templates: HTML and Javascript for Exponea weblayers
• styles: custom, per-message styling

To get custom message styles working in the Exponea preview without copying and pasting the whole of their CSS, this repo is also a valid Origami component, allowing us to insert the custom styles into Exponea using the Origami Build Service.

Tooling

This repo uses Tool Kit for its developer and CI tooling. It includes custom plugins for bundling code with Rollup and publishing the package to npm.

Exponea Cookie

This component adds a cookie that is considered by the Data Governance Council (DGC) a Stage 2 Cookie (see FT Cookie Categorisation Guidelines) on 6th December 2022 (See Data Governance Council minutes). This means that this cookie can be added without checking the FTCookieConsentGDPR cookie.