|
1 | 1 | --- |
2 | | -title: Analytics for Node.js Next |
| 2 | +title: Analytics for Node.js 2.0 |
3 | 3 | repo: analytics-node |
4 | 4 | strat: node-js |
5 | 5 | --- |
6 | 6 |
|
7 | | -Segment's Analytics Node.js Next library lets you record analytics data from your node code. The requests hit Segment's servers, and then Segment routes your data to any destinations you have enabled. |
| 7 | +Segment's Analytics Node.js 2.0 library lets you record analytics data from your node code. The requests hit Segment's servers, and then Segment routes your data to any destinations you have enabled. |
8 | 8 |
|
9 | 9 | The [Segment Analytics Node.js Next library is open-source](https://github.com/segmentio/analytics-next){:target="_blank"} on GitHub. |
10 | 10 |
|
11 | 11 | All of Segment's server-side libraries are built for high-performance, so you can use them in your web server controller code. This library uses an internal queue to make `identify` and `track` calls non-blocking and fast. It also batches messages and flushes asynchronously to Segment's servers. |
12 | 12 |
|
| 13 | +> info "Using Analytics for Node.js Classic?" |
| 14 | +> If you’re still using the classic version of Analytics for Node.js, you can refer to the documentation [here](/docs/connections/sources/catalog/libraries/server/node/). |
| 15 | +> <br><br>On [date], Segment will end support for Analytics Node.js Classic, which includes versions [#] and older. Upgrade to Analytics Node.js 2.0. See the Analytics Node.js 2.0 docs to learn more. |
| 16 | +
|
13 | 17 | ## Getting Started |
14 | 18 |
|
15 | 19 | > warning "" |
@@ -430,6 +434,132 @@ analytics.on('identify', (ctx) => console.log(err)) |
430 | 434 | analytics.on('track', (ctx) => console.log(ctx)) |
431 | 435 | ``` |
432 | 436 |
|
| 437 | +## Plugin architecture |
| 438 | +When you develop against Analytics 2.0, the plugins you write can augment functionality, enrich data, and control the flow and delivery of events. From modifying event payloads to changing analytics functionality, plugins help to speed up the process of getting things done. |
| 439 | + |
| 440 | +Though middlewares function the same as plugins, it's best to use plugins as they are easier to implement and are more testable. |
| 441 | + |
| 442 | +### Plugin categories |
| 443 | +Plugins are bound by Analytics 2.0 which handles operations such as observability, retries, and error handling. There are two different categories of plugins: |
| 444 | +* **Critical Plugins**: Analytics.js expects this plugin to be loaded before starting event delivery. Failure to load a critical plugin halts event delivery. Use this category sparingly, and only for plugins that are critical to your tracking. |
| 445 | +* **Non-critical Plugins**: Analytics.js can start event delivery before this plugin finishes loading. This means your plugin can fail to load independently from all other plugins. For example, every Analytics.js destination is a non-critical plugin. This makes it possible for Analytics.js to continue working if a partner destination fails to load, or if users have ad blockers turned on that are targeting specific destinations. |
| 446 | + |
| 447 | +> info "" |
| 448 | +> Non-critical plugins are only non-critical from a loading standpoint. For example, if the `before` plugin crashes, this can still halt the event delivery pipeline. |
| 449 | +
|
| 450 | +Non-critical plugins run through a timeline that executes in order of insertion based on the entry type. Segment has these five entry types of non-critical plugins: |
| 451 | + |
| 452 | +| Type | Details | |
| 453 | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
| 454 | +| `before` | Executes before event processing begins. These are plugins that run before any other plugins run. <br><br>For example, validating events before passing them along to other plugins. A failure here could halt the event pipeline. <br><br> See the example of how Analytics.js uses the [Event Validation plugin](https://github.com/segmentio/analytics-next/blob/master/packages/browser/src/plugins/validation/index.ts){:target="_blank"} to verify that every event has the correct shape. | |
| 455 | +| `enrichment` | Executes as the first level of event processing. These plugins modify an event. <br><br> See the example of how Analytics.js uses the [Page Enrichment plugin](https://github.com/segmentio/analytics-next/blob/master/packages/browser/src/plugins/page-enrichment/index.ts){:target="_blank"} to enrich every event with page information. | |
| 456 | +| `destination` | Executes as events begin to pass off to destinations. <br><br> This doesn't modify the event outside of the specific destination, and failure doesn't halt the execution. | |
| 457 | +| `after` | Executes after all event processing completes. You can use this to perform cleanup operations. <br><br>An example of this is the [Segment.io Plugin](https://github.com/segmentio/analytics-next/blob/master/packages/browser/src/plugins/segmentio/index.ts){:target="_blank"} which waits for destinations to succeed or fail so it can send it observability metrics. | |
| 458 | +| `utility` | Executes once during the bootstrap, to give you an outlet to make any modifications as to how Analytics.js works internally. This allows you to augment Analytics.js functionality. | |
| 459 | + |
| 460 | +### Example plugins |
| 461 | +Here's an example of a plugin that converts all track event names to lowercase before the event goes through the rest of the pipeline: |
| 462 | + |
| 463 | +```js |
| 464 | +export const lowercase: Plugin = { |
| 465 | + name: 'Lowercase events', |
| 466 | + type: 'enrichment', |
| 467 | + version: '1.0.0', |
| 468 | + |
| 469 | + isLoaded: () => true, |
| 470 | + load: () => Promise.resolve(), |
| 471 | + |
| 472 | + track: (ctx) => { |
| 473 | + ctx.updateEvent('event', ctx.event.event.toLowerCase()) |
| 474 | + return ctx |
| 475 | + } |
| 476 | +} |
| 477 | + |
| 478 | +const identityStitching = () => { |
| 479 | + let user |
| 480 | + |
| 481 | + const identity = { |
| 482 | + // Identifies your plugin in the Plugins stack. |
| 483 | + // Access `window.analytics.queue.plugins` to see the full list of plugins |
| 484 | + name: 'Identity Stitching', |
| 485 | + // Defines where in the event timeline a plugin should run |
| 486 | + type: 'enrichment', |
| 487 | + version: '0.1.0', |
| 488 | + |
| 489 | + // use the `load` hook to bootstrap your plugin |
| 490 | + // The load hook will receive a context object as its first argument |
| 491 | + // followed by a reference to the analytics.js instance from the page |
| 492 | + load: async (_ctx, ajs) => { |
| 493 | + user = ajs.user() |
| 494 | + }, |
| 495 | + |
| 496 | + // Used to signal that a plugin has been property loaded |
| 497 | + isLoaded: () => user !== undefined, |
| 498 | + |
| 499 | + // Applies the plugin code to every `identify` call in Analytics.js |
| 500 | + // You can override any of the existing types in the Segment Spec. |
| 501 | + async identify(ctx) { |
| 502 | + // Request some extra info to enrich your `identify` events from |
| 503 | + // an external API. |
| 504 | + const req = await fetch( |
| 505 | + `https://jsonplaceholder.typicode.com/users/${ctx.event.userId}` |
| 506 | + ) |
| 507 | + const userReq = await req.json() |
| 508 | + |
| 509 | + // ctx.updateEvent can be used to update deeply nested properties |
| 510 | + // in your events. It's a safe way to change events as it'll |
| 511 | + // create any missing objects and properties you may require. |
| 512 | + ctx.updateEvent('traits.custom', userReq) |
| 513 | + user.traits(userReq) |
| 514 | + |
| 515 | + // Every plugin must return a `ctx` object, so that the event |
| 516 | + // timeline can continue processing. |
| 517 | + return ctx |
| 518 | + }, |
| 519 | + } |
| 520 | + |
| 521 | + return identity |
| 522 | +} |
| 523 | + |
| 524 | +// Registers Segment's new plugin into Analytics.js |
| 525 | +await window.analytics.register(identityStitching()) |
| 526 | +``` |
| 527 | + |
| 528 | +Here's an example of a `utility` plugin that allows you to change the format of the anonymous_id cookie: |
| 529 | + |
| 530 | +```js |
| 531 | + |
| 532 | +window.analytics.ready(() => { |
| 533 | + window.analytics.register({ |
| 534 | + name: 'Cookie Compatibility', |
| 535 | + version: '0.1.0', |
| 536 | + type: 'utility', |
| 537 | + load: (_ctx, ajs) => { |
| 538 | + const user = ajs.user() |
| 539 | + const cookieJar = user.cookies |
| 540 | + const cookieSetter = cookieJar.set.bind(cookieJar) |
| 541 | + |
| 542 | + // blindly convert any values into JSON strings |
| 543 | + cookieJar.set = (key, value, opts) => cookieSetter(key, JSON.stringify(value), opts) |
| 544 | + |
| 545 | + // stringify any existing IDs |
| 546 | + user.anonymousId(user.anonymousId()) |
| 547 | + user.id(user.id()) |
| 548 | + }, |
| 549 | + isLoaded: () => true |
| 550 | + }) |
| 551 | + }) |
| 552 | +``` |
| 553 | + |
| 554 | +You can view Segment's [existing plugins](https://github.com/segmentio/analytics-next/tree/master/src/plugins){:target="_blank"} to see more examples. |
| 555 | + |
| 556 | +### Register a plugin |
| 557 | +Registering plugins enable you to modify your analytics implementation to best fit your needs. You can register a plugin using this: |
| 558 | + |
| 559 | +```js |
| 560 | +// A promise will resolve once the plugins have been successfully loaded into Analytics.js |
| 561 | +// You can register multiple plugins at once by using the variable args interface in Analytics.js |
| 562 | +await window.analytics.register(pluginA, pluginB, pluginN) |
433 | 563 |
|
434 | 564 | ## Development |
435 | 565 |
|
|
0 commit comments