# @segment/analytics.js-integration

> Base factory for analytics.js integrations

Latest version **3.3.4-alpha.5** (published 2023-04-18) · SEE LICENSE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install @segment/analytics.js-integration
pnpm add @segment/analytics.js-integration
yarn add @segment/analytics.js-integration
bun add @segment/analytics.js-integration
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.3.4-alpha.5 |
| Published | 2023-04-18 |
| First published | 2016-05-26 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 20 |
| Unpacked size | 84.5 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 35 |
| Author | Segment |
| Maintainers | needcaffeine, nat-grid, spandananune92, wlumsegment, vivek-26, moyara2, bala.singareddy, gbbastos, sprasannasastry22, akash.gautam07, preetyp, viveksainaneesegment, msaraf, kjoerres, rokatyal, ainatancinco, anton-vylushchak, sowjanyasegment, alayvora, pzawadzki, msaunders-segment, tw-dgarcia, bvakkalagadda, mbreske, nsandhu-segment, parag.panda, blangtwilio, ryanrouleau-segment, twjosiah, mcullenmeyer, nina-y, david.anusontarangkul.segment, mckern_segment, segment-admin, nainy.agrawal, tdibacco, sudojatin, nageshgolem, brandonheyer-segment, teganduong, alfrimpong, dobrin.ganev, ankit.gupta.unthinkable, marinhero, benattwilio, bharath.boregowda, conniechen, sungju.jin, pooyaj, yli119, ea_segment, emilyjia, kx-segment, cvillela_segment, xinghao.huang, harsh.vardhan, joe.ayoub.segment, gkochar123, rollcode, ariel.silvestri, cherylj-segment, leifdreizler, immanoj, aaronklish, michelr, maneesh.dharma29, msolorzano-segment, brianhumphreystwilio, jfehrman.segment, joetessy, pmunin, jalexy12, jbandi-twilio, prayansh-twilio, dominicbarnes, brandon.scott-segment, bgillan, phillip.thomas, ricardo.rossi, forgetfulfellow, fauzy.yy, mayur-pitale, dbaik-twilio-segment, seg-rustybailey, tanya.gupta.segment, pmiller-twilio, nevermore2022, aishikawaki, csayuso, mcoulibali, shupadhyay, swgupta, sumit1606, jahood-twilio, saisagarkappaganthula, dostwal, rmukundan, ngoldman-twilio, apareek-twilio, arubiochavez, shuvrajit9904, s3gm3nt, ama0223, tbrennanj, dangmai-segment, shraddha-twilio, taricjain, snehauppalapati, nitish.dubey, azhaotwilio, ryder.wendt, sa-jsooter, enyi.asonye, afsha-nazim-seg, akurapati, mschaszberger, lnamba, varadarajan-tw, seanhan-segment, replatero, sayan-das-in, justeen, sausingh, jgabe13, haeyoon.paik, kentrollins, meg1000, funlu, ashwitha.bg, whaider_twilio, tcgilbert, kevinburkesegment, felttrip, prabhnoor1997, akashyap91, connormarchand, clintz.seg, karimkeshwani, wally.tg, rhall-twilio, yash-twilio, brookstaylorjr, shayan-golafshani, lerahulram, shpankau, mugelstad, hdamani, brchristy, rrivera-segment, sethnutetwilio, fplinke, manali-bhosale, chtoombs, sethsegment, eric-hyde, elmoselyee, michaelghseg, jayakrishnannair, lateefat, maryam.sharif, wdbetts, ryanligon, sindhusegment, lfdelossantos, aramakrishnan, segment-camden, vbatanov, lluque-twilio, jair.aviles, pmaid, song4you, peterdemartini, emmy.byrne, vincen7tran, dean-huynh, cdignam-segment, abhinavsureka, rikezatsegment, arunlalam-segment, cjradek, neeharikakondipati, simpixelated, chihchun-twilio, acharles14, jyim008, seghungtran, tv0, hema-segment, oscb, krousseau, sachinwathore, fhalim-segment, cfree, hjoonpm, celine-segment, parsa-segment, pmcanseco-segment, ynguyen, masira, amillet89, cholt002, av-segment, aghotikar, vikrant-segment, larryatsegment, lbrink, shivpoojan-segment, ariel_segment, scruwys1, lew-gordon, kyliepedersen, jinapark, segmentio, rajulvadera, lpediredla, n2parko, sahilp, psankaranarayana, tyson_segment, bgamwell, uditmehta, salolivares, erikdw, chenxiangzhang, mericsson, prayansh-segmentt, jeremylarkin, bsneed, danieljackins, segment-seth, james9446, priscilla.giatti, kellylu, nlsun, drew-thompson, segment-jsingh, andrius-segment, valerieernst, khinkalilover, kelcook, alistairbarrell, gilomer, marcelopv, eric.rogner, kdharaiya, jon.anderson-at-segment.com, markzegarelli, stacy.song, niveda.balananthan, rexatsegment, nickaguilar, bradenbecker, reneewang, dan.lasky, sam.tapia, vikramkumar19, mpriyad25, jeremy.parker, khamidou-segment, smidges |
| Keywords | analytics.js, segment |

## Links

- npm: https://www.npmjs.com/package/@segment/analytics.js-integration
- Repository: https://github.com/segmentio/analytics.js-integration
- Homepage: https://github.com/segmentio/analytics.js-integration#readme
- Issues: https://github.com/segmentio/analytics.js-integration/issues
- npm.io page: https://npm.io/package/@segment/analytics.js-integration

## Dependencies (20)

- [is](https://npm.io/package/is.md) ^3.1.0
- [debug](https://npm.io/package/debug.md) ^2.2.0
- [domify](https://npm.io/package/domify.md) ^1.4.1
- [extend](https://npm.io/package/extend.md) ^3.0.2
- [next-tick](https://npm.io/package/next-tick.md) ^0.2.2
- [to-no-case](https://npm.io/package/to-no-case.md) ^0.1.3
- [load-iframe](https://npm.io/package/load-iframe.md) 1.0.2-alpha.6
- [@segment/fmt](https://npm.io/package/@segment/fmt.md) ^1.0.0
- [@ndhoule/each](https://npm.io/package/@ndhoule/each.md) ^2.0.1
- [@ndhoule/clone](https://npm.io/package/@ndhoule/clone.md) ^1.0.0
- [@ndhoule/every](https://npm.io/package/@ndhoule/every.md) ^2.0.1
- [@ndhoule/foldl](https://npm.io/package/@ndhoule/foldl.md) ^2.0.1
- [component-bind](https://npm.io/package/component-bind.md) ^1.0.0
- [slug-component](https://npm.io/package/slug-component.md) ^1.1.0
- [@ndhoule/extend](https://npm.io/package/@ndhoule/extend.md) ^2.0.0
- [analytics-events](https://npm.io/package/analytics-events.md) ^2.0.2
- [@ndhoule/defaults](https://npm.io/package/@ndhoule/defaults.md) ^2.0.1
- [@ndhoule/includes](https://npm.io/package/@ndhoule/includes.md) ^2.0.1
- [component-emitter](https://npm.io/package/component-emitter.md) ^1.2.0
- [@segment/load-script](https://npm.io/package/@segment/load-script.md) ^1.0.1

## Recent versions

- 3.3.4-alpha.5 (latest) — 2023-04-18
- 3.3.4-alpha.4 — 2023-04-18
- 3.3.4-alpha.3 — 2023-04-17
- 3.3.4-alpha.2 — 2023-04-17
- 3.3.4-alpha.1 — 2023-04-14
- 3.3.4-alpha.0 — 2023-04-04
- 3.3.3 — 2021-04-29
- 3.3.2 — 2020-04-01
- 3.3.1 — 2019-11-20
- 2.1.1 — 2018-05-22
- 3.3.0 — 2018-04-23
- 3.2.3 — 2018-03-27
- 3.2.2 — 2018-02-09
- 3.2.1 — 2018-02-06
- 3.2.0 — 2016-11-08
- … 5 more at https://npm.io/package/@segment/analytics.js-integration/versions

## README

# analytics.js-integration

[![CircleCI](https://circleci.com/gh/segmentio/analytics.js-integration.svg?style=shield&circle-token=096975c79692a2267d9a92fd412b6b8bb7e3eb0a)](https://circleci.com/gh/segmentio/analytics.js-integration)
[![Codecov](https://img.shields.io/codecov/c/github/segmentio/analytics.js-integration/master.svg?maxAge=2592000)](https://codecov.io/gh/segmentio/analytics.js-integration)

The base integration factory used to create custom analytics integrations for [Analytics.js](https://github.com/segmentio/analytics.js).

The factory returns a barebones integration that has no logic, so that we can share common pieces of logic—like queueing before an integration is ready, providing a way to default options, etc—in one place.

## Integrating with Segment

Interested in integrating your service with us? Check out our [Partners page](https://segment.com/partners/) for more details.

## Example

```js
var integration = require('@segment/analytics.js-integration');

var Custom = integration('Custom Analytics')
  .global('_custom')
  .assumesPageview()
  .readyOnInitialize();

Custom.prototype.track = function (event, properties) {
  window._custom.push(['track', event, properties]);
};
```

## Facade

This library relies on [`segmentio/facade`](https://github.com/segmentio/facade) which is a helper that makes working with the input to [Analytics.js](https://github.com/segmentio/analytics.js) easier, by handling lots of common cases in one place.

## API

### integration(name)

Create a new `Integration` constructor with the given integration `name`. `name` is the key with which users can `initialize` the integration.

### .option(key, default)

Register a new option for the integration by `key`, with a `default` value.

### .mapping(key)

Add a new mapping option by `key`. The option will be an array that the user can pass in of `key -> value` mappings. This will also generated a `#KEY` method on the integration's prototype for easily accessing the mapping.

For example if your integration only supports a handful of events like `Signed Up` and `Completed Order`, you might create an mapping option called `events` that the user would pass in, like so:

```js
var MyIntegration = Integration('MyIntegration')
  .mapping('events');
```

Which means that when the integration is initialized, it would be passed a mapping of `events` to use, like so:

```js
new MyIntegration({
  events: [
    { key: 'Signed Up', value: 'Register' },
    { key: 'Completed Order', value: 'Purchase' }
  ]
});
```

Then later on, you can easily get all of the entries with a specific key, by calling `this.events(key)`. For example:

```js
MyIntegration.prototype.track = function(track){
  var matches = this.events(track.event());
  each(matches, function(value){
    window._myglobal.push(value);
  });
};
```

### .global(key)

Register a new global variable `key` that the Integration uses. If this key already exists on `window` when `initialize` is called, it will return early, thus ensuring that setup logic and libraries aren't loaded twice.

### .assumesPageview()

Mark the `Integration` as assuming an initial pageview has happened when its Javascript library loads. This is important for integrations whose libraries assume a "pageview" in their interface as soon as the library loads, instead of exposing a `.page()` method or similar to call via Javascript.

This option changes the integration so that the very first call to `page` actually initializes the integration, ensuring that the pageviews aren't accidentally duplicated.

### .readyOnInitialize()

Mark the `Integration` as being ready to accept data after `initialize` is called. This is true of integrations that create queues in their snippets so that they can record data before their library has been downloaded.

### .readyOnLoad()

Mark the `Integration` as being ready to accept data after `load` is called. This is true for integrations that need to wait for their library to load on the page to start recording data.

### #initialize([page])

Initialize the integration. This is where the typical 3rd-party Javascript snippet logic should be. If the integration assumes an initial pageview, `initialize` will be called with the `page` method's arguments.

### #load([callback])

Load the integration's 3rd-party Javascript library, and `callback(err, e)`. The loading logic should be pulled out of the snippet from `initialize` and placed here.

### #identify(facade)

Identify the current user for the integration given an `Identify` [`facade`](https://github.com/segmentio/facade). See the [`identify` method docs](https://segment.io/docs/tracking-api/identify/) for more information.

### #group(facade)

Group the current account/organization/group/etc for the integration given an `Group` [`facade`](https://github.com/segmentio/facade). See the [`group` method docs](https://segment.io/docs/tracking-api/group/) for more information.

### #page(facade)

Transform a `Page` [`facade`](https://github.com/segmentio/facade) into a page view for the integration. See the [`page` method docs](https://segment.io/docs/tracking-api/page-and-screen/) for more information.

[Identify a user.](https://segment.io/docs/tracking-api/identify)

### #track(facade)

Track an event with the integration, given a `Track` [`facade`](https://github.com/segmentio/facade). See the [`track` method docs](https://segment.io/docs/tracking-api/track/) for more information.

### #alias(facade)

Alias two user identities given an `Alias` `facade`. See the [`alias` method docs](https://segment.io/docs/tracking-api/alias/) for more information.

---
_Source: https://npm.io/package/@segment/analytics.js-integration · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._