@haensl/google-analytics
Google Analytics 4 JavaScript abstraction for ga4
(gtag) and measurement protocol
(API).
@haensl/google-analytics
is build with different runtime platforms (browser vs. Node.js) in mind:
On the client:
Use window.gtag
(default): @haensl/google-analytics
import { init, event } from '@haensl/google-analytics'
;
On the server:
Use measurement protocol: @haensl/google-analytics/measurement-protocol
import { init, event } from '@haensl/google-analytics/measurement-protocol'
;
Attention: The measurement protocol abstraction requires a fetch
implementation to work, e.g. node-fetch
, cross-fetch
, or similar. See init(config)
.
Installation
Via npm
$ npm install -S @haensl/google-analytics
Via yarn
$ yarn add @haensl/google-analytics
Usage
Client/tag and measurement protocol offer similar methods, but differ in initialization and dependencies.
gtag (client)
@haensl/google-analytics
The tag implementation relies on the existence of window.gtag
. Please ensure that your page loads the Google Analytics 4 tag
, e.g. by including a <script src="...">
to fetch gtag.js
or via a component like @haensl/next-google-analytics
init(config)
import { init } from '@haensl/google-analytics'
Initializes the tracking module. You only need to call this once, e.g. when your app boots.
Tracking consent is defaulted to false
for EU region. See consent()
.
init({
measurementId,
debug = false,
anonymizeIp = true,
sendPageViews = false,
trackingConsent = false
})
consent(granted = false)
import { consent } from '@haensl/google-analytics'
Grant or deny tracking consent.
Granting/Denying tracking consent toggles:
For more information on consent mode, see Google's docs.
consent(granted = false)
Example: User grants consent:
import { consent } from '@haensl/google-analytics';
const onConsentTap = () => {
consent(true);
};
button.onClick = onConsentTap;
event({ name, params })
import { event } from '@haensl/google-analytics'
Track an event.
event({
name,
params
})
Example: Sign up event
import { event } from '@haensl/google-analytics';
// track a sign up from the footer form.
event({
name: 'sign_up',
params: {
form: 'footer'
}
});
exception({ description, fatal })
import { exception } from '@haensl/google-analytics'
Tracks an exception. Alias for event({ name: 'exception', ... })
.
exception({
description,
fatal = false
})
pageView({ location, title })
import { pageView } from '@haensl/google-analytics'
Tracks a page view. Alias for event({ name: 'page_view', ... })
.
pageView({
title,
location
})
setUserId({ id })
import { setUserId } from '@haensl/google-analytics'
Set the user id.
setUserId({
id
})
setUserProperty({ name, value })
import { setUserProperty } from '@haensl/google-analytics'
Set a user property (formerly known as dimension).
setUserProperty({
name,
value
})
Example: track the users color scheme:
import { setUserProperty } from '@haensl/google-analytics';
setUserProperty({
name: 'appearance',
value: 'dark'
});
Measurement protocol
@haensl/google-analytics/measurement-protocol
The measurement protocol implementation requires an API secret as well as a fetch
implementation at initialization.
init(config)
import { init } from '@haensl/google-analytics/measurement-protocol'
Initialize the measurement protocol module.
init({
fetch,
measurementId,
measurementSecret,
measurementUrl = 'https://www.google-analytics.com/mp/collect'
})
Example
import fetch from 'node-fetch';
import { init } from '@haensl/google-analytics/measurement-protocol';
init({
fetch,
measurementId: 'G-123ABC456D',
measurementSecret: 'super-secret'
});
clientId(cookies)
import { clientId } from '@haensl/google-analytics/measurement-protocol'
Tries to parse the Google Analytics client id from the given cookies object.
Generates a client id from timestamps if not found in cookies.
clientId(cookies = {}) => String
Example: Usage with next-cookies
import { cookies } from 'next-cookies';
import { clientId, pageView } from '@haensl/google-analytics/measurement-protocol';
export const getServerSideProps = async (ctx) => {
const requestCookies = cookies(ctx);
const requestClientId = clientId(requestCookies);
pageView({
title: 'my serverside page',
clientId: requestClientId,
location: ctx.req.url
});
};
async event({ name, params, clientId })
import { event } from '@haensl/google-analytics/measurement-protocol'
Track an event.
async event({
name,
params,
clientId
}) => Promise
Example: Sign up event
import { event, clientId } from '@haensl/google-analytics/measurement-protocol';
await event({
name: 'sign_up',
params: {
form: 'footer'
},
clientId: clientId(ctx.cookies)
});
async exception({ description, fatal clientId })
import { exception } from '@haensl/google-analytics/measurement-protocol'
Tracks an exception. Alias for event({ name: 'exception', ... })
.
async exception({
description,
fatal = false,
clientId
}) => Promise
async pageView({ location, title, clientId })
import { pageView } from '@haensl/google-analytics/measurement-protocol'
Tracks a page view. Alias for event({ name: 'page_view', ... })
.
async pageView({
title,
location,
clientId
}) => Promise
async setUserId({ id, clientId })
import { setUserId } from '@haensl/google-analytics/measurement-protocol'
Set the user id.
async setUserId({
id,
clientId
}) => Promise
async setUserProperty({ name, value, clientId })
import { setUserProperty } from '@haensl/google-analytics/measurement-protocol'
Set a user property.
async setUserProperty({
name,
value,
clientId
}) => Promsie
Example: track the users color scheme:
import { clientId, setUserProperty } from '@haensl/google-analytics/measurement-protocol';
await setUserProperty({
name: 'appearance',
value: 'dark',
clientId: clientId(ctx.cookies)
});