FOnce on Github: https://github.com/TonySimonovsky/FOnce.
Usage examples
There are 2 most common examples of FOnce usage.
- Firing a conversion pixel, provided by your advertisement service, only once per user. This is especially helpful for those who collect leads. As a lead is just contact details of a person, so it doesn’t matter how many times the user filled-out your form – for you it will still be a single lead. FOnce will help you make data in the interface of your ad campaign more precise).
- Showing window with a special offer. Sometimes you need to show a pop-up window (with a special offer, asking to join your Facebook community or even giving some hint on using the site). In these cases you don’t want to be too pushy, right? FOnce will help you show those windows only once per session (or once a day, if you want).
What I like most about FOnce is that by default the rules fire in the first pageview of a visit, but you can change this behaviour by simply adding conditions to the rules.
For example, if you want fire a conversion pixel only if the user converted after a minute on the site (to exclude fake leads), you can add those conditions and the rule will only fire once all 3 conditions are met: form successfully submitted, user is on the site more than a minute and haven’t yet converted into a lead.
Or, you want to show window with special offer only when a user tries to close the window or once per day after a user viewed 5 pages (and you know that on your site 5th pageview is a moment when the user is about to leave).
All of these use cases are easy to deal with using FOnce.
Several more problems, which FOnce solves: 1, 2, 3, 4.
If you discovered some other cases where FOnce might be helpful, please write to me and I’ll add them to this article.
FOnce installation
FOnce is made for GTM v2. Though it will work in GTM v1 after some simple tweaks (which will require some GTM knowledge from you), I recommend migrating to v2, if you haven’t done so.
To install simply download and import FOnce.json file to your GTM container using merge option (screenshot: http://joxi.ru/l2ZVPD5uX0bD2J).
Use rules FOnce - Once a session
, FOnce - Once today
, FOnce - Once a user
to fire tags with a respective scope.
If you need to add more conditions, you do simply like it is said: add conditions to the FOnce rule you are using.
Note. If you will just add 2 rules (one of the FOnce rules plus some other rule) to your tag, that won’t work how you expect (in this case your tag will fire 2 times: 1 for each rule, but not when both rules are met at the same time). So, for example, this will fire test_tag 2 times: on the first pageview of the session and when foo-page will be opened:
Instead you need to add second condition to the rule FOnce - Once a session
, like this:
(don’t forget you need to turn on “Page URL” in Variables section to see it in the list of conditions).
GTM technical implementation
Caution. If you are not a geek or don’t know GTM good enough, following text may cause gape. By this disclaimer I relieve myself of any responsibility caused by this. If you are not sure you want to read further, you can go directly to Github to download FOnce: https://github.com/TonySimonovsky/FOnce.
Geeks may read further.
Variables
FOnce stores information in three 1st party cookies (GTM Variables):
FOnce - cookie - Session
(cookie name:fonce_current_session
)FOnce - cookie - User
(cookie name:fonce_current_user
)FOnce - cookie - Today
(cookie name:fonce_current_day
)
There are 3 more variables used in FOnce:
FOnce - Session lifetime minutes
This one is used to set session lifetime in minutes (by default, 30 minutes).
Note, that a session in terms of FOnce is not the same as a Google Analytics’s session. FOnce operates following idea of session: set of pageviews with an interval between seperate pageviews not more than 30 minutes (or whatever you set in the “FOnce – Session lifetime minutes” variable). This is pretty close to what Google Analytics consideres a session, but not totally same. There will be some discrepancy. I’m open to any suggestions how to improve this or any other part of FOnce. Please, write your suggestions to 42@stony.me.FOnce - Today date
This variable simply returns current date. I could have done without it and put this code directly to the tag, but I thought it would be nicer to have this separate.FOnce - Was today
This variable is needed, because forFOnce - Once today
rule to work we need to check both the fact that conversion has already occurred and which date it occurred. This variable returns 1 if conversion already occurred today and 0 if not (or if it occurred, but yesterday or any other day).
Rules
There are 3 rules (FOnce - Once a session
, FOnce - Once a user
, FOnce - Once today
).
By default, they fire on the first pageview of visit to the site, but you can easily change this behaviour by simply adding any conditions you need.
For example, a rule for session scope by default looks like this:
But you can add any conditions to the rule like shown on screenshot 2 above in the usage section.
Tags
Each of the FOnce cookies is served by 2 GTM tags (so, there are 6 tags).
FOnce - [Session|User|Today] Flag
(below I will call them justFlag
). These tags fire on every page and just check if corresponding cookie already exists. If the cookie doesn’t exist, the tag creates it with a value, denoting, that conversion haven’t occurred yet.FOnce - [Session|User|Today] Conversion Flag
(below –Conversion Flag
). These tags fire using corresponding FOnce rule.
Note. These tags’ priority is set to 10, to be more than priority ofFlag
and thus to fire before it. While developing FOnce, I spent quite a lot of time trying to understand why sometimes cookie was set with right value and sometimes – not. In the end I found out that sometimesFlag
tags fired afterConversion Flag
tags and the former didn’t see that the latter already changed cookie value and was rewriting it.
Postscript
FOnce was released on Github on 14th of June, 2015. Feel free to use it. If you feel it may be improved, I will be happy to hear your ideas.