gtag() compatibility

[androidacy-user]

Hello!

We'd like to start using this library for GA4 on our site(s), but we're hitting a big snag right now: having to restructure all of our tracking calls to use mostly custom code.

Is there a plan to add gtag() or even dataLayer compatibility in the future?

[jahilldev]

Hi @androidacy-user!

Thanks for reaching out 👍

I would suggest this could be achieved by using a custom abstraction in your application. From memory, gtag is just a global function that wraps various GA triggers and config. If your application uses this directly, without your own abstraction (I would strongly suggest not doing this in future, it makes changing third party integrations difficult, as you're find out!), then you could simply write your own gtag function that wraps this package's track() function.

Something like this:

import { track } from '@minimal-analytics/ga4';

/*[...]*/

const GA_ID = 'G-XXXXXXXX';

window.gtag = (method, ...args) => {
  if(method === 'config' && args[0] === GA_ID) {
    track(GA_ID) // page_view

    return;
  }

  if(method === 'event') {
    track({ type: args[0], event: args[1] }); // custom event

    return;
  }
  
  /* etc, etc :) */
};

This would be a 1-1 proxy for triggering an event using gtag, e.g:

Page View

// maybe hold the measurement ID in a global var
gtag('config', 'G-XXXXXXXX');

Custom Event

gtag('event', 'login', {'ep.user': 'John Smith'});

You'll need to cater to all uses of gtag throughout your application, but with a little effort this shouldn't be too tricky.

Ideally your application would use it's own analytics abstraction, so if you wanted to switch from say GA to something completely different, you'd just refactor the abstraction, not the usage. This of course, can be said for any third party integration.

We won't be adding gtag compatibility to this package, given the multitude of ways Google Analytics can be integrated, it would dramatically (and gradually) increase the overall size of the code, whilst also potentially opening us up to supporting deprecated methods / API's in future. This is really a consumer issue, and should likely be handled by a given application.

I hope this helps! Please let me know if you have any further questions, or require help with anything.

It's important to note, if your application is not using a Node environment, we currently don't expose the track function globally. If this is the case, let me know, and we can look into doing that for you.

All the best! 👍

[androidacy-user]

Its a browser based application for the most part - good ol' WordPress and/or Laravel on the backend @jahilldev

[jahilldev]

@androidacy-user In that case, if you're not using a build tool for your frontend, then for the above to work we'll need to expose the track function globally for you.

Once we've done that, something like window.track() or similar, you can follow the above suggested abstraction, minus the import statement.

I'll see if I can get a release done sometime this week for you. This has been on my watch list, but nobody thus far has piped up to say they want it, but now you have!

Thanks again for contributing 👍

[jahilldev]

@androidacy-user Ok I've opened a PR that introduces an additional config property, defineGlobal.
PR: #31

Once this is merged / deployed you'll have access to the track() function on the Window. In order for this to work, you'll need to ensure you set this new config property under window.minimalAnalytics. I've updated the README in the PR to outline how.

It's off by default to avoid unnecessary Window pollution for those that don't want it.

[androidacy-user]

Excellent, sounds great

[jahilldev]

@androidacy-user I've just deployed the latest version that provides the global function definition, v1.8.4.

Let me know how you get on!

[jahilldev]

@androidacy-user Apologies, I've just identified a bug. Fixed now in v1.8.6!

[androidacy-user]

For anyone who wants it, here's our generic gtag() wrapper around track()

window.gtag = (event, eventName, data) => {
  // For each element in the data object, add the key and value to the event data object. For strings, prepend ep. to the key, and for numbers, append epn. to the key.
  for (const key in data) {
    if (typeof data[key] === 'string') {
      data[`ep.${key}`] = data[key]
      delete data[key]
    } else if (typeof data[key] === 'number') {
      data[`epn.${key}`] = data[key]
      delete data[key]
    }
  }
  // Send the event to Google Analytics.
  track('<tracking id>L', {
    type: eventName,
    event: {
      ...data
    }
  })
}