--- title: Analytics API Reference Documentation description: The core analytics API docs for the open-source analytics module pageTitle: API Reference subTitle: Core analytics API --- The core `analytics` API is exposed once the library is initialized with [configuration](#configuration). > TLDR; read the [getting started guide](http://getanalytics.io/tutorials/getting-started/) **Using analytics** 1. Initialize analytics with [configuration](#configuration) 2. Export the analytics instance with third-party providers (Google Analytics, HubSpot, etc.) 3. Use [`page`](#analyticspage), [`identify`](#analyticsidentify), [`track`](#analyticstrack) in your app 4. [Add an analytics provider](http://getanalytics.io/tutorials/getting-started/#3-connect-plugins) 5. [Write custom plugins](http://getanalytics.io/plugins/writing-plugins) ## `Configuration` Analytics library configuration After the library is initialized with config, the core API is exposed & ready for use in the application. **Arguments** - **config** object - analytics core config - **[config.app]** (optional) string - Name of site / app - **[config.version]** (optional) string|number - Version of your app - **[config.debug]** (optional) boolean - Should analytics run in debug mode - **[config.plugins]** (optional) Array.<AnalyticsPlugin> - Array of analytics plugins **Example** ```js import Analytics from 'analytics' import pluginABC from 'analytics-plugin-abc' import pluginXYZ from 'analytics-plugin-xyz' // initialize analytics const analytics = Analytics({ app: 'my-awesome-app', plugins: [ pluginABC, pluginXYZ ] }) ``` ## `analytics.identify` Identify a user. This will trigger `identify` calls in any installed plugins and will set user data in localStorage **Arguments** - **userId** String - Unique ID of user - **[traits]** (optional) Object - Object of user traits - **[options]** (optional) Object - Options to pass to identify call - **[callback]** (optional) Function - Callback function after identify completes **Example** ```js // Basic user id identify analytics.identify('xyz-123') // Identify with additional traits analytics.identify('xyz-123', { name: 'steve', company: 'hello-clicky' }) // Fire callback with 2nd or 3rd argument analytics.identify('xyz-123', () => { console.log('do this after identify') }) // Disable sending user data to specific analytic tools analytics.identify('xyz-123', {}, { plugins: { // disable sending this identify call to segment segment: false } }) // Send user data to only to specific analytic tools analytics.identify('xyz-123', {}, { plugins: { // disable this specific identify in all plugins except customerio all: false, customerio: true } }) ``` ## `analytics.track` Track an analytics event. This will trigger `track` calls in any installed plugins **Arguments** - **eventName** String - Event name - **[payload]** (optional) Object - Event payload - **[options]** (optional) Object - Event options - **[callback]** (optional) Function - Callback to fire after tracking completes **Example** ```js // Basic event tracking analytics.track('buttonClicked') // Event tracking with payload analytics.track('itemPurchased', { price: 11, sku: '1234' }) // Fire callback with 2nd or 3rd argument analytics.track('newsletterSubscribed', () => { console.log('do this after track') }) // Disable sending this event to specific analytic tools analytics.track('cartAbandoned', { items: ['xyz', 'abc'] }, { plugins: { // disable track event for segment segment: false } }) // Send event to only to specific analytic tools analytics.track('customerIoOnlyEventExample', { price: 11, sku: '1234' }, { plugins: { // disable this specific track call all plugins except customerio all: false, customerio: true } }) ``` ## `analytics.page` Trigger page view. This will trigger `page` calls in any installed plugins **Arguments** - **[data]** (optional) PageData - Page data overrides. - **[options]** (optional) Object - Page tracking options - **[callback]** (optional) Function - Callback to fire after page view call completes **Example** ```js // Basic page tracking analytics.page() // Page tracking with page data overrides analytics.page({ url: 'https://google.com' }) // Fire callback with 1st, 2nd or 3rd argument analytics.page(() => { console.log('do this after page') }) // Disable sending this pageview to specific analytic tools analytics.page({}, { plugins: { // disable page tracking event for segment segment: false } }) // Send pageview to only to specific analytic tools analytics.page({}, { plugins: { // disable this specific page in all plugins except customerio all: false, customerio: true } }) ``` ## `analytics.user` Get user data **Arguments** - **[key]** (optional) string - dot.prop.path of user data. Example: 'traits.company.name' **Example** ```js // Get all user data const userData = analytics.user() // Get user id const userId = analytics.user('userId') // Get user company name const companyName = analytics.user('traits.company.name') ``` ## `analytics.reset` Clear all information about the visitor & reset analytic state. **Arguments** - **[callback]** (optional) Function - Handler to run after reset **Example** ```js // Reset current visitor analytics.reset() ``` ## `analytics.ready` Fire callback on analytics ready event **Arguments** - **callback** Function - function to trigger when all providers have loaded **Example** ```js analytics.ready((payload) => { console.log('all plugins have loaded or were skipped', payload); }) ``` ## `analytics.on` Attach an event handler function for analytics lifecycle events. **Arguments** - **name** String - Name of event to listen to - **callback** Function - function to fire on event **Example** ```js // Fire function when 'track' calls happen analytics.on('track', ({ payload }) => { console.log('track call just happened. Do stuff') }) // Remove listener before it is called const removeListener = analytics.on('track', ({ payload }) => { console.log('This will never get called') }) // cleanup .on listener removeListener() ``` ## `analytics.once` Attach a handler function to an event and only trigger it once. **Arguments** - **name** String - Name of event to listen to - **callback** Function - function to fire on event **Example** ```js // Fire function only once per 'track' analytics.once('track', ({ payload }) => { console.log('This is only triggered once when analytics.track() fires') }) // Remove listener before it is called const listener = analytics.once('track', ({ payload }) => { console.log('This will never get called b/c listener() is called') }) // cleanup .once listener before it fires listener() ``` ## `analytics.getState` Get data about user, activity, or context. Access sub-keys of state with `dot.prop` syntax. **Arguments** - **[key]** (optional) string - dot.prop.path value of state **Example** ```js // Get the current state of analytics analytics.getState() // Get a subpath of state analytics.getState('context.offline') ``` ## `analytics.storage` Storage utilities for persisting data. These methods will allow you to save data in localStorage, cookies, or to the window. **Example** ```js // Pull storage off analytics instance const { storage } = analytics // Get value storage.getItem('storage_key') // Set value storage.setItem('storage_key', 'value') // Remove value storage.removeItem('storage_key') ``` ### `analytics.storage.getItem` Get value from storage **Arguments** - **key** String - storage key - **[options]** (optional) Object - storage options **Example** ```js analytics.storage.getItem('storage_key') ``` ### `analytics.storage.setItem` Set storage value **Arguments** - **key** String - storage key - **value** any - storage value - **[options]** (optional) Object - storage options **Example** ```js analytics.storage.setItem('storage_key', 'value') ``` ### `analytics.storage.removeItem` Remove storage value **Arguments** - **key** String - storage key - **[options]** (optional) Object - storage options **Example** ```js analytics.storage.removeItem('storage_key') ``` ## `analytics.plugins` Async Management methods for plugins. This is also where [custom methods](https://bit.ly/329vFXy) are loaded into the instance. **Example** ```js // Enable a plugin by namespace analytics.plugins.enable('keenio') // Disable a plugin by namespace analytics.plugins.disable('google-analytics') ``` ### `analytics.plugins.enable` Enable analytics plugin **Arguments** - **plugins** string|Array.<string> - name of plugins(s) to disable - **[callback]** (optional) Function - callback after enable runs **Example** ```js analytics.plugins.enable('google-analytics').then(() => { console.log('do stuff') }) // Enable multiple plugins at once analytics.plugins.enable(['google-analytics', 'segment']).then(() => { console.log('do stuff') }) ``` ### `analytics.plugins.disable` Disable analytics plugin **Arguments** - **plugins** string|Array.<string> - name of integration(s) to disable - **callback** Function - callback after disable runs **Example** ```js analytics.plugins.disable('google').then(() => { console.log('do stuff') }) analytics.plugins.disable(['google', 'segment']).then(() => { console.log('do stuff') }) ```