JavaScript API
Control campaigns from your own code with window.TafseePopup: open and close a campaign, send events to rules, pass visitor values, pause and resume.
Once the script has loaded, window.TafseePopup is available on every page that carries the install code. This article is for developers.
What you need
- The install code on the page. See Installing the code.
- A campaign's ID for calls that name a campaign. It is on the campaign's Details tab, under Campaign ID.
The calls
TafseePopup.show('campaign-id'); // open a campaign now (ignores rules and frequency)
TafseePopup.hide(); // close what is open
TafseePopup.track('tafsee:offer'); // send a named event; a "JavaScript event" rule with that name fires
TafseePopup.track('add_to_cart'); // tell the "Adds to cart" rule something went in the cart
TafseePopup.identify({ email: 'shopper@example.com', plan: 'gold' });
TafseePopup.pause(); // stop automatic triggers
TafseePopup.resume(); // start them again
TafseePopup.reset(); // forget this visitor in this browser
TafseePopup.campaigns(); // [{ campaignId, name, type }], after the script has loaded
TafseePopup.diagnose(); // why each campaign is or is not showing
TafseePopup.simulateExitIntent(); // testing helperOpen and close
- show(id) opens the campaign at once. Rules, frequency limits and the campaign's place in the queue are not checked.
- hide() closes any open popup or bar. Inline campaigns stay.
Send events to rules
- track(name) sends a named event. A campaign with the condition JavaScript event and the same event name then fires.
- track('add_to_cart') feeds the condition Adds to cart on stores whose add-to-cart button the script does not recognise by itself.
Pass values about the visitor
identify({ … }) does two things. An email value prefills the e-mail field of your forms. Every value can be matched by the condition Custom attribute, for example plan is gold. The values are kept in the visitor's browser.
Pause and resume
pause() stops automatic triggers such as time, scroll and exit intent on this page until resume() is called. Use it during a checkout, for example. An explicit show() still opens a campaign.
Forget the visitor
reset() clears what this browser remembers for your website: the visitor id, frequency limits, sign-ups and A/B versions. Open popups are closed.
Read what is on the page
- campaigns() returns the campaigns loaded for this page.
- diagnose() returns, per campaign, whether it shows and why not. The first call fetches the test tools and answers an empty list; call it again a moment later.
Calls before the script has loaded
The script loads without blocking the page, so your own code may run first. Put this small stub above your calls and they are kept and run when the script is ready:
<script>
window.TafseePopup = window.TafseePopup || { q: [] };
['show', 'hide', 'track', 'identify', 'reset'].forEach(function (m) {
TafseePopup[m] = TafseePopup[m] || function () { TafseePopup.q.push([m, [].slice.call(arguments)]); };
});
</script>Attributes of the script tag
The install code sets these for you. They matter when you write the tag by hand:
- data-site: required. Your public site key.
- data-debug: writes what the script does to the browser console, with the prefix [tafsee].
- data-device: forces desktop, tablet or mobile. For testing only.
<script async src="https://popup.beta.tafsee.com/embed/v1.js" data-site="pk_your_site_key"></script>Switches in the page address
- ?tafsee-debug=1 opens the test panel. It stays on for the tab until ?tafsee-debug=0.
- ?tafsee-reset=1 forgets this browser's record for the site once, removes itself from the address, and counts nothing for that page load.
If it does not work
- TafseePopup is not defined: the script has not loaded yet (use the stub), or it is blocked on this page.
- show() does nothing: the id is not a published campaign of this website. campaigns() lists the ones that are.
- A "JavaScript event" rule does not fire: the event name in track() must be exactly the name in the rule.
