{"id":13806328,"url":"https://github.com/hakimio/ngx-google-analytics","last_synced_at":"2025-06-30T23:34:08.390Z","repository":{"id":197918354,"uuid":"699753087","full_name":"hakimio/ngx-google-analytics","owner":"hakimio","description":"📈 A simple Google analytics integration for Angular apps","archived":false,"fork":false,"pushed_at":"2023-10-03T11:09:13.000Z","size":377,"stargazers_count":20,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-20T20:12:50.875Z","etag":null,"topics":["analytics-4","angular","ga4","google","google-analytics","google-analytics-4","ngx"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hakimio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-10-03T09:14:38.000Z","updated_at":"2025-05-09T23:33:31.000Z","dependencies_parsed_at":"2023-10-03T14:55:08.093Z","dependency_job_id":null,"html_url":"https://github.com/hakimio/ngx-google-analytics","commit_stats":null,"previous_names":["hakimio/ngx-google-analytics"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hakimio/ngx-google-analytics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakimio%2Fngx-google-analytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakimio%2Fngx-google-analytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakimio%2Fngx-google-analytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakimio%2Fngx-google-analytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hakimio","download_url":"https://codeload.github.com/hakimio/ngx-google-analytics/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakimio%2Fngx-google-analytics/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261012112,"owners_count":23096807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics-4","angular","ga4","google","google-analytics","google-analytics-4","ngx"],"created_at":"2024-08-04T01:01:10.280Z","updated_at":"2025-06-30T23:34:08.335Z","avatar_url":"https://github.com/hakimio.png","language":"TypeScript","readme":"# Ngx Google Analytics\n\n\u003e A simple way to track GA4 events in Angular apps.\n\n`@hakimio/ngx-google-analytics` is a fork of __Max Andriani's__ `ngx-google-analytics`.\n\n---\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/hakimio/ngx-google-analytics/tests.yml)](https://github.com/hakimio/ngx-google-analytics/actions/workflows/tests.yml)\n[![Version Number](https://img.shields.io/npm/v/@hakimio/ngx-google-analytics.svg)](https://www.npmjs.com/package/@hakimio/ngx-google-analytics)\n[![License](https://img.shields.io/npm/l/@hakimio/ngx-google-analytics.svg)](https://www.npmjs.com/package/@hakimio/ngx-google-analytics)\n\n# Index\n\n- [Setup](#setup)\n  - [Install the package](#install-the-package)\n  - [Standalone](#standalone-app-component)\n  - [NgModule](#ngmodule)\n  - [Setup Router Provider](#setup-router-provider)\n  - [Advanced Router Provider Setup](#advanced-router-provider-setup)\n- [GoogleAnalyticsService](#googleanalyticsservice)\n  - [Register Analytics events](#register-analytics-events)\n  - [Manually register page views](#manually-register-page-views)\n- [Directives](#directives)\n  - [Simple directive usage](#simple-directive-usage)\n  - [Usage on input elements](#usage-on-input-elements)\n  - [Directive groups](#directive-groups)\n\n## Setup\n\n### Install the package\n\n```\nnpm install @hakimio/ngx-google-analytics\n```\n\n### Standalone app component\n\nIf your app component is using standalone API, follow these steps to set up the library:\n- Add `provideGoogleAnalytics('ga4-tag-id')` to your app's providers. If you can not find your GA4 tag id, see [this](https://support.google.com/analytics/answer/9539598?sjid=1584949217252276099-EU) Google help page.\n\n`main.ts`\n```ts\nimport {AppComponent} from './app/app.component';\nimport {bootstrapApplication} from '@angular/platform-browser';\nimport {ROUTES} from './app/app.routes';\nimport {provideGoogleAnalytics} from '@hakimio/ngx-google-analytics';\n\nbootstrapApplication(AppComponent, {\n    providers: [\n        provideRouter(ROUTES),\n        provideAnimations(),\n        provideGoogleAnalytics('ga4-tag-id') // ⬅️ Google Analytics provider\n    ]\n}).catch(err =\u003e console.error(err));\n```\nYou can also specify additional settings using the second optional parameter: `provideGoogleAnalytics('ga4-tag-id', settings)`.\nSee [IGoogleAnalyticsSettings](https://github.com/hakimio/ngx-google-analytics/blob/master/projects/ngx-google-analytics/src/lib/interfaces/i-google-analytics-settings.ts)\ninterface for more information about available settings.  \n- Add `NgxGoogleAnalyticsModule` to your app component's imports:\n\n`app.component.ts`\n```ts\nimport {NgxGoogleAnalyticsModule} from '@hakimio/ngx-google-analytics';\n\n@Component({\n    selector: 'app-root',\n    templateUrl: './app.component.html',\n    styleUrls: ['./app.component.css'],\n    standalone: true,\n    imports: [\n        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module\n    ]\n})\nexport class AppComponent {}\n```\n\n### NgModule\n\nIf your application is `NgModule` based, follow these steps to set up the library:\n- Add `NgxGoogleAnalyticsModule` to your root app module's (`AppModule`) `imports`. \n- Add `provideGoogleAnalytics('ga4-tag-id')` in your app module's providers. If you can not find your GA4 tag id, see [this](https://support.google.com/analytics/answer/9539598?sjid=1584949217252276099-EU) Google help page.\n\n`app.module.ts`\n```ts\nimport {NgxGoogleAnalyticsModule, provideGoogleAnalytics} from '@hakimio/ngx-google-analytics';\n\n@NgModule({\n    declarations: [\n        AppComponent\n    ],\n    imports: [\n        BrowserModule,\n        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module\n    ],\n    providers: [\n        provideGoogleAnalytics('ga4-tag-id') // ⬅️ Google Analytics provider\n    ],\n    bootstrap: [AppComponent]\n})\nexport class AppModule {}\n```\nYou can also specify additional settings using the second optional parameter: `provideGoogleAnalytics('ga4-tag-id', settings)`.\nSee [IGoogleAnalyticsSettings](https://github.com/hakimio/ngx-google-analytics/blob/master/projects/ngx-google-analytics/src/lib/interfaces/i-google-analytics-settings.ts)\ninterface for more information about available settings.\n\n### Setup Router Provider\n\nIf you are using Angular Router and would like to track page views, you can include `provideGoogleAnalyticsRouter()` in your root app providers.\n\n**IMPORTANT:** `provideGoogleAnalyticsRouter()` is not compatible with SSR and should not be included in server app providers.\n\n```ts\nimport {NgxGoogleAnalyticsModule, provideGoogleAnalytics, provideGoogleAnalyticsRouter} from '@hakimio/ngx-google-analytics';\n\n@NgModule({\n    imports: [\n        // ...\n        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module\n    ],\n    providers: [\n        provideGoogleAnalytics('ga4-tag-id'),\n        provideGoogleAnalyticsRouter() // ⬅️ Google Analytics router provider\n    ]\n})\nexport class AppModule {}\n```\n\n### Advanced Router Provider Setup\n\nYou can include or exclude some routes by passing options object to `provideGoogleAnalyticsRouter(options)`. \n\nFollowing path matches are supported:\n\n- Simple path match: `{ include: [ '/full-uri-match' ] }`;\n- Wildcard path match: `{ include: [ '*/public/*' ] }`;\n- Regex path match: `{ include: [ /^\\/public\\/.*/ ] }`;\n\n```ts\nimport {NgxGoogleAnalyticsModule, provideGoogleAnalytics, provideGoogleAnalyticsRouter} from '@hakimio/ngx-google-analytics';\n\n@NgModule({\n    imports: [\n        // ...\n        NgxGoogleAnalyticsModule // ⬅️ Google Analytics module\n    ],\n    providers: [\n        provideGoogleAnalytics('ga4-tag-id'),\n        provideGoogleAnalyticsRouter({ // ⬅️ Google Analytics router provider\n            include: ['/some-path'],\n            exclude: ['*/another/path/*']\n        })\n    ]\n})\nexport class AppModule {}\n```\n\n\n## GoogleAnalyticsService\n\nThe service provides strongly typed way to call `gtag()` command. Apart from type checking, it does not do \nany other validation or transformation of the parameters.\n\n### Register Analytics events\n\n```ts\n@Component()\nexport class TestFormComponent {\n\n    private readonly gaService = inject(GoogleAnalyticsService);\n\n    onUserInputName() {\n        this.gaService.event('enter_name', {\n            category: 'user_register_form',\n            label: 'Name',\n            options: {\n                customDimension: 'foo_bar'\n            }\n        });\n    }\n\n    onUserInputEmail() {\n        this.gaService.event('enter_email', {\n            category: 'user_register_form',\n            label: 'Email'\n        });\n    }\n\n    onSubmit() {\n        this.gaService.event('submit', {\n            category: 'user_register_form',\n            label: 'Enviar' \n        });\n    }\n\n}\n```\n\n### Manually register page views\n\n```ts\n@Component()\nexport class TestPageComponent implements OnInit {\n\n    private readonly gaService = inject(GoogleAnalyticsService);\n\n    ngOnInit() {\n        this.gaService.pageView('/test', {\n            title: 'Test the Title'\n        });\n    }\n    \n    onUserLogin() {\n        this.gaService.pageView('/test', {\n            title: 'Test the Title',\n            options: {\n                user_id: 'my-user-id'\n            }\n        });\n    }\n\n}\n```\n\n## Directives\n\nDirectives provide a simple way to register Analytics events. Instead of manually using `GoogleAnalyticsService`, \nyou can simply add `ga*` attributes to your html elements.\n\n### Simple directive usage\n\nBy default, the directive calls `gtag()` on click events, but you can also specify other events by providing `gaBind` attribute.\n\n**IMPORTANT:** Remember to import `NgxGoogleAnalyticsModule` in all your standalone components and modules where you use `ga*` directives.\n\n```html\n\u003cdiv\u003e\n  \u003cbutton gaEvent=\"click_test\" gaCategory=\"ga_directive_test\"\u003eClick Test\u003c/button\u003e\n  \u003cbutton gaEvent=\"focus_test\" gaCategory=\"ga_directive_test\" gaBind=\"focus\"\u003eFocus Test\u003c/button\u003e\n  \u003cbutton gaEvent=\"blur_test\" gaCategory=\"ga_directive_test\" gaBind=\"blur\"\u003eBlur Test\u003c/button\u003e\n  \u003cbutton gaEvent=\"custom_test\" gaCategory=\"ga_directive_test\" gaBind=\"customEvent\"\u003eCustom Event Test\u003c/button\u003e\n\u003c/div\u003e\n```\n\n### Usage on `input` elements\n\nWhen `gaEvent` directive is used on form elements, the default `trigger` is `focus` event.\n\n```html\n\u003cdiv\u003e\n  \u003cinput gaEvent=\"fill_blur\" gaCategory=\"ga_directive_input_test\" placeholder=\"Auto Blur Test\"/\u003e\n\u003c/div\u003e\n```\n\n### Directive groups\n\nThe `gaCategory` directive can be specified on higher level of html element group to specify same category for all \nchild elements.\n\n```html\n\u003cdiv gaCategory=\"ga_test_category\"\u003e\n  \u003cbutton gaEvent gaAction=\"click_test\"\u003eClick Test\u003c/button\u003e\n  \u003cbutton gaEvent gaAction=\"focus_test\" gaBind=\"focus\"\u003eFocus Test\u003c/button\u003e\n  \u003cbutton gaEvent gaAction=\"blur_test\" gaBind=\"blur\"\u003eBlur Test\u003c/button\u003e\n\u003c/div\u003e\n```\n","funding_links":[],"categories":["Table of contents"],"sub_categories":["Angular"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhakimio%2Fngx-google-analytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhakimio%2Fngx-google-analytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhakimio%2Fngx-google-analytics/lists"}