Merge pull request #7369 from segmentio/add-ajs-settings-info

Add customer header and `keepalive` info to Analytics.js documentation

Author: pwseg

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 })
 })
 ```
@@ -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: