From 1b5665b27bcef7b22d609221790f1e8a4276685e Mon Sep 17 00:00:00 2001 From: Seth Silesky <5115498+silesky@users.noreply.github.com> Date: Thu, 2 Jan 2025 12:39:36 -0600 Subject: [PATCH 1/4] update settings --- .../libraries/website/javascript/index.md | 53 +++++++++++++++---- 1 file changed, 44 insertions(+), 9 deletions(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index 1dc5df0565..e7b3e2ed2d 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -328,7 +328,6 @@ The Analytics.js utility methods help you change how Segment loads on your page. - [On (Emitter)](#emitter) - [Timeout](#extending-timeout) - [Reset (Logout)](#reset-or-log-out) -- [Keepalive](#keepalive) ### Load @@ -372,7 +371,7 @@ If you want to access end-tool library methods that do not match any Analytics.j ```js -analytics.ready(function() { +analytics.ready(() => { window.mixpanel.set_config({ verbose: true }); }); ``` @@ -422,7 +421,7 @@ analytics.on(method, callback); Example: ```js -analytics.on('track', function(event, properties, options) { +analytics.on('track', (event, properties, options) => { bigdataTool.push(['recordEvent', event]); @@ -461,11 +460,6 @@ The `reset` method only clears the cookies and `localStorage` created by Segment Segment doesn't share `localStorage` across subdomains. If you use Segment tracking on multiple subdomains, you must call `analytics.reset()` for each subdomain to completely clear out the user session. -### Keepalive - -You can utilize this in instances where an API call fires on a hard redirect, and are missed from getting captured in Segment. If you set this flag to true, it enables firing the event before the redirect. This is available for all events. You can read more about this in the [Github PR](https://github.com/segmentio/analytics-next/issues/768#issuecomment-1386100830){:target="_blank"}. - - ## Managing data flow with the Integrations object > success "" @@ -530,7 +524,7 @@ analytics.load('writekey', { integrations: { All: false, 'Google Analytics': tru This way, you can conditionally load integrations based on what customers opt into on your site. The example below shows how you might load only the tools that the user agreed to use. ```js -onConsentDialogClosed(function(consentedTools){ +onConsentDialogClosed((consentedTools) => { analytics.load('writekey', { integrations: consentedTools }) }) ``` @@ -589,6 +583,47 @@ When enabled, Analytics.js automatically retries network and server errors. With Analytics.js stores events in `localStorage` and falls back to in-memory storage when `localStorage` is unavailable. It retries up to 10 times with an incrementally increasing back-off time between each retry. Analytics.js queues up to 100 events at a time to avoid using too much of the device's local storage. See the [destination Retries documentation](/docs/connections/destinations/#retries) to learn more. +## Headers + +### Add custom headers +You can override your headers by custom +```ts +analytics.load("", + { + integrations: { + 'Segment.io': { + deliveryStrategy: { + config: { + headers: { 'x-api-key': 'foo' } + }, + }, + }, + }, + } +``` + +## Keepalive + +You can utilize this in instances where an API call fires on a hard redirect, and are missed from getting captured in Segment. If you set this flag to true, it enables firing the event before the redirect. + +By default, this is set to `false`. This is because there is a 64kb limit for all fetch requests with keepalive. So when sending keepalive requests, you are competing with other in-flight keepalive requests, regardless of being Segment related requests or not -- which can result in data loss in some scenarios. By default, we only use keep-alive if 1. the page is 'unloading' and 2. the user is using batching. + +```ts +analytics.load("", + { + integrations: { + 'Segment.io': { + deliveryStrategy: { + config: { + keepalive: true + }, + }, + }, + }, + } +``` + + ## Batching Batching is the ability to group multiple requests or calls into one request or API call. All requests sent within the same batch have the same `receivedAt` time. With Analytics.js, you can send events to Segment in batches. Sending events in batches enables you to have: - Delivery of multiple events with fewer API calls From b1e0fc52c64d8c0e7d20cb93b56a26a94e094b55 Mon Sep 17 00:00:00 2001 From: pwseg <86626706+pwseg@users.noreply.github.com> Date: Thu, 23 Jan 2025 13:03:14 -0600 Subject: [PATCH 2/4] change the headers --- .../libraries/website/javascript/index.md | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index e7b3e2ed2d..c1c47ad3c2 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -582,25 +582,24 @@ When enabled, Analytics.js automatically retries network and server errors. With Analytics.js stores events in `localStorage` and falls back to in-memory storage when `localStorage` is unavailable. It retries up to 10 times with an incrementally increasing back-off time between each retry. Analytics.js queues up to 100 events at a time to avoid using too much of the device's local storage. See the [destination Retries documentation](/docs/connections/destinations/#retries) to learn more. +## Delivery strategy configuration -## Headers +## Add custom headers + +You can override default headers by providing custom headers in your configuration. Use the `deliveryStrategy.config.headers` option to specify the headers, like in the following example: -### Add custom headers -You can override your headers by custom ```ts -analytics.load("", - { - integrations: { - 'Segment.io': { - deliveryStrategy: { - config: { - headers: { 'x-api-key': 'foo' } - }, - }, - }, - }, +analytics.load("", { + integrations: { + 'Segment.io': { + deliveryStrategy: { + config: { + headers: { 'x-api-key': 'foo' } + } + } + } } -``` +}); ## Keepalive From 5e2768f11ff693cd9d73c14d36a04d5cb492bc0f Mon Sep 17 00:00:00 2001 From: pwseg <86626706+pwseg@users.noreply.github.com> Date: Thu, 23 Jan 2025 13:11:33 -0600 Subject: [PATCH 3/4] clarify keepalive --- .../sources/catalog/libraries/website/javascript/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index c1c47ad3c2..6ee1a181bc 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -603,9 +603,9 @@ analytics.load("", { ## Keepalive -You can utilize this in instances where an API call fires on a hard redirect, and are missed from getting captured in Segment. If you set this flag to true, it enables firing the event before the redirect. +You can use the `keepalive` option to make sure that Segment captures API calls triggered during a hard redirect. When enabled, `keepalive` will try to fire events before the redirect occurs. -By default, this is set to `false`. This is because there is a 64kb limit for all fetch requests with keepalive. So when sending keepalive requests, you are competing with other in-flight keepalive requests, regardless of being Segment related requests or not -- which can result in data loss in some scenarios. By default, we only use keep-alive if 1. the page is 'unloading' and 2. the user is using batching. +By default, `keepalive` is set to false, because all fetch requests with the `keepalive` flag are subject to a 64kb size limit. Additionally, keepalive requests share this size limit with all other in-flight `keepalive` requests, regardless of whether they're related to Segment. This competition for resources can lead to data loss in some scenarios. ```ts analytics.load("", From 5bb1ed835f5332ce403e6bf96477669cc105438e Mon Sep 17 00:00:00 2001 From: pwseg <86626706+pwseg@users.noreply.github.com> Date: Thu, 23 Jan 2025 14:21:01 -0600 Subject: [PATCH 4/4] clean up code snippets and clarify keepalive --- .../libraries/website/javascript/index.md | 34 +++++++++++-------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index 6ee1a181bc..76f9299e47 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -584,7 +584,9 @@ Analytics.js stores events in `localStorage` and falls back to in-memory storage ## Delivery strategy configuration -## Add custom headers +The `deliveryStrategy.config` object lets you customize how data is delivered to Segment. This includes options like setting custom headers and enabling `keepalive` to capture events during hard redirects. + +### Adding custom headers You can override default headers by providing custom headers in your configuration. Use the `deliveryStrategy.config.headers` option to specify the headers, like in the following example: @@ -605,24 +607,28 @@ analytics.load("", { You can use the `keepalive` option to make sure that Segment captures API calls triggered during a hard redirect. When enabled, `keepalive` will try to fire events before the redirect occurs. -By default, `keepalive` is set to false, because all fetch requests with the `keepalive` flag are subject to a 64kb size limit. Additionally, keepalive requests share this size limit with all other in-flight `keepalive` requests, regardless of whether they're related to Segment. This competition for resources can lead to data loss in some scenarios. +By default, `keepalive` is set to false, because all fetch requests with the `keepalive` flag are subject to a 64kb size limit. Additionally, `keepalive` requests share this size limit with all other in-flight `keepalive` requests, regardless of whether they're related to Segment. This competition for resources can lead to data loss in some scenarios. + +Segment only uses `keepalive` by default if: +- The browser detects that the page is unloading (like if the user closes the tab or navigates away). +- You have batching enabled. + +To enable `keepalive`, use the following configuration: ```ts -analytics.load("", - { - integrations: { - 'Segment.io': { - deliveryStrategy: { - config: { - keepalive: true - }, - }, - }, - }, +analytics.load("", { + integrations: { + 'Segment.io': { + deliveryStrategy: { + config: { + keepalive: true + } + } + } } +}); ``` - ## Batching Batching is the ability to group multiple requests or calls into one request or API call. All requests sent within the same batch have the same `receivedAt` time. With Analytics.js, you can send events to Segment in batches. Sending events in batches enables you to have: - Delivery of multiple events with fewer API calls