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
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.
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.
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.
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.
@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?
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.
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.
: