| 1 | # analytics.js-core
|
| 2 |
|
| 3 | [](https://circleci.com/gh/segmentio/analytics.js-core)
|
| 4 | [](https://codecov.io/gh/segmentio/analytics.js-core)
|
| 5 |
|
| 6 | This is the core of [Analytics.js](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/), the open-source library that powers data collection at [Segment](https://segment.com).
|
| 7 |
|
| 8 | To build this into a full, usable library, see the [Analytics.js](https://github.com/segmentio/analytics.js) repository.
|
| 9 |
|
| 10 | ## Using Types (v.4.0.0-beta.0 and later)
|
| 11 |
|
| 12 | We recently introduced Typescript support and types to Analytics.js Core. While the exposed types still need some work (pull requests are welcome!), they're ready to be used.
|
| 13 |
|
| 14 | ### Importing as an npm module
|
| 15 |
|
| 16 | If you use analytics.js-core as an npm module, you can use its types out of the box:
|
| 17 | <img src="https://user-images.githubusercontent.com/484013/89060070-2e235f00-d317-11ea-9fd9-e1c77aaca9f9.gif" alt="Example of Types usage in Analytics JS" width="500px">
|
| 18 |
|
| 19 | ### Using types with the AJS Snippet
|
| 20 |
|
| 21 | If you create a source at https://app.segment.com, Segement automatically generates a JS snippet that you can add to your website. (for more information visit our [documentation](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/quickstart/)).
|
| 22 |
|
| 23 | To use types with the snippet, add `analytics` as part of the global module.
|
| 24 | Something like this:
|
| 25 |
|
| 26 | ```typescript
|
| 27 | import { SegmentAnalytics } from '@segment/analytics.js-core';
|
| 28 |
|
| 29 | declare global {
|
| 30 | interface Window {
|
| 31 | analytics: SegmentAnalytics.AnalyticsJS;
|
| 32 | }
|
| 33 | }
|
| 34 | ```
|
| 35 |
|
| 36 | ## Using as a standalone `npm` package
|
| 37 | We recommend using the CDN version of `analytics.js` as it offers all the project and workspace specific settings, enabled integrations, and middleware. But if you prefer to use `analytics.js-core` as a standalone npm package using your own tooling & workflow, you can do the following:
|
| 38 |
|
| 39 | 1- Install the dependencies
|
| 40 | ```
|
| 41 | yarn add @segment/analytics.js-core
|
| 42 | yarn add @segment/analytics.js-integration-segmentio
|
| 43 | // you may need this depending on the bundler
|
| 44 | yarn add uuid@^3.4
|
| 45 | ```
|
| 46 |
|
| 47 | 2- Import the dependencies
|
| 48 | ```javascript
|
| 49 | import Analytics from "@segment/analytics.js-core/build/analytics";
|
| 50 | import SegmentIntegration from "@segment/analytics.js-integration-segmentio";
|
| 51 | ```
|
| 52 |
|
| 53 | 3- Initialize Segment and add Segment's own integration
|
| 54 | ```javascript
|
| 55 | // instantiate the library
|
| 56 | const analytics = new Analytics();
|
| 57 |
|
| 58 | // add Segment's own integration ( or any other device mode integration )
|
| 59 | analytics.use(SegmentIntegration);
|
| 60 |
|
| 61 | // define the integration settings object.
|
| 62 | // Since we are using only Segment integration in this example, we only have
|
| 63 | // "Segment.io" in the integrationSettings object
|
| 64 | const integrationSettings = {
|
| 65 | "Segment.io": {
|
| 66 | apiKey: "<YOUR SEGMENT WRITE KEY>",
|
| 67 | retryQueue: true,
|
| 68 | addBundledMetadata: true
|
| 69 | }
|
| 70 | };
|
| 71 |
|
| 72 |
|
| 73 | // Initialize the library
|
| 74 | analytics.initialize(integrationSettings);
|
| 75 |
|
| 76 | // Happy tracking!
|
| 77 | analytics.track('🚀');
|
| 78 | ```
|
| 79 |
|
| 80 | ## License
|
| 81 |
|
| 82 | Released under the [MIT license](LICENSE).
|
| 83 |
|
| 84 | [analytics.js]: https://segment.com/docs/libraries/analytics.js/
|