Google Analytics package

OPENING POST


Description

We need to implement a package that adds the Google Analytics library and sends pageviews and events when the URL changes. Just adding the tracking code is not enough because Frontity works as a SPA.

User Stories

As a Frontity user
I want to add a package to include my tracking code
so that I don’t have to write that logic on my own theme.

Possible solution

It should be noted that there will be more analytics packages and some of them could be used at the same time in a Frontity project.

import { sendPageview, sendEvent, afterCSR } from "@frontity/analytics";
import GoogleAnalytics from "../types";

const googleAnalytics: GoogleAnalytics = {
  actions: {
    analytics: {
      sendPageview,
      sendEvent,
      afterCSR
    },
    ga: {
      sendPageview: ({ state }) => pageview => {
        // Do something with that pageview.
        console.log(state.ga.trackingId, pageview);
      },
      sendEvent: ({ state }) => event => {
        // Do something with that event.
        console.log(state.ga.trackingId, event);
      }
    }
  },
  state: {
    analytics: {
      namespaces: ["ga"]
    },
    ga: {
      trackingId: "UA-123456-7"
    }
  }
};

export default googleAnalytics;


CURRENT STATUS SUMMARY


:warning: Please, bear in mind that this section wasn’t part of the opening post. It has been added afterwards and its purpose is to keep a quick summary with the most relevant information about this FD at the top of the thread.

Version 1.0 Final Implementation

A post was merged into an existing topic: The analytics library

@david I think your last post belongs to The `analytics` library instead?

You are right. Actually, the Analytics feature discussion was open the very same day this was posted so it had to be a mistake.

Should I move the post to the other FD?
Is that possible, or do I have to copy and paste in the other thread?

I think it’s possible. Try it out and let us know :slightly_smiling_face:

5 posts were split to a new topic: Add Google analytics to my Frontity project

The first stable version for the @frontity/google-analytics package is ready!

There are not breaking changes for this package, as the settings for the frontity users remain the same, but it now uses the new version of the analytics library under the hood.

2 Likes

This has been included in the latest release :tada: : Read the full Release Announcement.

@david could you please add the final implementation here, for future reference? Maybe you can use the TSDocs to some extent.

Pull Request

Final implementation

The package was adapted to use the new version of @frontity/analytics and the following changes were made:

  • sendPageview and sendEvent were renamed to pageview and event respectively.

  • Its namespace is googleAnalytics.

  • The properties state.googleAnalytics.trackingId or state.googleAnalytics.trackingIds properties are used to specify the tracking IDs used by the package.

    {
      state: {
        googleAnalytics: {
          // If you only specify a single tracking ID
          trackingId: "UA-34567890-12",
          // If you want to use a list of tracking IDs
          trackingId: ["UA-34567890-12", "UA-34567890-13"]
        }
      }
    }
    
  • The pageview action receives an object with the properties title and link. It sends the pageview data to all traking IDs defined in the properties mentioned before.

    actions.googleAnalytics.pageview({
      title: "The Beauties Of Gullfoss",
      link: "/2016/the-beauties-of-gullfoss/"
    });
    

    This action is called automatically if state.analytics.pageviews.googleAnalytics is set to true.

  • The event action sends an event to all traking IDs defined in either state.googleAnalytics.trackingId or state.googleAnalytics.trackingIds.

    actions.googleAnalytics.event({
      name: "Click",
      payload: {
        category: "Video",
        label: "Featured Media",
        value: 42,
      },
    });
    

    This action is not meant to be called directly. It is called automatically when calling actions.analytics.event() and state.analytics.events.googleAnalytics is set to true.

  • Note that you must pass an event object to actions.analytics.event() with the following properties in order to be correctly sent to Google Analytics.

    Name Type Default Required Description
    name string - true The value of this property is mapped to the eventAction field of analytics.js events.
    payload Object - true Event payload.

    The payload object has the following format:

    Name Type Default Required Description
    category string - true The value of this property is mapped to the eventCategory field of analytics.js events.
    label string - false The value of this property is mapped to the eventLabel field of analytics.js events.
    value number - false The value of this property is mapped to the eventValue field of analytics.js events.
    [key] any - false Any other property specified in analytics.js field reference.
1 Like

We have released the v2.0 of the @frontity/google-analytics package which uses the Google Analytics 4 library (gtag) instead of the Universal Analytics library (ga): Update @frontity/google-analytics to work with the new GA4 format by cristianbote · Pull Request #733 · frontity/frontity · GitHub

This is the first time we release a major version of a package, so we need to talk about how to document it.

  • How to update the docs.
  • How/where to create migration guides.
  • How to refer to the previous versions (info, APIs and so on).

We also have to decide what to do with these old FDs:

  • How to update them to reflect the new changes.
  • If we should create a new FD for the new version or not.

But let’s not talk about it here, let’s have that conversation in Code <-> Documentation workflow.

I wanted to add this comment here for context :slightly_smiling_face:

cc: @santosguillamot, @juanma

@cristianbote I think it would be nice to write down here a summary of the changes made in the v2.0 of the package and how users should migrate from older versions. Maybe it could be a shortened version of the Final Implementation template. What do you think?

Pull Request

Functionalities

Using @frontity/google-analytics anyone should be able to use the new GA4 to send in events and other analytic data.

API changes

Backward compatible changes

  • Tracking custom data it’s still possible with GA4 with single or multiple tracking IDs, using the same actions:
    • googleAnalytics.pageview
    • googleAnalytics.event

New APIs

  • window.gtag

Breaking changes

  • There’s no window.ga anymore.

Deprecated APIs

  • window.ga it is not available anymore

Technical explanation

  • The way one uses the GA4 to send in data, has changed as well.
  • The changes are not breaking the way pageview and event actions are working.

@SantosGuillamot let me know if the above summaries the changes properly.

Thanks Cristian :slightly_smiling_face:

If I am not mistaken, the old tracking IDs are still compatible with the new library used to send pageviews and events (gtag). What is breaking here is the way to send custom pageviews or events right? If users created their own pageviews or events they have to migrate them following this guide, but they can still use tracking IDs for Google Analytics properties using Universal Analytics. Is that correct?

I think you are right. This is is pretty confusing to me, as it’s not clearly stated if the new GA ids are tracking IDs. Or I am not getting through to it.

Yup, and the way the configuration is set up.

Great :slightly_smiling_face: Could you update your summary to prevent missunderstandings?

1 Like

This is the moment when we should open an issue in the docs, isn’t it?

Related: Update @frontity/google-analytics to work with the new GA4 format by cristianbote · Pull Request #733 · frontity/frontity · GitHub

Awesome!

Just did it in here Document the @frontity/[email protected] · Issue #19 · frontity/api-reference · GitHub

2 Likes