--- title: Getting started with Analytics description: Start here to learn how to build apps with the analytics npm module pageTitle: Getting Started subTitle: Start here to learn how to build apps with the analytics --- This guide will walk you through installing & wiring up **analytics** in your application. Analytics is designed to work with any frontend javascript framework and it works in plain static HTML. For framework specific implementation examples checkout the main [repo](https://github.com/DavidWells/analytics/tree/master/examples). **Let's jump into it 👇** ## 1. Install the package Install the analytics module into your project via [npm](https://www.npmjs.com/package/analytics) ```bash npm install analytics ``` Or install via `yarn` ```bash yarn add analytics ``` ## 2. Include in project Import `analytics` and initialize the library with the analytics plugins of your choice. ```js{2} /* example file src/analytics.js */ import Analytics from 'analytics' const analytics = Analytics({ app: 'app-name', plugins: [ // ... your analytics integrations ] }) /* export the instance for usage in your app */ export default analytics ``` See the [configuration docs](https://getanalytics.io/api/#configuration) for more details. ## 3. Connect plugins **Connect analytics with a third-party analytics tool** To connect `analytics` to your third-party tools (e.g. Google analytics), install the [provider plugin](https://getanalytics.io/plugins). If there is no plugin for your provider, you can [create a plugin](http://getanalytics.io/plugins/writing-plugins) or send us a [request](https://getanalytics.io/plugins/request/). The example below is showing how to connect google analytics using the [google analytics plugin](https://getanalytics.io/plugins/google-analytics/). This plugin will load the google analytics tracking script onto the page and handle page + custom event tracking. ```js{7-11} /* src/analytics.js */ import Analytics from 'analytics' import googleAnalytics from '@analytics/google-analytics' const analytics = Analytics({ app: 'app-name', plugins: [ googleAnalytics({ trackingId: 'UA-121991123', }) ] }) export default analytics ``` ## 4. Use in your app After we've initialized `analytics`, we need to call the [core methods](https://getanalytics.io/api/) in our application code. Import the `analytics` instance created in the previous step and call a method: - `analytics.page()` to send page view data. - `analytics.track()` to send tracking events to your analytic providers - `analytics.identify` to identify a website visitor ```js // Import analytics instance into your app and call its methods import analytics from './analytics' /* Track page views */ analytics.page() /* Identify users */ analytics.identify('userid-123', { favoriteColor: 'blue', membershipLevel: 'pro' }) /* Track events */ analytics.track('buttonClicked', { value: 100 }) ``` See the api docs for further details: - [Page](https://getanalytics.io/api/#analyticspage) - [Track](https://getanalytics.io/api/#analyticstrack) - [Identify](https://getanalytics.io/api/#analyticsidentify) ## Usage examples Analytics works in the browser and on the server in node.js. In the browser, `analytics` will work with any frontend framework. - [HTML](https://getanalytics.io/tutorials/getting-started/#html) - [React](https://getanalytics.io/tutorials/getting-started/#react) - [Gatsby](https://getanalytics.io/tutorials/getting-started/#gatsby) - [Preact](https://getanalytics.io/tutorials/getting-started/#preact) - [Vue](https://getanalytics.io/tutorials/getting-started/#vue) - [Angular](https://getanalytics.io/tutorials/getting-started/#angular) ### HTML Analytics works in vanilla HTML pages and can be [imported from a CDN](#cdn-browser-usage). [Live demo](https://analytics-html-example.netlify.app/) & the [source code](https://github.com/DavidWells/analytics/tree/master/examples/vanilla-html). ### React Checkout the [using analytics with react demo](https://analytics-react-example.netlify.app/) & the [source code](https://github.com/DavidWells/analytics/tree/master/examples/react) For a larger example see the [kitchen sink example](https://analytics-demo.netlify.app) & its [source code](https://github.com/DavidWells/analytics/tree/master/examples/demo). Also checkout the [`useAnalytics`](http://getanalytics.io/utils/react-hooks) react hooks. ### Gatsby To use analytics with Gatsby install the [gatsby-plugin-analytics](https://www.gatsbyjs.org/packages/gatsby-plugin-analytics/) plugin. [Live demo](https://getanalytics.io/) (this site) & the [source code](https://github.com/DavidWells/analytics/blob/09a720fdd89b5bb418e349cf24e0b4658f2bee95/site/gatsby-theme-oss-docs/src/analytics.js). ```bash npm install gatsby-plugin-analytics ``` And add to your `gatsby.config.js` file. This will enable automate page tracking. ```js { resolve: 'gatsby-plugin-analytics' } ``` See the [gatsby-plugin-analytics docs](https://www.gatsbyjs.org/packages/gatsby-plugin-analytics/) for more details. You can also reference the various [react examples](https://getanalytics.io/tutorials/getting-started/#react) above and directly integrate with a `pushState` listener in your site. ### Preact Preact is a fast 3kB alternative to React with the same modern API. [Using analytics with preact demo](https://analytics-preact-example.netlify.app/) & the [source code](https://github.com/DavidWells/analytics/tree/master/examples/preact). ### Vue [Using analytics with vue demo](https://analytics-vue-example.netlify.app/) & the [source code]( https://github.com/DavidWells/analytics/tree/master/examples/vue). ### Angular Demo coming soon. The above steps will work for Vue apps. ([contributions to the docs welcome](https://github.com/DavidWells/analytics/tree/master/examples) 😃). ### ES6 Usage ```js import Analytics from 'analytics' import googleAnalyticsPlugin from '@analytics/google-analytics' import customerIOPlugin from '@analytics/customerio' /* Initialize analytics */ const analytics = Analytics({ app: 'my-app-name', version: 100, plugins: [ googleAnalyticsPlugin({ trackingId: 'UA-121991291', }), customerIOPlugin({ siteId: '123-xyz' }) ] }) /* Track a page view */ analytics.page() /* Track a custom event */ analytics.track('userPurchase', { price: 20 item: 'pink socks' }) /* Identify a visitor */ analytics.identify('user-id-xyz', { firstName: 'bill', lastName: 'murray', email: 'da-coolest@aol.com' }) ``` ### CDN Browser usage When importing global `analytics` into your project from a cdn the library is expose via a global `_analytics` variable. Call `_analytics.init` to create an analytics instance. ```html ``` If you are including analytics from the `unpkg` CDN via a script tag, it's possible that ad-blockers like uBlock Origin might block the script from loading. This only effects applications importing `analytics` from a CDN. This is because ad-block extensions will block any URL with the word `analytics`. This causes problems! This has been observed in CodeSandbox as well with ad-block browser extensions enabled. If you are including analytics via a `script` tag, it's advised to rename the path and host the analytics script yourself to avoid these issues. Example: ```html ``` ### Node.js Usage For ES6/7 javascript you can `import Analytics from 'analytics'` for normal node.js usage you can import like so: ```js const { Analytics } = require('analytics') // or const Analytics = require('analytics').default const analytics = Analytics({ app: 'my-app-name', version: 100, plugins: [ googleAnalyticsPlugin({ trackingId: 'UA-121991291', }), customerIOPlugin({ siteId: '123-xyz' }) ] }) // Fire a page view analytics.page() ```