Pop-up and native banners: instructions for developers
|
Prerequisites To work with on-site personalization, first, they need to be set by the Meiro team: 1. Activation of the endpoint in the Meiro Events (ME) system should be implemented in order to collect events. 2. Meiro Events API connection must be set in the Administration/Configurations/Settings tab. 3. Channels/Web banners tabs must be enabled by the administrator for your user role. 4. For native banners, it is required to place a DOM element (or multiple elements) with the corresponding ID in the HTML code of 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 native banners
Meiro Events will search for any elements that have the specified ID in the following order:
- As the
idattribute, for example<div id="some-container-id"></div>. If none are found, - As the
data-containeridattribute, for example<div data-containerid="some-container-id"></div>. If none are found, - As a CSS
classname, for example<div class="some-container-id"></div>.
Remember: If the id attribute is used, only the first element with the given ID will display a banner. If the data-containerid attribute or classname is used, the same banner will be displayed in all found elements.
Remember: Any existing content of the container element will be removed before the banner is inserted.
HTML banners
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.closePopUpWebBanner(): void |
| Closes the current pop up banner. Can be used if you implement your own close button. |
MeiroEvents.getWebBannerHttpResponses(bannerId: string): Array<{ url: string, data: any }> |
|
If the conditions for the banner include 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 |
MeiroEvents.goToWebBannerUrl(url: string, bannerId): void |
Transitions user to the giver URL (if the meiro:bannerclick DOM event is not prevented) and tracks the web_banner_click event in Meiro Events. It also emits the meiro:bannerclick DOM event. |
Get banner id from within the HTML banner code
SDK no longer supports obtaining banner id by its own interface because it’s no longer possible after the implementation of native 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 get banner id.
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 For Similarly, for |
|
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 pop-up banner on any user interaction by ID
MeiroEvents.showPopUpWebBanner("banner-id-here");
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"
}