You can ask Ometria for an overlay at a moment you choose, such as when a shopper clicks a button, instead of only when the page loads. Your web team calls one JavaScript function, and you can send tags with the call to pick which overlay comes back.
Before you start
- The Ometria JavaScript tracker must be on your site, with overlays turned on.
- Give the overlay you want to show a tag. Open the overlay, go to Display and timing and choose or create a tag. Tags are set per version. See Overlay tags.
- Use a tag name that only this overlay uses, so you know which overlay will show.
- Set the overlay to show on page entry with no delay, so it appears as soon as your code calls it.
How it works
Your code calls ometria.overlay.fetchAndDisplayOverlay(). Ometria checks your live overlays and shows the one that matches, in the same way it does when a page loads.
- The overlay still follows its usual settings in Ometria, such as device, store, page URL, page views and how often it shows.
- The overlay also follows its display timing. If it is set to show when a shopper is about to leave the page, the call sets up that trigger instead of showing it straight away. If it has a delay, it waits for the delay first.
- Overlays without any tags, and overlays set to show everywhere, match every call. If one of them also fits the page, it can show instead of your tagged overlay.
- Only one overlay shows at a time. If an overlay is already showing, or a mini overlay from earlier in the shopper's visit is waiting, the call does nothing.
- If nothing matches, nothing shows and no error appears on your site.
- Impressions, sign ups and clicks on live overlays are counted in your overlay reports as normal.
data-overlay-init="manual"). See Setting tags for overlays in our developer docs.Show an overlay
Pass the tag of the overlay you want inside an object:
ometria.overlay.fetchAndDisplayOverlay({ tag: 'size-guide' });
You can send more than one tag. An overlay matches if it has any of them:
ometria.overlay.fetchAndDisplayOverlay({ tag: ['size-guide', 'new-customer'] });
If you call the function with no tag, Ometria uses the tags already set on the page. In manual mode, these are the tags you set with setTag or setTags.
ometria.overlay.fetchAndDisplayOverlay();
fetchAndDisplayOverlay apply to that call only. In manual mode, they are not added to the tags you set with setTag or setTags.Options
| Â | ||
| Option | Type | What it does |
tag |
Text, or a list of text | Optional. The tag or tags to match for this call. Each tag must be 1 to 50 characters. If any tag is empty or too long, the call does nothing. |
pageViewNumber |
Number | Optional. The page view number to use for this call, for overlays set to show after a number of page views. It doesn't change the shopper's real page view count. Leave it out to use their current count. If it isn't a number of 0 or more, the call does nothing. |
Examples
Show an overlay when a shopper opens the size guide
document.querySelector('#size-guide-button').addEventListener('click', function () {
ometria.overlay.fetchAndDisplayOverlay({ tag: 'size-guide' });
});
Show an overlay after a product is added to basket
// Call this from your add to basket success handler
function onAddedToBasket() {
ometria.overlay.fetchAndDisplayOverlay({ tag: 'basket-offer' });
}
Show an overlay after the shopper scrolls down the page
var shown = false;
window.addEventListener('scroll', function () {
var scrolled = (window.scrollY + window.innerHeight) / document.body.scrollHeight;
if (!shown && scrolled > 0.6) {
shown = true;
ometria.overlay.fetchAndDisplayOverlay({ tag: 'scroll-offer' });
}
});
Show an overlay on a single page app after a route change
// Example for a router that emits a route change event
router.afterEach(function (to) {
if (to.path.startsWith('/sale')) {
ometria.overlay.fetchAndDisplayOverlay({ tag: 'sale' });
}
});
Check the tracker has loaded first
If your code can run before the Ometria tracker loads, check the function exists before you call it:
function showOmetriaOverlay(tag) {
if (window.ometria && window.ometria.overlay && window.ometria.overlay.fetchAndDisplayOverlay) {
window.ometria.overlay.fetchAndDisplayOverlay({ tag: tag });
}
}
showOmetriaOverlay('size-guide');
Listen for sign ups and clicks (manual mode)
In manual mode you can add an onEvent function to react when a shopper submits the overlay or clicks its button. It only runs for live overlays. With the standard script, or for an overlay in test or preview, it is ignored without any error.
ometria.overlay.onEvent = function (event) {
// event.type is 'submit' or 'cta_click', event.overlayId is the overlay's ID
if (event.type === 'submit') {
console.log('Overlay ' + event.overlayId + ' submitted');
}
};
ometria.overlay.fetchAndDisplayOverlay({ tag: 'size-guide' });
Test your setup
- To check the overlay before it goes live, open your site with preview. An overlay set to Test only shows in preview, not to shoppers who visit your site normally. Preview ignores how often the overlay is allowed to show, but its tag must still match the tag in your call.
- Overlays in test or preview don't count impressions or sign ups in your reports.
- To see why an overlay did or didn't show, add a cookie named
OMdebugwith the value1, then reload the page and check your browser console. This also shows when a tag or page view number in your call isn't valid. - If your overlay doesn't show, check that it is live, that its tag matches the tag in your code exactly, that its Display and timing settings fit the page, and that the shopper hasn't already seen it as often as it is allowed to show.
Comments
0 comments
Please sign in to leave a comment.