{"id":13527877,"url":"https://github.com/angulartics/angulartics","last_synced_at":"2025-05-14T07:11:02.704Z","repository":{"id":8741522,"uuid":"10418430","full_name":"angulartics/angulartics","owner":"angulartics","description":"Analytics for AngularJS applications.","archived":false,"fork":false,"pushed_at":"2020-07-01T15:15:57.000Z","size":638,"stargazers_count":1940,"open_issues_count":85,"forks_count":414,"subscribers_count":57,"default_branch":"master","last_synced_at":"2025-04-28T02:37:31.738Z","etag":null,"topics":["analytics","angular","event-tracking","google-analytics","pageview-tracking"],"latest_commit_sha":null,"homepage":"http://angulartics.github.io/","language":"JavaScript","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/angulartics.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}},"created_at":"2013-06-01T05:59:41.000Z","updated_at":"2025-03-16T21:09:17.000Z","dependencies_parsed_at":"2022-08-30T16:11:18.638Z","dependency_job_id":null,"html_url":"https://github.com/angulartics/angulartics","commit_stats":null,"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angulartics%2Fangulartics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angulartics%2Fangulartics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angulartics%2Fangulartics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angulartics%2Fangulartics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angulartics","download_url":"https://codeload.github.com/angulartics/angulartics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252321366,"owners_count":21729324,"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","angular","event-tracking","google-analytics","pageview-tracking"],"created_at":"2024-08-01T06:02:04.757Z","updated_at":"2025-05-14T07:10:57.629Z","avatar_url":"https://github.com/angulartics.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Service"],"sub_categories":[],"readme":"# angulartics\n\n[![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-downloads-url] [![Bower version][bower-image]][bower-url] [![Dependencies status][dep-status-image]][dep-status-url] [![devDependency Status](https://david-dm.org/angulartics/angulartics/dev-status.svg)](https://david-dm.org/angulartics/angulartics#info=devDependencies) [![MIT license][license-image]][license-url] [![Gitter Chat](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/angulartics) [![CDNJS](https://img.shields.io/cdnjs/v/angulartics.svg)](https://cdnjs.com/libraries/angulartics)\n\nVendor-agnostic analytics for AngularJS applications. [angulartics.github.io](http://angulartics.github.io \"Go to the website\")\n\n## Please Read!\n\nThis is **Angulartics**, not _**[Angularytics](http://github.com/mgonto/angularytics)**_. There's been some complains about the unfortunate similarity in the names of both projects (this is actually a [funny story](#FunnyStory)), so [we hear you guys](https://daveceddia.com/angular/angularytics-vs-angulartics/) and are making this clarification here. Just make sure **Angulartics** is the library you actually want to use, and if you work in a team, make sure this is the library they are using!\n\n## Install\n\n### npm\n\n```shell\nnpm install angulartics\n```\n\n### Bower\n\nTo install angulartics core module:\n```shell\nbower install angulartics\n```\n\n### NuGet\n\n\u003e **Note: we are dropping support for NuGet.\n\n## Full path tracking (for pages without a router)\nIntroduced in 0.15.19 - support websites that do not use Angular `routes` or `states` on every page and still want to track full paths.  The modifications lead to the following behavior:\n\n - **Viewing page `http://host.com/routes#/route` will be tracked as `/routes#/route`.** The original version would only track the page as `/route`\n - **Viewing page `http://host.com/noroutes` will be tracked as `/noroutes`.**  This is useful for pages that do not contain Angular code besides initializing the base module.\n - **Viewing page `http://host.com/routes2` that loads a default route and changes the path to `http://host.com/routes2#/` will be tracked as `/routes2#/`.** This will only fire one pageview, whereas earlier versions would have fired two.\n\nTo enable this behavior, add the following to your configuration:\n\n\t\t...\n\t\tvar yourApp = angular.module('YourApp', ['angulartics', 'angulartics.google.analytics'])\n\t\t    .config(function ($analyticsProvider) {\n\t\t        $analyticsProvider.firstPageview(true); /* Records pages that don't use $state or $route */\n\t\t        $analyticsProvider.withAutoBase(true);  /* Records full path */\n\t\t});\n\nYou can also use `$analyticsProvider.withBase(true)` instead of `$analyticsProvider.withAutoBase(true)` if you are using a `\u003cbase\u003e` HTML tag.\n\n## Minimal setup\n\n### for Google Analytics\n\nSee [angulartics-google-analytics](https://github.com/angulartics/angulartics-google-analytics/blob/master/README.md) documentation.\n\n### for Google Tag Manager (new interface)\n\n    angular.module('myApp', ['angulartics', 'angulartics.google.tagmanager'])\n\nAdd the full tracking code from Google Tag Manager to the beginning of your body tag.\n\nSetup listeners in Google Tag Manager\n\n#### 6 Variables\n\nNaming and case must match.\n\n1. **angulartics page path**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **content-name**\n2. **angulartics event category**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **target**\n3. **angulartics event action**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **action**\n4. **angulartics event label**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **target-properties**\n5. **angulartics event value**\n    Macro Type: **Data Layer Variable**\n    Data Layer Variable Name: **value**\n6. **angulartics event interaction type**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **interaction-type**\n\n#### 2 Triggers\n\nName and case must match\n\n1. **Angulartics events**\n    Event: **Custom Event**\n    Fire on: **interaction**\n2. **Angulartics pageviews**\n    Event: **Custom Event**\n    Fire on: **content-view**\n\n#### 2 Tags\n\n1. **Angulartics Events**\n    Product: **Google Analytics**\n    Type: **Universal Analytics**\n    Tracking ID: **YourGoogleAnalyticsID**\n    Track Type: **Event**\n    Category: **{{angulartics event category}}**\n    Action: **{{angulartics event action}}**\n    Label: **{{angulartics event label}}**\n    Value: **{{angulartics event value}}**\n    Non-Interaction Hit: **{{angulartics event interaction type}}**\n    Fire On: **Angulartics events**\n2. **Angulartics Pageviews**\n    Product: **Google Analytics**\n    Type: **Universal Analytics**\n    Tracking ID: **YourGoogleAnalyticsID**\n    Track Type: **Page View**\n    More settings \u003e Field to Set \u003e name: **page**, value: **{{angulartics page path}}**\n    Fire On: **Angulartics pageviews**\n\n### for Google Tag Manager (old interface)\n\n    angular.module('myApp', ['angulartics', 'angulartics.google.tagmanager'])\n\nAdd the full tracking code from Google Tag Manager to the beginning of your body tag.\n\nSetup listeners in Google Tag Manager\n\n#### 6 Macros\n\nNaming and case must match.\n\n1. **angulartics page path**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **content-name**\n2. **angulartics event category**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **target**\n3. **angulartics event action**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **action**\n4. **angulartics event label**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **target-properties**\n5. **angulartics event value**\n    Macro Type: **Data Layer Variable**\n    Data Layer Variable Name: **value**\n6. **angulartics event interaction type**\n    Type: **Data Layer Variable**\n    Data Layer Variable Name: **interaction-type**\n\n#### 2 Rules\n\nName and case must match\n\n1. **Angulartics events**\n    Condition: **{{event}} equals interaction**\n2. **Angulartics pageviews**\n    Condition: **{{event}} equals content-view**\n\n#### 2 Tags\n\n1. **Angulartics Events**\n    Product: **Google Analytics**\n    Type: **Universal Analytics**\n    Tracking ID: **YourGoogleAnalyticsID**\n    Track Type: **Event**\n    Category: **{{angulartics event category}}**\n    Action: **{{angulartics event action}}**\n    Label: **{{angulartics event label}}**\n    Value: **{{angulartics event value}}**\n    Non-Interaction Hit: **{{angulartics event interaction type}}**\n    Firing Rules: **Angulartics events**\n2. **Angulartics Pageviews**\n    Product: **Google Analytics**\n    Type: **Universal Analytics**\n    Tracking ID: **YourGoogleAnalyticsID**\n    Track Type: **Page View**\n    More settings \u003e Basic Configuration \u003e Document Path: **{{angulartics page path}}**\n    Firing Rules: **Angulartics pageviews**\n\n### for Piwik ##\n\nSee [angulartics-piwik](https://github.com/angulartics/angulartics-piwik) for more details.\n\n### for other providers\n\n[Browse the website for detailed instructions.](http://angulartics.github.io)\n\n## Supported providers\n\n* [Adobe Analytics](https://github.com/angulartics/angulartics-adobe-analytics)\n* [Chartbeat](https://github.com/angulartics/angulartics-chartbeat)\n* [Clicky](https://github.com/angulartics/angulartics-clicky)\n* [Facebook Pixel] (https://github.com/mooyoul/angulartics-facebook-pixel)\n* [Flurry](https://github.com/angulartics/angulartics-flurry)\n* [Google Analytics](https://github.com/angulartics/angulartics-google-analytics)\n* Google Tag Manager\n* GoSquared\n* [HubSpot](https://github.com/angulartics/angulartics-hubspot)\n* [IBM Digital Analytics](https://github.com/cwill747/angulartics-coremetrics)\n* [Kissmetrics](https://github.com/angulartics/angulartics-kissmetrics)\n* [Localytics](https://github.com/angulartics/angulartics-localytics)\n* Loggly\n* Marketo\n* [Mixpanel](https://github.com/angulartics/angulartics-mixpanel)\n* Piwik\n* [Scout](https://github.com/Trolleymusic/angulartics-scout)\n* Scroll tracking\n* [Segment](https://github.com/angulartics/angulartics-segment)\n* Splunk\n* Woopra\n\nIf there's no Angulartics plugin for your analytics vendor of choice, please feel free to write yours and PR' it! Here's how to do it.\n\n## Creating your own vendor plugin\n\n\u003e Make sure you follow the [Plugin contribution guidelines](https://github.com/angulartics/angulartics/wiki/Plugin-contribution-rules). You can also use [any of the existing plugins](https://github.com/angulartics) as a starter template.\n\nIt's very easy to write your own plugin. First, create your module and inject `$analyticsProvider`:\n\n\tangular.module('angulartics.myplugin', ['angulartics'])\n\t  .config(['$analyticsProvider', function ($analyticsProvider) {\n\nPlease follow the style `angulartics.{vendorname}`.\n\nNext, you register either the page track function, event track function, or both. You do it by calling the `registerPageTrack` and `registerEventTrack` methods. Let's take a look at page tracking first:\n\n    $analyticsProvider.registerPageTrack(function (path) {\n\t\t// your implementation here\n\t}\n\nBy calling `registerPageTrack`, you tell Angulartics to invoke your function on `$routeChangeSuccess` or `$stateChangeSuccess`. Angulartics will send the new path as an argument.\n\n    $analyticsProvider.registerEventTrack(function (action, properties) {\n\t\t// your implementation here\n\nThis is very similar to page tracking. Angulartics will invoke your function every time the event (`analytics-on` attribute) is fired, passing the action (`analytics-event` attribute) and an object composed of any `analytics-*` attributes you put in the element.\n\nIf the analytics provider is created async, you can wrap you code with:\n\n    angulartics.waitForVendorApi(\"var\", 1000, function(window.var) {\n      ...\n    });\n\nwhich will polls every 1000ms for `window.var`, and fire `function(window.var)` once `window.var` is not `undefined`. Calls made by `$analytics` will be buffered until `function(window.var)` fires.\n\nYou can also poll for `window.var.subvar` with:\n\n    angulartics.waitForVendorApi(\"var\", 1000, \"subvar\", function(window.var) {\n      ...\n    });\n\nCheck out the bundled plugins as reference. If you still have any questions, feel free to email me or post an issue at GitHub!\n\n## Playing around\n\n### Opt-out settings\n\nWhen working on a global product there are many countries who by default require the opt-out functionality of all analytics and tracking. These opt out settings are meant to aid with that. The developer mode simply cripples the library where as this actually disables the tracking so it can be turned on and off.\n\n    // $analytics.setOptOut(boolean Optout);\n    // To opt out\n    $analytics.setOptOut(true);\n\n    // To opt in\n    $analytics.setOptOut(false);\n\n    // To get opt out state\n    $analytics.getOptOut(); // Returns true or false\n\n\n### Disabling virtual pageview tracking\n\nIf you want to keep pageview tracking for its traditional meaning (whole page visits only), set virtualPageviews to false:\n\n\tmodule.config(function ($analyticsProvider) {\n\t\t$analyticsProvider.virtualPageviews(false);\n\n### Disabling pageview tracking for specific routes\n\nIf you want to disable pageview tracking for specific routes, you can define a list of excluded routes (using strings or regular expressions):\n\n    module.config(function ($analyticsProvider) {\n    \t\t$analyticsProvider.excludeRoutes(['/abc','/def']);\n\nUrls and routes that contain any of the strings or match any of the regular expressions will not trigger the pageview tracking.\n\n### Disabling tracking of specific query string keys\n\nIf you want to disable tracking for specific query string keys, you can define a list of both whitelisted and blacklisted keys (using strings or regular expressions):\n\n    module.config(function ($analyticsProvider) {\n            $analyticsProvider.queryKeysWhitelist([/^utm_.*/]);\n            $analyticsProvider.queryKeysBlacklist(['email',/^user/]);\n\nAny query string key/value pairs will be filtered out of the URL sent to the tracking authority.\n\nBlacklisting overrides Whitelisting.\n\n### Disabling tracking on $routeChangeSuccess\n\nIf you want to disable pageview tracking for the $routeChangeSuccess event, set trackRoutes to false:\n\n    module.config(function ($analyticsProvider) {\n      $analyticsProvider.trackRoutes(false);\n\n### Disabling tracking on $stateChangeSuccess\n\nIf you want to disable pageview tracking for the $stateChangeSuccess event, set trackStates to false:\n\n    module.config(function ($analyticsProvider) {\n      $analyticsProvider.trackStates(false);\n\n### Programmatic tracking\n\nUse the `$analytics` service to emit pageview and event tracking:\n\n\tmodule.controller('SampleCtrl', function($analytics) {\n\t\t// emit pageview beacon with path /my/url\n\t    $analytics.pageTrack('/my/url');\n\n\t\t// emit event track (without properties)\n\t    $analytics.eventTrack('eventName');\n\n\t\t// emit event track (with category and label properties for GA)\n\t    $analytics.eventTrack('eventName', {\n\t      category: 'category', label: 'label'\n        });\n\n### Declarative tracking\n\nUse `analytics-on` and `analytics-event` attributes for enabling event tracking on a specific HTML element:\n\n\t\u003ca href=\"file.pdf\"\n\t\tanalytics-on=\"click\"\n        analytics-if=\"myScope.shouldTrack\"\n\t\tanalytics-event=\"Download\"\u003eDownload\u003c/a\u003e\n\n`analytics-on` lets you specify the DOM event that triggers the event tracking; `analytics-event` is the event name to be sent.\n\n`analytics-if` is a conditional check. If the attribute value evaluates to a falsey, the event will NOT be fired. Useful for user tracking opt-out, etc.\n\nAdditional properties (for example, category as required by GA) may be specified by adding `analytics-*` attributes:\n\n\t\u003ca href=\"file.pdf\"\n\t\tanalytics-on=\"click\"\n\t\tanalytics-event=\"Download\"\n\t\tanalytics-category=\"Content Actions\"\u003eDownload\u003c/a\u003e\n\nor setting `analytics-properties`:\n\n\t\u003ca href=\"file.pdf\"\n\t\tanalytics-on=\"click\"\n\t\tanalytics-event=\"Download\"\n\t\tanalytics-properties=\"{ category: 'Content Actions' }\"\u003eDownload\u003c/a\u003e\n\n### Scroll tracking\n\nYou can use:\n\n    \u003cdiv analytics-on=\"scrollby\"\u003e\n\nwhich will track an event when the element is scrolled to the top of the viewport.\nThis relies on [jQuery Waypoints](http://imakewebthings.com/jquery-waypoints/) which must be loaded:\n\n    \u003cscript src=\"waypoints/waypoints.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"angulartics/dist/angulartics-scroll.min.js\"\u003e\u003c/script\u003e\n\nThe following module must be enabled as well:\n\n    angular.module('myApp', [..., 'angulartics.scroll'])\n\nYou can pass [extra options](http://imakewebthings.com/waypoints/api/waypoint/) to Waypoints with `scrollby-OPTION`. For example, to track an event when the element is in the middle on the viewport:\n\n    \u003cdiv analytics-on=\"scrollby\" scrollby-offset=\"50%\"\u003e\n\nWaypoints is fired with the following options:\n  - `continuous: false`, when jumping (for example with a URL anchor) passed several tracked elements, only the last one will fire an event\n  - `triggerOnce: true`, the tracking event is only fired once for a given page\n\n### User tracking\n\nYou can assign user-related properties which will be sent along each page or event tracking thanks to:\n\n    $analytics.setAlias(alias)\n    $analytics.setUsername(username)\n    $analytics.setUserProperties(properties)\n    $analytics.setSuperProperties(properties)\n\nLike `$analytics.pageTrack()` and `$analytics.eventTrack()`, the effect depends on the analytics provider (i.e. `$analytics.register*()`). Not all of them implement those methods.\n\nThe Google Analytics module lets you call `$analytics.setUsername(username)` or set up `$analyticsProvider.settings.ga.userId = 'username'`.\n\n### Exception tracking\n\nYou can enable automatic exception tracking which decorates angular's `$exceptionHandler` and reports the exception to the analytics provider:\n\n    $analyticsProvider.trackExceptions(true)\n\nCurrently only the Google Analytics provider supports tracking exceptions, and it does so by reporting it as an event.\n\n### Developer mode\n\nYou can disable tracking with:\n\n    $analyticsProvider.developerMode(true);\n\nYou can also debug Angulartics by adding the following module:\n\n    angular.module('myApp', [..., 'angulartics.debug'])\n\nwhich will call `console.log('Page|Event tracking: ', ...)` accordingly.\n\n## What else?\n\nSee more docs and samples at [http://angulartics.github.io](http://angulartics.github.io \"http://angulartics.github.io\").\n\n## \u003ca name=\"FunnyStory\"\u003e\u003c/a\u003eFunny Story\n\nBack in 2003 [@mgonto](http://github.com/mgonto) and I were excited with Angular, doing a bunch of stuff. We had met each other at the [Nardoz](http://github.com/nardoz) group and even crossed paths working for the same company. It turns out, both of us came up with the idea of building a module for analytics **at the same time, without knowing about it**. We even created our respective repos with just seconds of difference. Check that out yourselves by using the GitHub api and inspecting [the creation date for this repo](https://api.github.com/repos/angulartics/angulartics) (at that time, this repo was under my username [@luisfarzati](http://github.com/luisfarzati), this is the original so it has the original creation date) and then [Angularytics](https://api.github.com/repos/mgonto/angularytics)' creation date. Even our initial commits were about the same time.\n\nTo be honest, initially I thought he was just blatantly copycating the idea but then when I checked out the repo data, truth was his repo timestamp was even earlier than mine. So, technically, I copycated his idea. Of course I did not, that's the funny and weirdest thing of the story. Or perhaps, even weirder, is that we both chose almost the same exact name, only that @mgonto went with an additional Y.\n\nWe discussed about renaming one of our projects, we almost decided to play a Rock, Paper, Scissors, Lizard, Spock game to decide who keeps the original name, but both of us really liked our names. So we kept it that way.\n\nIsn't the open source world crazy?\n\n## License\n\n[MIT](LICENSE)\n\n[npm-image]: https://img.shields.io/npm/v/angulartics.svg\n[npm-url]: https://npmjs.org/package/angulartics\n[npm-downloads-image]: https://img.shields.io/npm/dm/angulartics.svg\n[npm-downloads-url]: https://npmjs.org/package/angulartics\n[bower-image]: https://img.shields.io/bower/v/angulartics.svg\n[bower-url]: http://bower.io/search/?q=angulartics\n[dep-status-image]: https://img.shields.io/david/angulartics/angulartics.svg\n[dep-status-url]: https://david-dm.org/angulartics/angulartics\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[license-url]: LICENSE\n[slack-image]: https://angulartics.herokuapp.com/badge.svg\n[slack-url]: https://angulartics.herokuapp.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangulartics%2Fangulartics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangulartics%2Fangulartics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangulartics%2Fangulartics/lists"}