# @googleforcreators/tracking

> Utility package for telemetry in the Web Stories editor, powered by Google Analytics.

Latest version **0.1.202410011217** (published 2024-10-01) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @googleforcreators/tracking
pnpm add @googleforcreators/tracking
yarn add @googleforcreators/tracking
bun add @googleforcreators/tracking
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.1.202410011217 |
| Published | 2024-10-01 |
| First published | 2022-02-07 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 12 \|\| >= 14 \|\| >= 16 \|\| >= 18 \|\| >= 20 |
| Dependencies | 0 |
| Unpacked size | 86.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 798 |
| Author | Google |
| Maintainers | google-wombot, swissspidy |
| Keywords | web stories, analytics, google analytics, telemetry |

## Links

- npm: https://www.npmjs.com/package/@googleforcreators/tracking
- Repository: https://github.com/GoogleForCreators/web-stories-wp
- Homepage: https://github.com/GoogleForCreators/web-stories-wp/blob/main/packages/tracking/README.md
- Issues: https://github.com/googleforcreators/web-stories-wp/issues
- npm.io page: https://npm.io/package/@googleforcreators/tracking

## Recent versions

- 0.1.202410011217 (latest) — 2024-10-01
- 0.1.202409011216 — 2024-09-01
- 0.1.202407011334 — 2024-07-01
- 0.1.202405151100 — 2024-05-15
- 0.1.202401011233 — 2024-01-01
- 0.1.202309041201 — 2023-09-04
- 0.1.202306211149 — 2023-06-21
- 0.1.202303271448 — 2023-03-27
- 0.1.202302061326 — 2023-02-06
- 0.1.202301231653 — 2023-01-23
- 0.1.202212191259 — 2022-12-19
- 0.1.202212071230 — 2022-12-07
- 0.1.202211151052 — 2022-11-15
- 0.1.202208291229 — 2022-08-29
- 0.1.202208151234 — 2022-08-15
- … 10 more at https://npm.io/package/@googleforcreators/tracking/versions

## README

# Tracking

Helper library for interacting with Google Events to track page/screen views and events.

Supports only Google Analytics 4

## Usage

### Initialize Tracking

Initialize tracking in the module's entry point.

If the user has opted in to telemetry, this will enable tracking by loading the Google Analytics `gtag.js` script.

By default this will result in a page view being tracked, unless turned off using the second boolean argument.

```js
initializeTracking('Awesome App', false);
```

### Enable/Disable Tracking

Use the `disableTracking` and `enableTracking` functions to initialize tracking after the initial page view.

Useful when the user changes his telemetry preferences at a later point.

The `isTrackingEnabled()` function provides the current opt-in/out status.

### Tracking Screen Views

[Screen views](https://developers.google.com/analytics/devguides/collection/ga4/screen-view) are like page views, but for web apps. To send `screen_view` events when users navigate to different screens within an app,
use the `trackScreenView()` function.

```js
trackScreenView('Settings');
```

### Tracking Clicks

Use the `trackClick` function in your `onClick` handler.

If links are to open in the same tab, they will only do so after the tracking event has already been sent.
This ensures no tracking calls are missed.

```js
trackClick(event, 'contact_support');
```

### Tracking Errors (Exceptions)

You can use `trackError` to send [exception events](https://developers.google.com/analytics/devguides/collection/ga4/exceptions) to measure the number and type of crashes or errors that occur on a web page.

The first parameter is the prefix, the second one the error description, and the third one indicates whether the error was fatal or not.

```js
trackError('demo', 'Division by zero', false);
```

### Tracking Events

At the core of this package is the `trackEvent` function.

All you need to provide is the event name and as many optional event parameters as you want:

```js
trackEvent('insert_template', {
template_name: 'Awesome Template',
});
```

### User Timings

Use the following helper function to start a timer and return a callback to stop it:

```js
const trackTiming = getTimeTracker('video_transcoding'); // Start timer.
// Perform some long task...
trackTiming(); // Stop timer and send event.
```

---
_Source: https://npm.io/package/@googleforcreators/tracking · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._