@hakimio/ngx-google-analytics

Ngx Google Analytics

A simple way to track GA4 events in Angular apps.

@hakimio/ngx-google-analytics is a fork of Max Andriani's ngx-google-analytics.

Index

• Setup
  • Install the package
  • Standalone
  • NgModule
  • Setup Router Provider
  • Advanced Router Provider Setup
• GoogleAnalyticsService
  • Register Analytics events
  • Manually register page views
• Directives
  • Simple directive usage
  • Usage on input elements
  • Directive groups

Setup

Install the package

npm install @hakimio/ngx-google-analytics

Standalone app component

If your app component is using standalone API, follow these steps to set up the library:

• Add provideGoogleAnalytics('ga4-tag-id') to your app's providers. If you can not find your GA4 tag id, see this Google help page.

main.ts

import {AppComponent} from './app/app.component';
import {bootstrapApplication} from '@angular/platform-browser';
import {ROUTES} from './app/app.routes';
import {provideGoogleAnalytics} from '@hakimio/ngx-google-analytics';

bootstrapApplication(AppComponent, {
    providers: [
        provideRouter(ROUTES),
        provideAnimations(),
        provideGoogleAnalytics('ga4-tag-id') // ⬅️ Google Analytics provider
    ]
}).catch(err => console.error(err));

You can also specify additional settings using the second optional parameter: provideGoogleAnalytics('ga4-tag-id', settings). See IGoogleAnalyticsSettings interface for more information about available settings.

• Add NgxGoogleAnalyticsModule to your app component's imports:

app.component.ts

import {NgxGoogleAnalyticsModule} from '@hakimio/ngx-google-analytics';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
    standalone: true,
    imports: [
        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module
    ]
})
export class AppComponent {}

NgModule

If your application is NgModule based, follow these steps to set up the library:

• Add NgxGoogleAnalyticsModule to your root app module's (AppModule) imports.
• Add provideGoogleAnalytics('ga4-tag-id') in your app module's providers. If you can not find your GA4 tag id, see this Google help page.

app.module.ts

import {NgxGoogleAnalyticsModule, provideGoogleAnalytics} from '@hakimio/ngx-google-analytics';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module
    ],
    providers: [
        provideGoogleAnalytics('ga4-tag-id') // ⬅️ Google Analytics provider
    ],
    bootstrap: [AppComponent]
})
export class AppModule {}

You can also specify additional settings using the second optional parameter: provideGoogleAnalytics('ga4-tag-id', settings). See IGoogleAnalyticsSettings interface for more information about available settings.

Setup Router Provider

If you are using Angular Router and would like to track page views, you can include provideGoogleAnalyticsRouter() in your root app providers.

IMPORTANT: provideGoogleAnalyticsRouter() is not compatible with SSR and should not be included in server app providers.

import {NgxGoogleAnalyticsModule, provideGoogleAnalytics, provideGoogleAnalyticsRouter} from '@hakimio/ngx-google-analytics';

@NgModule({
    imports: [
        // ...
        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module
    ],
    providers: [
        provideGoogleAnalytics('ga4-tag-id'),
        provideGoogleAnalyticsRouter() // ⬅️ Google Analytics router provider
    ]
})
export class AppModule {}

Advanced Router Provider Setup

You can include or exclude some routes by passing options object to provideGoogleAnalyticsRouter(options).

Following path matches are supported:

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

import {NgxGoogleAnalyticsModule, provideGoogleAnalytics, provideGoogleAnalyticsRouter} from '@hakimio/ngx-google-analytics';

@NgModule({
    imports: [
        // ...
        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module
    ],
    providers: [
        provideGoogleAnalytics('ga4-tag-id'),
        provideGoogleAnalyticsRouter({ // ⬅️ Google Analytics router provider
            include: ['/some-path'],
            exclude: ['*/another/path/*']
        })
    ]
})
export class AppModule {}

GoogleAnalyticsService

The service provides strongly typed way to call gtag() command. Apart from type checking, it does not do any other validation or transformation of the parameters.

Register Analytics events

@Component()
export class TestFormComponent {

    private readonly gaService = inject(GoogleAnalyticsService);

    onUserInputName() {
        this.gaService.event('enter_name', {
            category: 'user_register_form',
            label: 'Name',
            options: {
                customDimension: 'foo_bar'
            }
        });
    }

    onUserInputEmail() {
        this.gaService.event('enter_email', {
            category: 'user_register_form',
            label: 'Email'
        });
    }

    onSubmit() {
        this.gaService.event('submit', {
            category: 'user_register_form',
            label: 'Enviar' 
        });
    }

}

Manually register page views

@Component()
export class TestPageComponent implements OnInit {

    private readonly gaService = inject(GoogleAnalyticsService);

    ngOnInit() {
        this.gaService.pageView('/test', {
            title: 'Test the Title'
        });
    }
    
    onUserLogin() {
        this.gaService.pageView('/test', {
            title: 'Test the Title',
            options: {
                user_id: 'my-user-id'
            }
        });
    }

}

Directives

Directives provide a simple way to register Analytics events. Instead of manually using GoogleAnalyticsService, you can simply add ga* attributes to your html elements.

Simple directive usage

By default, the directive calls gtag() on click events, but you can also specify other events by providing gaBind attribute.

IMPORTANT: Remember to import NgxGoogleAnalyticsModule in all your standalone components and modules where you use ga* directives.

<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>
  <button gaEvent="custom_test" gaCategory="ga_directive_test" gaBind="customEvent">Custom Event Test</button>
</div>

Usage on input elements

When gaEvent directive is used on form elements, the default trigger is focus event.

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

Directive groups

The gaCategory directive can be specified on higher level of html element group to specify same category for all child elements.

<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

15.0.0

• GA4 support
• Updated Angular to v16 and dropped support for older versions
• Dropped rxjs v6 support. Now only rxjs v7 is supported.
• NgxGoogleAnalyticsModule.forRoot() and NgxGoogleAnalyticsRouterModule.forRoot() are now replaced by provideGoogleAnalytics() and provideGoogleAnalyticsRouter() to set up library's providers
• All directives are now standalone and can be imported separately or used as hostDirectives in other directives
• GoogleAnalyticsService methods now use options objects to specify additional arguments instead of a long list of arguments with some of the arguments undefined.

Thanks, @Spejik, for the implementation.

Before:

this.gaService.pageView('/test', 'Test the Title', undefined, {
  user_id: 'my-user-id'
});

After:

this.gaService.pageView('/test', {
    title: 'Test the Title',
    options: {
        user_id: 'my-user-id'
    }
});