@classi/ngx-google-analytics
TypeScript icon, indicating that this package has built-in type declarations

4.0.5 • Public • Published

google-analytics

A bridge package between Angular application and Google Analytics API (gtag.js).

Features

  • Page view tracking
  • Custom event tracking
  • User timing tracking
  • [clAnalyticsOn] directive for tracking DOM events

Install

# install peer dependencies
$ yarn add -D @types/gtag.js
# install this package
$ yarn add @classi/ngx-google-analytics

Usage

Setup

0. Install gtag.js

ngx-google-analytics depends on window.gtag variable. Setup gtag.js following offitial guide: https://developers.google.com/analytics/devguides/collection/gtagjs

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() {
    dataLayer.push(arguments);
  }
  gtag('js', new Date());

  gtag('config', 'GA_MEASUREMENT_ID');
</script>

1. Install providers into the application.

import { ApplicationConfig } from '@angular/core';
import { provideGoogleAnalytics } from '@classi/ngx-google-analytics';

export const appConfig: ApplicationConfig = {
  providers: [
    provideGoogleAnalytics({})
  ],
};

AnalyticsTrackerConfig Options

  • startTrackingOnInit?: boolean: Start tracking automatically when the application is initialized.
  • disableTracking?: boolean: Disable all tracking. Usually for development.

2. Start tracking in bootstrapping

If you set startTrackingOnInit: true in AnalyticsTrackerConfig, you can skip this step.

To track all page view events with Angular router, start tracking before the initial navigation. Typically, the best place to start tracking is the constructor of AppComponent.

export class AppComponent {
  constructor(private readonly analytics: AnalyticsTracker) {
    this.analytics.startTracking();
  }
}

AnalyticsTracker

The central API of @classi/ngx-google-analytics.

Set user context: setUserContext(user) / clearUserContext()

export class AppComponent {
  constructor(private readonly analytics: AnalyticsTracker) {
    this.analytics.startTracking();
  }

  setUserId(userId: string) {
    this.analytics.setUserContext({ id: userId });
    this.analytics.clearUserContext();
  }
}

Set custom dimensions: setCustomDimensions(dimensions)

export class AppComponent {
  constructor(private readonly analytics: AnalyticsTracker) {
    this.analytics.startTracking();
  }

  setCustomDimensions(dimensions: Record<string, string>) {
    this.analytics.setCustomDimensions(dimensions);
  }
}

Send events: sendEvent(event)

export class AppComponent {
  constructor(private readonly analytics: AnalyticsTracker) {
    this.analytics.startTracking();
  }

  sendCustomEvent() {
    this.analytics.sendEvent({
      name: 'click',
      // optional
      params: {
        event_category: 'test',
        event_label: 'foobar',
        value: 100,
      },
    });
  }
}

Send user timing: sendUserTiming(eventFields)

export class AppComponent {
  constructor(private readonly analytics: AnalyticsTracker) {
    this.analytics.startTracking();
  }

  sendUserTiming() {
    const before = window.performance.now();
    doSomething().then(() => {
      const after = window.performance.now();
      this.analytics.sendUserTiming({
        name: 'something',
        params: {
          value: Month.round(after - before), // * required
          event_category: 'test',
          event_label: 'foobar',
        },
      });
    });
  }
}

AnalyticsOnDirective: <button clAnalyticsOn>

A directive to bind single DOM event and event tracking. Import GoogleAnalyticsModule to enable it.

@Component({
  standalone: true,
  imports: [GoogleAnalyticsModule],
  template: `<button clAnalyticsOn="click" [analyticsEvent]="clickEvent">Buy</button>`,
})
export class SomeComponent {}
  • clAnalyticsOn="{{eventName}}": Set a DOM event to track.
  • [analyticsEvent]="event": Set event fields. See details in sendEvent document.

Development

  • Run tests: npm run test google-analytics

Readme

Keywords

none

Package Sidebar

Install

npm i @classi/ngx-google-analytics

Weekly Downloads

239

Version

4.0.5

License

none

Unpacked Size

92.5 kB

Total Files

40

Last publish

Collaborators

  • classi-dev