|
1 | | -# angularjs-segment |
2 | | -AngularJS module for easily adding Segment analytics to any app. https://segment.com |
| 1 | +# ngSegment: [Segment](https://segment.com) analytics for [AngularJS](https://angular.io/) |
| 2 | +A highly configurable module for adding Segment analytics to any Angular app. |
| 3 | + |
| 4 | +## Table of Contents |
| 5 | +- [Get Started](#get-started) |
| 6 | +- [Usage](#usage) |
| 7 | +- [Configuration](#configuration) |
| 8 | + - [Provider](#provider) |
| 9 | + - [Constant](#constant) |
| 10 | + - [Service](#service) |
| 11 | +- [API Documentation](#api-documentation) |
| 12 | +- [Examples](#examples) |
| 13 | + |
| 14 | +## Get Started |
| 15 | + |
| 16 | +1. Download the ngSegment source from Bower, npm, or Github. |
| 17 | +2. Include `segment.min.js` in your `index.html`, after including Angular. |
| 18 | +3. Add `'ngSegment'` to your main module's list of dependencies: `angular.module('myApp', ['ngSegment']);`. |
| 19 | + |
| 20 | +**Bower:** |
| 21 | +`bower install angular-segment-analytics --save` |
| 22 | + |
| 23 | +**npm:** |
| 24 | +`npm install angular-segment-analytics` |
| 25 | + |
| 26 | +## Usage |
| 27 | + |
| 28 | +Set your API key using any of the configuration methods provided ([provider](#provider), [constant](#constant), or [service](#service)), and you're ready to start using Segment in your app. |
| 29 | + |
| 30 | +```js |
| 31 | +// analytics.js will be asynchronously auto-loaded |
| 32 | +segmentProvider.setKey('abc'); |
| 33 | +``` |
| 34 | + |
| 35 | +Most Segment methods (see [Analytics.js](https://segment.com/docs/libraries/analytics.js/)) are available on the `segment` service created by ngSegment. |
| 36 | + |
| 37 | +```js |
| 38 | +segment.track('action', { prop: 'value' }); |
| 39 | +``` |
| 40 | + |
| 41 | +Continue reading about the configuration options, or jump to the [Examples](#examples). |
| 42 | + |
| 43 | + |
| 44 | +## Configuration |
| 45 | + |
| 46 | +ngSegment can be configured in any of 3 ways: using a provider, constant or service. These 3 options are available so you can pick the mechanism that fits your application best. The provider or constant are recommended because typically it's best to configure 3rd party libraries in the config phase of your application. |
| 47 | + |
| 48 | +It is not recommended to mix configuration mechanisms, but if you do they're applied in the order listed in this documentation (provider, constant then service) and conflicting settings will be overridden. |
| 49 | + |
| 50 | +### Provider |
| 51 | + |
| 52 | +The `segmentProvider` is available during your application's `.config()` phase, before services have been instantiated. Read the AngularJS documentation to learn more about [module configuration blocks](https://docs.angularjs.org/guide/module#module-loading-dependencies). |
| 53 | + |
| 54 | +```js |
| 55 | +angular.module('myApp').config(function (segmentProvider) { |
| 56 | + segmentProvider |
| 57 | + .setKey('abc') |
| 58 | + .setCondition(function ($rootScope) { |
| 59 | + return $rootScope.isProduction; |
| 60 | + }) |
| 61 | + .setDebug(true) |
| 62 | +}); |
| 63 | +``` |
| 64 | + |
| 65 | +All of the [analytics.js](https://segment.com/docs/libraries/analytics.js/) methods are also available on both the `segmentProvider` and `segment` service. You might want to call [.identify()](https://segment.com/docs/libraries/analytics.js/#identify) during your app's config block if you have your user's information available at that time: |
| 66 | +```js |
| 67 | +segmentProvider.identify('user-id', {}); |
| 68 | +``` |
| 69 | + |
| 70 | +### Constant |
| 71 | + |
| 72 | +You can also set any of the configuration options available by providing your own `segmentConfig` constant. You only need to register your constant with your own app using `angular.module('myApp').constant('myConstant', {});`, and the `segmentProvider` will find it. |
| 73 | + |
| 74 | +Your `segmentConfig` constant should overwrite the properties found in [segmentDefaultConfig](https://github.com/aleross/angular-segment-analytics/blob/master/src/config.js). Any properties not overridden will default to the values found in that file. |
| 75 | + |
| 76 | +```js |
| 77 | +angular.module('myApp').constant('segmentConfig', { |
| 78 | + |
| 79 | + // These values will automatically be loaded by the segment service |
| 80 | + apiKey: 'abc', |
| 81 | + condition: function ($rootScope) { |
| 82 | + return $rootScope.isProduction; |
| 83 | + } |
| 84 | +}); |
| 85 | +``` |
| 86 | + |
| 87 | +Read more about [AngularJS constants](https://docs.angularjs.org/api/auto/service/$provide#constant). |
| 88 | + |
| 89 | +### Service |
| 90 | + |
| 91 | +If your API key or other configuration parameters are only available in the run phase of your application then you can load Analytics.js using `segmentLoader.load(apiKey)`, and configure using the `segment` service: |
| 92 | +```js |
| 93 | +angular.module('myApp').controller(function (segment, segmentLoader) { |
| 94 | + segment.setCondition(function ($rootScope) { |
| 95 | + return $rootScope.isProduction; |
| 96 | + }); |
| 97 | + |
| 98 | + // If you don't set the API key using the provider or constant |
| 99 | + // then you need to manually load Analytics.js |
| 100 | + segmentLoader.load('abc'); |
| 101 | +}); |
| 102 | +``` |
| 103 | + |
| 104 | +Typically you should configure 3rd party libraries before the `run()` phase of your AngularJS application, so it's recommended that you use the **provider** or **constant** mechanism for configuring `ngSegment` instead of the service. |
| 105 | + |
| 106 | +## API Documentation |
| 107 | + |
| 108 | +The configuration API is available on the `segmentProvider` and `segment` service. For configuring via a constant, see [`defaultSegmentConfig`](https://github.com/aleross/angular-segment-analytics/blob/master/src/config.js) for the property names to override. |
| 109 | + |
| 110 | +All configuration methods are chainable: |
| 111 | +```js |
| 112 | +segmentProvider |
| 113 | + .setKey('xx') |
| 114 | + .setAutoload(false) |
| 115 | + .setDebug(true); |
| 116 | +``` |
| 117 | + |
| 118 | +### setKey(string) |
| 119 | + |
| 120 | +Sets the API key (or **Write Key**) from your Segment project, found in the setup guide or settings for your project. Your API key is required before Analytics.js can be loaded. |
| 121 | + |
| 122 | +Note: If you don't set the API key during the `.config()` phase of your app (using either the **provider** or **constant** forms of configuration), then ngSegment will not be able to autoload Analytics.js and you'll need to load it manually using `segmentLoader.load(apiKey);`. |
| 123 | + |
| 124 | +### setCondition(injectable callback) |
| 125 | +**Default:** none |
| 126 | +```js |
| 127 | +// Disable tracking for non-production environments |
| 128 | +segmentProvider.setCondition(function ($rootScope) { |
| 129 | + return !$rootScope.environment.isProduction; |
| 130 | +}); |
| 131 | +``` |
| 132 | + |
| 133 | +The callback function is also injected with the analytics.js method name and arguments being called. |
| 134 | +```js |
| 135 | +// Disble tracking for admin users |
| 136 | +segmentProvider.setCondition(function ($rootScope, method, arguments) { |
| 137 | + if (!(method === 'track' and $rootScope.user.isAdmin)) { |
| 138 | + return true; |
| 139 | + } |
| 140 | +}); |
| 141 | +``` |
| 142 | + |
| 143 | +### setAutoload(boolean) |
| 144 | +**Default:** `true` |
| 145 | + |
| 146 | +ngSegment autoloads Segment's Analytics.js before the AngularJS `.run()` phase if an API key has been set. Set autoload to false if you're including analytics.js in your build script. |
| 147 | + |
| 148 | +If you need to load the Segment analytics.js script on-demand, you can use the `segmentLoader` or `segmentLoaderProvider`: |
| 149 | + |
| 150 | +```js |
| 151 | +angular.module('myApp').controller('MyController', function (segmentLoader) { |
| 152 | + segmentLoader.load('abc'); |
| 153 | +}); |
| 154 | +``` |
| 155 | +If you already set the API key via configuration, you can access it using the segment service: |
| 156 | +```js |
| 157 | +angular.module('myApp').controller('MyController', function (segmentLoader) { |
| 158 | + segmentLoader.load(segment.config.apiKey); |
| 159 | +}); |
| 160 | +``` |
| 161 | +or via provider in your application's `config()` block: |
| 162 | +```js |
| 163 | +angular.module('myApp').config(function (segmentLoaderProvider) { |
| 164 | + segmentLoaderProvider.load('abc'); |
| 165 | +}); |
| 166 | +``` |
| 167 | + |
| 168 | +### setLoadDelay(integer) |
| 169 | +**Default:** `0ms` (no delay) |
| 170 | + |
| 171 | +Used in combination with `setAutoload`, this controls the amount of time in milliseconds ngSegment will wait before autoloading Segment's Analytics.js. |
| 172 | + |
| 173 | +**Why:** If your app loads many resources on page load or asynchronously, and your app doesn't require Segment in the first few seconds of application use, then it could be beneficial to defer loading Segment until other required resources have loaded (scripts, css, fonts, images, etc). Depending on the integrations you've enabled, Segment itself will load a series of additional scripts (e.g. Google Analytics, Intercom). Most browsers limit max connections (across multiple host names) to 17 connections at a time. If you don't hit this limit by the time Analytics.js is autoloaded, then you won't see any benefit from delaying. Note: any events tracked using ngSegment before Analytics.js has loaded will be queued and replayed once Analytics.js has been loaded. If the user leaves or reloads the page before this, then the events will be lost. |
| 174 | + |
| 175 | +If you're using the `segmentLoader` to manually load Analytics.js and still want to introduce a load delay, then instead of `setLoadDelay` you can pass in a delay in milliseconds as the second parameter to `.load()`: |
| 176 | + |
| 177 | +```js |
| 178 | +angular.module('myApp').controller('MyController', function (segmentLoader) { |
| 179 | + |
| 180 | + // Delay loading Analytics.js for 3 seconds |
| 181 | + segmentLoader.load(segment.config.apiKey, 3000); |
| 182 | +}); |
| 183 | +``` |
| 184 | + |
| 185 | +### setEvents(object) |
| 186 | +**Default:** none |
| 187 | + |
| 188 | +Stores an object on the segment service for easy reference later using `segment.events`. |
| 189 | + |
| 190 | +**Why:** if your app tracks many unique events, it will quickly become unwieldy to keep track of event names if they're hard-coded in your code each time you call `segment.track('Event Name', eventData)`. For better organization, you may want to create an Angular constant to store all events your app uses by name. You can store this constant on the segment service so you don't need to inject your event names constant into every controller/service/etc that uses `segment`. |
| 191 | + |
| 192 | +```js |
| 193 | +angular.module('myApp').constant('SegmentEvents', { |
| 194 | + SIGNED_UP: 'Signed Up' |
| 195 | +}); |
| 196 | + |
| 197 | +angular.module('myApp').config(function (segmentProvider, SegmentEvents) { |
| 198 | + |
| 199 | + // EventsConstant is a key-value object of events you track |
| 200 | + segmentProvider.setEvents(SegmentEvents); |
| 201 | +}); |
| 202 | + |
| 203 | +angular.module('myApp').controller('MyController', function (segment) { |
| 204 | + |
| 205 | + // Easy constant reference later |
| 206 | + segment.track(segment.events.SIGNED_UP, { plan: 'Startup' }); |
| 207 | +}); |
| 208 | +``` |
| 209 | + |
| 210 | +### setDebug(boolean) |
| 211 | +**Default:** `false` |
| 212 | + |
| 213 | +Enables debug log statements that are helpful for troubleshooting or when first setting up Segment and ngSegment. |
| 214 | + |
| 215 | +### setConfig(object) |
| 216 | + |
| 217 | +Convenience method for setting multiple config properties at once using an object that matches the property names of [`defaultSegmentConfig`](https://github.com/aleross/angular-segment-analytics/blob/master/src/config.js). |
| 218 | + |
| 219 | +```js |
| 220 | +angular.module('myApp').config(function (segmentProvider) { |
| 221 | + |
| 222 | + // Set multiple config properties at once |
| 223 | + segmentProvider.setConfig({ |
| 224 | + debug: true, |
| 225 | + apiKey: 'abc', |
| 226 | + autoload: false |
| 227 | + }); |
| 228 | +}); |
| 229 | +``` |
| 230 | + |
| 231 | + |
| 232 | +## Examples |
| 233 | + |
| 234 | +The `segment` service and `segmentProvider` implement most methods from [Analytics.js](https://segment.com/docs/libraries/analytics.js/). Check [`segmentDefaultConfig.methods`](https://github.com/aleross/angular-segment-analytics/blob/master/src/config.js) for a complete list. |
| 235 | + |
| 236 | +### Page tracking |
| 237 | +```js |
| 238 | +$rootScope.$on('$routeChangeSuccess', function () { |
| 239 | + segment.pageview($location.path()); |
| 240 | +}); |
| 241 | +``` |
| 242 | + |
| 243 | +### Event tracking |
| 244 | +```js |
| 245 | +$scope.myAction = function () { |
| 246 | + segment.track(); |
| 247 | +}); |
| 248 | +``` |
0 commit comments