In-app messages on a website

A page that calls init shows its in-app messages. There is nothing else to set up.

It works after init

The web SDK asks for the messages waiting for this browser and draws them itself, in a shadow root, so your page's styles and the message's never meet.

import treebars from '@treebars/web-sdk';

treebars.init({ writeKey: '<your-write-key>' });

When a message appears

The SDK asks for messages when a session starts, when the tab comes back after being hidden, and when a page opens. Somebody reading through a site of many pages asks at most once in thirty seconds; a reload always asks.

A message is shown on the event it was set to wait for. One that arrives as the page opens — you published it since their last page — is shown on that same page, provided the answer is back within ten seconds. Later than that it waits for the next page, rather than appear over somebody who is already reading. A page opened in a background tab opens, for this, when it is first looked at. To ask at a moment of your own, call treebars.syncInAppMessages().

Switching it off

Pass inAppEnabled: false. No message is fetched and none is drawn; events are recorded as before.

treebars.init({ writeKey: '<your-write-key>', inAppEnabled: false });

To turn it back on, take that option out — and any setInAppRenderer(null) — and deploy. From 0.5.0 the SDK tells Treebars which it is, so an in-app campaign or template warns you while you write it when a platform it would go to has messages switched off. A site on an earlier SDK says nothing either way, which is not the same as off.

Holding messages over a screen

For something your page shows over everything that no message may cover — a passcode, a checkout it must not lose — call treebars.holdInApp() as it appears and treebars.releaseInApp() as it goes. Nothing is drawn or spent in between, a message already on screen stays, and on release whatever is waiting for this moment is offered. The apps have the same two calls. From 0.7.0.

treebars.holdInApp();     // the passcode screen is up
// …
treebars.releaseInApp();  // and gone

Drawing messages yourself

Hand setInAppRenderer a function and it is given each message in place of the SDK's renderer: the SDK still decides which message and when, and your function draws it and reports what the person did. Call it before init or in the same script as init — the first message of a page is drawn once that script has run, so either order works.

treebars.setInAppRenderer((view) => {
  // view.message is the message; view.tokens its colours and font.
  showMyDialog(view.message, {
    onButton: (button) => view.onClick(button),
    onClose: () => view.onDismiss(),
  });
});

setInAppRenderer(null) draws nothing and keeps fetching, for a page that only reads treebars.inbox; a message that would have been shown is counted as held back in the campaign's report. A nudge is drawn only by the SDK's own renderer, so a page with its own shows none.

A strict Content-Security-Policy

An HTML message runs in a sandboxed frame. Where your policy refuses inline scripts, the SDK draws it in a frame served by Treebars instead, which your policy has to allow:

Content-Security-Policy: frame-src https://frame.treebars.com

If nothing appears

In the order worth checking:

1. The page and the campaign are in the same environment. A page built with a pk_test_ key shows what was published under Test, and only that.
2. The browser had visited before the campaign was sent. A campaign sent once goes to the people Treebars knows at that moment; a browser that first opens your site afterwards is not among them.
3. A minute has passed. A campaign published to everyone is sent within a minute or two. Reload after that.
4. The page is on 0.5.0 or later, and does not pass inAppEnabled: false or call setInAppRenderer(null). The campaign says so while you write it, when your site reports that it has them off.
5. The campaign's report. Sent, fetched and displayed are counted apart, and a message a browser fetched and held back is listed with the reason — a limit, a page rule, a blocked frame.

What a message can do once it is on screen is on HTML in-app messages.