Skip to content

Add customer header and keepalive info to Analytics.js documentation #7369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 23, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 });
});
```
Expand Down Expand Up @@ -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]);

Expand Down Expand Up @@ -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 ""
Expand Down Expand Up @@ -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 })
})
```
Expand Down Expand Up @@ -588,6 +582,52 @@ 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

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:

```ts
analytics.load("<YOUR_WRITE_KEY>", {
integrations: {
'Segment.io': {
deliveryStrategy: {
config: {
headers: { 'x-api-key': 'foo' }
}
}
}
}
});

## Keepalive

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.

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("<YOUR_WRITE_KEY>", {
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:
Expand Down
Loading