Web banners: instructions for developers

Prerequisites To work with web banners, first, they need to be set by the Meiro team: 1. Meiro Events must be implemented.  2. Meiro Events API connection must be set in the Administration/ Settings tab.  3. The Pop up web banners tab must be enabled by the administrator for your user role. 4. For embedded web banners it is required to install  "Element ID" on the website where the banner will be displayed.

General

The evaluation of conditions for displaying banners and the insertion of the banner into the page (if any) happens during the MeiroEvents.track(“pageview”) function call.

If your website is a single-page application and you call this function manually, and if there are any cookie/local storage/GTM conditions, make sure that the relevant cookies etc. are set before this tracking call.

The element containing the banner has a z-index value set to 1000000 (1 million). This includes the overlay (for banners with the position set to “middle”).

 

DOM containers for embedded web banners

To make embedded web banners displayed you have to place some container (DOM element) with a unique id into your website page,
eg. <div id=”meiro-embedded-banner-sidebar”></div> so a user can fill this id in Meiro Business Explorer (embedded web banners tab) as a web banner position. There can be multiple web banner containers at different places on a single page.

 

HTML banners

The HTML banners are inserted into an iframe element. This means that the CSS from the main page is inaccessible within the banner, and vice versa.

If you want to access the window object of the main page from within the banner HTML code, you can access it under window.parent, and you can access the Meiro Events SDK under window.parent.MeiroEvents.

The SDK exposes several methods that can be used inside the HTML banner code:

MeiroEvents.closeWebBanner(closePopUpWebBanner(): void

Closes the current banner.pop up banner. Can be used if you implement your own close button.

 

MeiroEvents.getWebBannerId():

string

Returns

the id of the current banner. Can be used for tracking custom events inside the banner or to retrieve stored HTTP responses.

MeiroEvents.getWebBannerHttpResponses(bannerId: string): Array<{ url: string, data: any }>

If the conditions for the banner included any HTTP request conditions, the responses will be stored in an array of objects. Each object will contain a url property with the URL to which the request was made, and a data property containing the parsed body of the response.   Remember: The order of the responses in the array is not guaranteed to be the same as the order of the conditions in the condition builder! Examine the URL to differentiate between multiple HTTP conditions.   Use the getWebBannerIdwindow.frameElement.getAttribute('data-bannerid') method to get the id to pass as an argument to getWebBannerHttpResponses.getWebBannerHttpResponses.

 

MeiroEvents.goToWebBannerUrl(url: string)string, bannerId): void.void

TracksTransitions user to the web_banner_clickgiver eventURL in Meiro Events Emits(if the meiro:bannerclick DOM event If the meiro:bannerclick event is not preventedprevented) inand yourtracks the web_banner_click event listener,in transitionsMeiro Events. It also emits the meiro:bannerclick DOM event.

Get banner id from within HTML banner code

SDK no longer supports obtaining banner id by its own interface because it’s no longer possible after the implementation of embedded web banners. There can be several banners at the same time on the page and it’s not obvious which one you may be asking for.
From now on use the window.frameElement.getAttribute('data-bannerid') method to theget givenbanner URL.id.

You can also track events as usual via MeiroEvents.track(...) from inside the banner.

Cookie, local storage, and Google Tag Manager data type handling

The values retrieved from cookies/storage/GTM are handled in the following way for the purposes of condition evaluation:

Boolean	The operators are yes and no. For yes, the condition will pass if the value is true, 1, or any of the strings true, True, or 1. Similarly, for no, the condition will pass if the value is false, 0, false, False, or 0.
DateTime / Relative DateTime	The value is passed as an argument to the JavaScript Date class constructor before comparing it with the provided value. If the result of the conversion is an invalid date, the condition will always fail.   Values retrieved from cookies and local storage are always retrieved as strings. If you store a JavaScript UNIX timestamp (number of milliseconds), this number will be retrieved as a string and parsing to Date object will fail. Please make sure to store timestamps in cookies and local storage in a format that will be correctly parsed when passed to the Date constructor (i.e. new Date(timestamp)). We recommend the ISO format.
Number	The value is converted to the JavaScript number type before comparison.
String	The value is converted to the JavaScript string type before comparison.

Display web banner on any user iteractioninteraction by id

Display web banner by id on any user iteractioninteraction by calling a special SDK method showBanner.

MeiroEvents.showBanner(showPopUpWebBanner("banner-id-here");

Web banner id can be found in the URL cdp.meiro.youracount/personalization/web-banners/id_is_here

e.g. for web banner URL https://cdp.meiro.your account/personalization/web-banners/eacf4043-ec65-4c30-939e-87c2ce19ac40

ID will be: eacf4043-ec65-4c30-939e-87c2ce19ac40

Remember: If a web banner has set the HTTP request trigger condition, the method getWebBannerHttpResponses will return an empty array as the request will not be executed. Keep it in mind when using response data in the banner. 

Capturing custom DOM events

The SDK triggers DOM events for each banner action, namely show, click (image banner only) and close. The events can be captured by implementing event listeners into your code:

document.addEventListener("meiro:bannershow", (event) => {...do whatever you want...})

Event names: meiro:bannershow, meiro:bannerclick, meiro:bannerclose

Each event holds banner data in the following structure accessible under event.detail property:

{
  type: "show" | "click" | "close",
  bannerId: "some-banner-id",
  bannerName: "Some banner name",
  // url is present only in the meiro:bannerclick event
  url: "https://www.example.com"
}

The meiro:bannerclick event is followed by an immediate transition to the destination URL. If you want to perform some task before the transition (e.g. log the event into your own event-tracking system), call event.preventDefault() in your event listener; this will cancel the transition. When you're done, use event.detail.url property to make the transition manually.