ngx-google-analytics

Ngx Google Analytics

An easy implementation to track ga on angular8+ apps.

Feedbacks on https://github.com/maxandriani/ngx-google-analytics

• Setup
  • NPM
  • Simple Setup
  • Routing Setup
  • Advanced Routing Setup
• GoogleAnalyticsServie
• Directives
• Changelog

Setup

NPM

To setup this package on you project, just call the following command.

npm install ngx-google-analytics

Simple Setup

On your Angular Project, you shall include the NgxGoogleAnalyticsModule on you highest level application module. ie AddModule. The easest install mode call the forRoot() method and pass the GA tracking code.

import { NgxGoogleAnalyticsModule } from 'ngx-google-analytics';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    NgxGoogleAnalyticsModule.forRoot('traking-code')
  // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Setup Routing Module

We provide a second Module Dependency to configure Router Event Bindings and performa automatic page view every time you application navigate to another page.

Add NgxGoogleAnalyticsRouterModule on AppModule enable auto track Router events.

IMPORTANT: This Module just subscribe to Router events when the bootstrap component is created, and than cleanup any subscriptions related to previous compenente when it is destroyed. Maybe you may get some issues if using this module on a server side rendering or multiple bootstrap componentes. If it is your case, a suggest you subscribe does events by yourself. You can use or git repository as reference.

import { NgxGoogleAnalyticsModule, NgxGoogleAnalyticsRouterModule } from 'ngx-google-analytics';
...

@NgModule({
  ...
  imports: [
    ...
    NgxGoogleAnalyticsModule.forRoot(environment.ga),
    NgxGoogleAnalyticsRouterModule
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ]
})
export class AppModule {}

Advanced Setup Routing Module

You can customize some rules to include/exclude routes on NgxGoogleAnalyticsRouterModule. The include/exclude settings allow:

• Simple route match: { include: [ '/full-uri-match' ] };
• Wildcard route match: { include: [ '*/public/*' ] };
• Regular Expression route match: { include: [ /^\/public\/.*/ ] };

import { NgxGoogleAnalyticsModule, NgxGoogleAnalyticsRouterModule } from 'ngx-google-analytics';
...

@NgModule({
  ...
  imports: [
    ...
    NgxGoogleAnalyticsModule.forRoot(environment.ga),
    NgxGoogleAnalyticsRouterModule.forRoot({ include: [...], exclude: [...] })
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ]
})
export class AppModule {}

GoogleAnalyticsService

This service provides a easy and strong typed way to call gtag() command. It does nothing else then conver a strong typed list of arguments into a standard gtag api call.

Call Interface Events

@Component( ... )
export class TestFormComponent {

  constructor(
    private $gaService: GoogleAnalyticsService
  ) {}

  onUserInputName() {
    ...
    this.$gaService.event('enter_name', 'user_register_form', 'Name');
  }

  onUserInputEmail() {
    ...
    this.$gaService.event('enter_email', 'user_register_form', 'Email');
  }

  onSubmit() {
    ...
    this.$gaService.event('submit', 'user_register_form', 'Enviar');
  }

}

Call GA Page Views and Virtual Page Views

@Component(...)
export class TestPageComponent implements OnInit {

  constructor(
    protected $gaService: GoogleAnalyticsService
  ) {}

  ngOnInit() {
    this.$gaService.pageView('/teste', 'Teste de Title')
  }

  onUserLogin() {
    ...
    this.$gaService.pageView('/teste', 'Teste de Title', undefined, {
      user_id: 'my-user-id'
    })
  }

}

Directives

In a way to help you to be more productive on attach GA events on UI elements. We create some directives to handle GoogleAnalyticsService and add event listener by simple attributes.

Simple directive use

The default behaviour is call gtag on click events, but you can change the trigger to focus or blur events as well.

<div>
  <button gaEvent="click_test" gaCategory="ga_directive_test">Click Test</button>
  <button gaEvent="focus_test" gaCategory="ga_directive_test" gaBind="focus">Focus Test</button>
  <button gaEvent="blur_test" gaCategory="ga_directive_test" gaBind="blur">Blur Test</button>
</div>

Simple input use

If you atacchs gaEvent directive on form elements, it will assume focus event as default trigger.

<div>
  <input gaEvent="fill_blur" gaCategory="ga_directive_input_test" placeholder="Auto Blur Test">
</div>

Grouped directives

Sometime your UX guy want to gromp several elements in the interface at same group to help his analystis and reports. Fortunaly the gaCategory directive can be placed on the highest level group element and all child gaEvent will assume the parent gaCategory as their parent.

<div gaCategory="ga_test_category">
  <button gaEvent gaAction="click_test">Click Test</button>
  <button gaEvent gaAction="focus_test" gaBind="focus">Focus Test</button>
  <button gaEvent gaAction="blur_test" gaBind="blur">Blur Test</button>
</div>

Changelog

9.2.0

• Add include/exclude rules feature on NgxGoogleAnalyticsRouterModule.forRoot() to filter witch pages should trigger page-view event.
• Remove peerDependencies from package.json to do not trigger unnecessary warnings on npm install command.