{"id":100662,"date":"2025-02-21T02:54:42","date_gmt":"2025-02-21T02:54:42","guid":{"rendered":"https:\/\/peraltafinancing.com\/analytics\/gtmtips-use-localstorage-for-client-id-persistence-in-google-analytics\/"},"modified":"2025-02-21T02:54:42","modified_gmt":"2025-02-21T02:54:42","slug":"gtmtips-use-localstorage-for-client-id-persistence-in-google-analytics","status":"publish","type":"post","link":"https:\/\/fivemor.com\/?p=100662","title":{"rendered":"#GTMTips: Use localStorage For Client ID Persistence In Google Analytics"},"content":{"rendered":"


\n<\/p>\n

\n
\n

Updated 1 October 2019<\/strong> With ITP 2.3<\/a> it looks like Safari is reducing the usefulness of localStorage<\/code> as well, so this solution should not<\/strong> be considered future-proof. The only stable way to persist client-side data at the moment seems to be HTTP cookies<\/a>.<\/p>\n<\/blockquote>\n

\n

Updated 7 March 2019<\/strong> – Added some extra caveats<\/a> to this solution. Also, be sure to read my article on ITP 2.1<\/a>, which has far more detail on what Intelligent Tracking Prevention is and how to work with it.<\/p>\n<\/blockquote>\n

Looks like Safari is tightening the noose around browser cookies with the introduction of ITP 2.1<\/a> (Intelligent Tracking Prevention). Among other things, ITP 2.1<\/strong> caps the expiration of client-side cookies to 7 days<\/strong>. Client-side cookies<\/em> in this context refer to cookies set with the document.cookie<\/code> API, which would cover pretty much all cookies set by vendored JavaScript libraries like Google Analytics\u2019 analytics.js<\/strong>.<\/p>\n

Personally, I think anything that forces a rethink of the cookie model is welcome. It\u2019s awkward and twisted that we still rely on such flimsy and fragile browser storage for persisting important data such as anonymous analytics identifiers, authentication flags, and basically anything that needs to persist from one page to the next.<\/p>\n

Having said that, this can make potentially benevolent<\/em> tracking such as that done with Google Analytics<\/a> on a website quite difficult for users with Safari browsers. Since GA relies on a browser cookie capped at 2 years\u2019 expiration (by default), this 7 days max can really hurt data quality.<\/p>\n

In this article, I want to show you how to use customTask<\/code><\/a> with localStorage<\/code> to serve as a backup<\/em> of sorts for your cookie-based Client ID persistence.<\/p>\n

It\u2019s not perfect. Check out the caveats<\/a> chapter for details. Please treat this as a technology demo rather than a be-all, end-all solution to cookie woes. We\u2019ll need to rely on the vendors and browsers finding consensus for how to make life harder on the bad agents without compromising the work us \u201cregular folks\u201d need to do to improve our websites with first-party analytics data.<\/p>\n


\n X<\/span><\/p>\n

\n
\n The Simmer Newsletter<\/strong>\n <\/p>\n

\n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n

<\/span><\/p>\n

Tip 96: Persist the Client ID in localStorage<\/code><\/h2>\n
\n

<\/p>\n

\"localStorage<\/p>\n

<\/a><\/p>\n<\/div>\n

It\u2019s not a novel trick. In fact, Google themselves show you how to do this<\/a> in the developer documentation. The thing is, though, that Google only shows you how to replace<\/strong> cookie storage with localStorage<\/code>. I still want to leverage cookies, because they make things like cross-domain tracking far easier to do.<\/p>\n

The process is basically this:<\/p>\n

    \n
  1. \n

    When a Google Analytics tracker is created, check if Client ID is persisted in localStorage<\/code>.<\/p>\n<\/li>\n

  2. \n

    If this is the case, check if its expiration is in the future.<\/p>\n<\/li>\n

  3. \n

    If this is the case, build the tracker with the Client ID from localStorage<\/code> (the tracker will generate the _ga<\/code> cookie with this data, too).<\/p>\n<\/li>\n

  4. \n

    If there is no Client ID in localStorage<\/code> use GA\u2019s default Client ID creation and storage mechanisms.<\/p>\n<\/li>\n

  5. \n

    When the tag fires, write the Client ID in localStorage<\/code>.<\/p>\n<\/li>\n<\/ol>\n

    It should be pretty smooth sailing. Since the _ga<\/code> cookie and localStorage<\/code> are kept in sync, this should work across origins which is something that localStorage<\/code> by default doesn\u2019t do.<\/p>\n

    NOTE!<\/strong> Since you\u2019re always checking localStorage<\/code> first, this means that if the user deletes their cookies, they don\u2019t actually delete the Client ID, because that would require localStorage<\/code> to be flushed, too. You might want to discuss this solution with your legal team before going forward with it.<\/p>\n

    How to set the Client ID<\/h3>\n

    You\u2019ll need two Custom JavaScript variables<\/strong>. One to set<\/strong> the Client ID, and one to get<\/strong> it.<\/p>\n

    To set<\/strong> the Client ID, go to the customTask<\/code> Builder tool<\/a>, select the option named Use localStorage To Persist ClientId<\/strong>, and then click Copy to clipboard<\/strong>.<\/p>\n

    \n

    <\/p>\n

    \"Copy<\/p>\n

    <\/a><\/p>\n<\/div>\n

    In Google Tag Manager<\/a>, create a new Custom JavaScript variable, and paste the clipboard content within. Then, do the following two maintenance operations:<\/p>\n

      \n
    1. \n

      Delete the following text from the start of the code block: var customTask = <\/code>. Just that, nothing else.<\/p>\n<\/li>\n

    2. \n

      Delete the last character of the entire code block, which should be a semi-colon.<\/p>\n<\/li>\n<\/ol>\n

      Then, modify the configuration object, if you wish.<\/p>\n

      \n
      var<\/span> localStorageCid = {\n  objectName: 'ga_client_id'<\/span>,\n  expires: 1000<\/span>*60<\/span>*60<\/span>*24<\/span>*365<\/span>*2<\/span>\n};\n<\/code><\/pre>\n<\/div>\n
      If you want the name of the object written to localStorage<\/code> to be something other than 'ga_client_id'<\/code>, change the respective string value. The expires<\/code> value is a number in milliseconds<\/strong> denoting how long the object should be in storage. It\u2019s updated every time a tag fires with this customTask<\/code> script. If you want the storage to expire sooner or later than two years\u2019 time, change the value of expires<\/code> accordingly.<\/p>\n
      \n
      NOTE!<\/strong> There is no automatic expiration mechanism with localStorage<\/code>. \u201cExpires\u201d here simply means that if the expiration of the item is in the past, it will be overwritten with the Client ID generated by GA.<\/p>\n<\/blockquote>\n
      Finally, add this customTask<\/code> to all your Google Analytics tags<\/strong>. Easiest way to do it is to use a Google Analytics Settings variable<\/a>. Add it like this:<\/p>\n
      \n
          <\/p>\n
          \"Customtask<\/p>\n
          <\/a><\/p>\n<\/div>\n
      Remember that you can only add one customTask<\/code> per tag or Google Analytics Settings variable. Use the customTask<\/code> Builder tool<\/a> to compile a customTask<\/code> that incorporates multiple different functions.<\/p>\n
      How to get the Client ID<\/h3>\n
      The second Custom JavaScript variable<\/strong> you\u2019ll need is something that will pull the Client ID from localStorage<\/code> and use that instead of the value stored in the _ga<\/code> cookie (if any).<\/p>\n
      This is what the Custom JavaScript variable code looks like:<\/p>\n
      \n
      function<\/span>() {\n  var<\/span> objectName = 'ga_client_id'<\/span>;\n  if<\/span> (window<\/span>.localStorage) {\n    var<\/span> jsonObj = window<\/span>.localStorage.getItem(objectName) || '{}'<\/span>;\n    var<\/span> obj = JSON.parse(jsonObj);\n    var<\/span> now = new<\/span> Date<\/span>().getTime();\n    if<\/span> (obj.clientId && obj.expires) {\n      if<\/span> (now return obj.clientId;\n      }\n    }\n  }\n  return<\/span>;\n}\n<\/code><\/pre>\n<\/div>\n
      Change the value of objectName<\/code> to match the name of the localStorage<\/code> object you set in the customTask<\/code> above. By default, it\u2019s 'ga_client_id'<\/code>.<\/p>\n
      This script checks if a Google Analytics Client ID is found in localStorage<\/code>, and that if found, its expiration time hasn\u2019t whizzed past yet. If both of these conditions pass, the Client ID is returned from localStorage<\/code>.<\/p>\n
      If no item is found, or if object has expired, or if the browser doesn\u2019t support localStorage<\/code>, the variable returns undefined<\/code> which basically means that GA falls back to its default method of Client ID generation, retrieval, and storage.<\/p>\n
      You need to add this variable to every single tag to which you added the customTask<\/code> from above<\/strong>. Again, it\u2019s imperative that every single tag uses this new localStorage<\/code> method consistently, or you might end up with tags firing with the wrong Client ID, thus skewing your data.<\/p>\n
      You add this variable with the field name clientId<\/code>, like this:<\/p>\n
      \n
          <\/p>\n
          \"ClientID<\/p>\n
          <\/a><\/p>\n<\/div>\n
      That\u2019s it for this simple solution. There is one big problem<\/strong> with this approach, though. It will always<\/strong> take the Client ID from localStorage<\/code> if it\u2019s available and hasn\u2019t expired. This is problematic in one specific scenario: cross-domain tracking<\/strong>.<\/p>\n
      How to respect GA\u2019s cross-domain linker parameter<\/h3>\n
      Turns out, this isn\u2019t totally trivial to do. Even if you set the allowLinker<\/code> field to true<\/code> in the tag, the Client ID from localStorage<\/code> will always overwrite the respective field in the tag, no matter how valid the linker parameter was.<\/p>\n
      So, you need to replicate how allowLinker<\/code> works, checking if the URL has a valid linker parameter. If it does, then you need to bypass the localStorage<\/code> fetch, so that analytics.js can build the Client ID with the linker parameter, and then write the updated ID into localStorage<\/code> in the customTask<\/code>.<\/p>\n
      Unfortunately, analytics.js<\/strong> doesn\u2019t expose the allowLinker<\/code> functionality as an API you could simply query to know whether the URL has a valid linker parameter or not.<\/p>\n
      This leaves us with very few options. Your best bet is to actually reproduce<\/strong> what allowLinker<\/code> does. It\u2019s not trivial, so I did the legwork for you (thanks to David Vallejo\u2019s<\/a> generous help). You can find the source code in this Gist<\/a>.<\/p>\n
      To add it to your setup, open the Custom JavaScript variable you created in the previous chapter, and edit it to this:<\/p>\n
      \n
      function<\/span>() {\n  var<\/span> objectName = 'ga_client_id'<\/span>;\n  \n  var<\/span> checkLinker=function<\/span>(t){var<\/span> n,e,i=function<\/span>(t,n){for<\/span>(var<\/span> e=new<\/span> Date<\/span>,i=window<\/span>.navigator,r=i.plugins||[],a=[t,i.userAgent,e.getTimezoneOffset(),e.getYear(),e.getDate(),e.getHours(),e.getMinutes()+n],s=0<\/span>;sreturn o(a.join(\".\"<\/span>))},r=function<\/span>(t,n){var<\/span> e=new<\/span> Date<\/span>,i=window<\/span>.navigator,r=e.getHours()+Math<\/span>.floor((e.getMinutes()+n)\/60<\/span>);return<\/span> o([t,i.userAgent,i.language||\"\"<\/span>,e.getTimezoneOffset(),e.getYear(),e.getDate()+Math<\/span>.floor(r\/24<\/span>),(24<\/span>+r)%24<\/span>,(60<\/span>+e.getMinutes()+n)%60<\/span>].join(\".\"<\/span>))},o=function<\/span>(t){var<\/span> n,e=1<\/span>;if<\/span>(t)for<\/span>(e=0<\/span>,n=t.length-1<\/span>;0<\/span>var i=t.charCodeAt(n);e=0<\/span>!=(i=266338304<\/span>&(e=(e6&268435455<\/span>)+i+(i14)))?e^i>>21<\/span>:e}return<\/span> e.toString()};if<\/span>(\"string\"<\/span>==typeof<\/span> t&&t.length){if<\/span>(!\/_ga=\/<\/span>.test(t))return<\/span>\"Invalid linker format in string argument!\"<\/span>;e=t.split(\"&\"<\/span>).filter(function<\/span>(t){return<\/span>\"_ga\"<\/span>===t.split(\"=\"<\/span>)[0<\/span>]}).shift()}else<\/span> e=(n=\/[?&]_ga=\/<\/span>.test(window<\/span>.location.search)?\"search\"<\/span>:\/[#&]_ga=\/<\/span>.test(window<\/span>.location.hash)?\"hash\"<\/span>:void<\/span> 0<\/span>)&&window<\/span>.location[n].substring(1<\/span>).split(\"&\"<\/span>).filter(function<\/span>(t){return<\/span>\"_ga\"<\/span>===t.split(\"=\"<\/span>)[0<\/span>]}).shift();if<\/span>(void<\/span> 0<\/span>===e||!e.length)return<\/span>\"Invalid linker format in URL!\"<\/span>;var<\/span> a,s,g,u,f=e.indexOf(\".\"<\/span>);return<\/span> f>-1<\/span>&&(e.substring(0<\/span>,f),s=(a=e.substring(f+1<\/span>)).indexOf(\".\"<\/span>),g=a.substring(0<\/span>,s),u=a.substring(s+1<\/span>)),void<\/span> 0<\/span>!==u?g===i(u=u.split(\"-\"<\/span>).join(\"\"<\/span>),0<\/span>)||g===i(u,-1<\/span>)||g===i(u,-2<\/span>)||g===r(u,0<\/span>)||g===r(u,-1<\/span>)||g===r(u,-2<\/span>):void<\/span> 0<\/span>};\n  \n  if<\/span> (checkLinker()) {\n    return<\/span>;\n  }\n  \n  if<\/span> (window<\/span>.localStorage) {\n    var<\/span> jsonObj = window<\/span>.localStorage.getItem(objectName) || '{}'<\/span>;\n    var<\/span> obj = JSON.parse(jsonObj);\n    var<\/span> now = new<\/span> Date<\/span>().getTime();\n    if<\/span> (obj.clientId && obj.expires) {\n      if<\/span> (now return obj.clientId;\n      }\n    }\n  }\n  return<\/span>;\n}\n<\/r.length><\/code><\/pre>\n<\/div>\n
      The checkLinker()<\/code> method parses the URL for a valid linker parameter. If one is found, then the variable ignores the Client ID stored in localStorage<\/code> and allows the GA tag to build the Client ID from the linker parameter instead.<\/p>\n
      Read on for one major caveat in this approach.<\/p>\n
      Caveats<\/h3>\n
      There are, naturally, some caveats to this workaround.<\/p>\n
      That big block of code starting with var checkLinker=<\/code> contains the code in the GitHubGist<\/a> just minified to reduce clutter.<\/p>\n