@microsoft/1ds-post-js 4.4.0-nightlybeta3.2505-35 → 4.4.0-nightlybeta3.2507-23

package/README.md

@@ -40,39 +40,39 @@ appInsightsCore.initialize(coreConfig, []);
 
 | Config | Description | Type
 |----------------|--------------|----
-| eventsLimitInMem     | The number of events that can be kept in memory before the SDK starts to drop events. By default, this is 10,000.|number
-| immediateEventLimit | [Optional] Sets the maximum number of immediate latency events that will be cached in memory before the SDK starts to drop other immediate events only, does not drop normal and real time latency events as immediate events have their own internal queue. Under normal situations immediate events are scheduled to be sent in the next Javascript execution cycle, so the typically number of immediate events is small (~1), the only time more than one event may be present is when the channel is paused or immediate send is disabled (via manual transmit profile). By default max number of events is 500 and the default transmit time is 0ms. Added in v3.1.1 | number
-|  autoFlushEventsLimit | [Optional] If defined, once this number of events has been queued the system perform a flush() to send the queued events without waiting for the normal schedule timers. Default is undefined | number
-|  httpXHROverride      |The HTTP override that should be used to send requests, request properties and headers should be added to the request to maintain correct functionality with other plugins.|IXHROverride
-|  overrideInstrumentationKey     |Override for Instrumentation key.|string
-|  overrideEndpointUrl     |Override for Endpoint where telemetry data is sent.|string
-|  disableTelemetry     |The master off switch.  Do not send any data if set to TRUE.|boolean
-|  ignoreMc1Ms0CookieProcessing     |MC1 and MSFPC cookies will not be provided. Default is false.|boolean
-|  payloadPreprocessor |POST channel preprocessing function. Can be used to gzip the payload (and set appropriate HTTP headers) before transmission. |[Function](./src/DataModels.ts)
-|  payloadListener |POST channel function hook to listen to events being sent, called after the batched events have been committed to be sent. Also used by Remote DDV Channel to send requests. |[Function](./src/DataModels.ts)
-| disableEventTimings | [Optional] By default additional timing metrics details are added to each event after they are sent to allow you to review how long it took to create serialized request. As not all users require this level of detail and it's now possible to get the same metrics via the IPerfManager and IPerfEvent, so you can now disabled this previous level. Default value is false to retain the previous behavior, if you are not using these metrics and performance is a concern then it is recommended to set this value to true. | boolean
-| valueSanitizer | [Optional] The value sanitizer to use while constructing the envelope, if not provided the default sanitizeProperty() method is called to validate and convert the fields for serialization. The path / fields names are based on the format of the envelope (serialized object) as defined via the [Common Schema 4.0](https://aka.ms/CommonSchema) specification. | IValueSanitizer
-| stringifyObjects | [Optional] During serialization, when an object is identified should the object serialized by true => JSON.stringify(theObject); otherwise theObject.toString(). Defaults to false. | boolean
-| enableCompoundKey | [Optional] Enables support for objects with compound keys which indirectly represent an object eg. event: { "somedata.embeddedvalue": 123 }  where the "key" of the object contains a "." as part of it's name.  Defaults to false. | boolean
-| disableOptimizeObj | [Optional] Switch to disable the v8 `optimizeObject()` calls used to provide better serialization performance. Defaults to false. | boolean
-| transports | [Optional] Either an array or single value identifying the requested `TransportType` (const enum) type that should be used. This is used during initialization to identify the requested send transport, it will be ignored if a httpXHROverride is provided. | number or number[]
-| useSendBeacon | [Optional] A flag to enable or disable the usage of the sendBeacon() API if available by the runtime. If running on ReactNative this defaults to `false` for all other cases it defaults to `true`.
-| disableFetchKeepAlive | [Optional] A flag to disable the usage of the [fetch with keep-alive](https://javascript.info/fetch-api#keepalive) support.
-| unloadTransports | [Optional] Either an array or single value identifying the requested TransportType type(s) that should be used during unload or events marked as sendBeacon. This is used during initialization to identify the requested send transport, it will be ignored if a httpXHROverride is provided and alwaysUseXhrOverride is true.
-| avoidOptions<br/><sub><i>(Since 3.1.10+)</i></sub><br /><sub>Default: false (Since 3.2.0)<br />Previously true</sub> | [Optional] Avoid adding request headers to the outgoing request that would cause a pre-flight (OPTIONS) request to be sent for each request. | boolean
-| xhrTimeout<br/><sub><i>(Since 3.1.11+)</i></sub>  | [Optional] Specify a timeout (in ms) to apply to requests when sending requests using XHR or fetch() requests only, does not affect sendBeacon() or XDR (XDomainRequest) usage. Defaults to undefined and therefore the runtime defaults (normally zero for browser environments) | number
-| disableXhrSync<br/><sub><i>(Since 3.1.11+)</i></sub> | [Optional] When using [Xhr](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) for sending requests disable sending as synchronous during unload or synchronous flush. __You should enable this feature for IE (when there is no sendBeacon() or fetch (with keep-alive) support) and you have clients that end up blocking the UI during page unloading__. <span style="color:red">This will cause ALL XHR requests to be sent asynchronously which during page unload may result in the lose of telemetry</span>. This does not affect any other request type (fetch(), sendBeacon() or XDR (XDomainRequest)) | boolean<br/>Default: undefined
-| alwaysUseXhrOverride<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] By default during unload (or when you specify to use sendBeacon() or sync fetch (with keep-alive) for an event) the SDK ignores any provided httpXhrOverride and attempts to use sendBeacon() or fetch(with keep-alive) when they are available. When this configuration option is true any provided httpXhrOverride will always be used, so any provided httpXhrOverride will also need to "handle" the synchronous unload scenario. | boolean<br /> Default: false
-| maxEventRetryAttempts<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] Identifies the number of times any single event will be retried if it receives a failed (retirable) response, this  causes the event to be internally "requeued" and resent in the next batch. As each normal batched send request is retried at least once before starting to increase the internal backoff send interval, normally batched events will generally be attempted the next nearest even number of times. This means that the total number of actual send attempts will almost always be even (setting to 5 will cause 6 requests), unless using manual synchronous flushing (calling flush(false)) which is not subject to request level retry attempts. | number<br/>Default: 6
-| maxUnloadEventRetryAttempts<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] Identifies the number of times any single event will be retried if it receives a failed (retriable) response as part of processing / flushing events once a page unload state has been detected, this causes the event to be internally "requeued" and resent in the next batch, which during page unload. Unlike the normal batching process, send requests are never retried, so the value listed here is always the maximum number of attempts for any single event.<br/>Notes: The SDK by default will use the sendBeacon() API if it exists which is treated as a fire and forget successful response, so for environments that support or supply this API the events won't be retried (because they will be deeded to be successfully sent). When an environment (IE) doesn't support sendBeacon(), this will cause multiple synchronous (by default) XMLHttpRequests to be sent, which will block the UI until a response is received. You can disable ALL synchronous XHR requests by setting the 'disableXhrSync' configuration setting and/or changing this value to 0 or 1. | number<br/>Default: 2
-| addNoResponse <br /><sub><i>(Since 3.2.8+)</i></sub> | [Optional] flag to indicate whether the sendBeacon and fetch (with keep-alive flag) should add the "NoResponseBody" query string value to indicate that the server should return a 204 for successful requests. | boolean<br/>Default: true
-| disableZip <br /><sub><i>(Since 4.3.7+)</i></sub> | [Optional] flag to use CompressionStream API to compress the payload. Compression will only occur if the event is asynchronous. For events like unloads, compression will not be applied. * Note: if user set payloadPreprocessor, this zip compression will not be applied. | boolean<br/>Default: true
+| [eventsLimitInMem](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#eventsLimitInMem)     | The number of events that can be kept in memory before the SDK starts to drop events. By default, this is 10,000.|number
+| [immediateEventLimit](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#immediateEventLimit) | [Optional] Sets the maximum number of immediate latency events that will be cached in memory before the SDK starts to drop other immediate events only, does not drop normal and real time latency events as immediate events have their own internal queue. Under normal situations immediate events are scheduled to be sent in the next Javascript execution cycle, so the typically number of immediate events is small (~1), the only time more than one event may be present is when the channel is paused or immediate send is disabled (via manual transmit profile). By default max number of events is 500 and the default transmit time is 0ms. Added in v3.1.1 | number
+|  [autoFlushEventsLimit](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#autoFlushEventsLimit) | [Optional] If defined, once this number of events has been queued the system perform a flush() to send the queued events without waiting for the normal schedule timers. Default is undefined | number
+|  [httpXHROverride](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#httpXHROverride)      |The HTTP override that should be used to send requests, request properties and headers should be added to the request to maintain correct functionality with other plugins.|IXHROverride
+|  [overrideInstrumentationKey](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#overrideInstrumentationKey)     |Override for Instrumentation key.|string
+|  [overrideEndpointUrl](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#overrideEndpointUrl)     |Override for Endpoint where telemetry data is sent.|string
+|  [disableTelemetry](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#disableTelemetry)     |The master off switch.  Do not send any data if set to TRUE.|boolean
+|  [ignoreMc1Ms0CookieProcessing](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#ignoreMc1Ms0CookieProcessing)     |MC1 and MSFPC cookies will not be provided. Default is false.|boolean
+|  [payloadPreprocessor](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#payloadPreprocessor) |POST channel preprocessing function. Can be used to gzip the payload (and set appropriate HTTP headers) before transmission. |[Function](./src/DataModels.ts)
+|  [payloadListener](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#payloadListener) |POST channel function hook to listen to events being sent, called after the batched events have been committed to be sent. Also used by Remote DDV Channel to send requests. |[Function](./src/DataModels.ts)
+| [disableEventTimings](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#disableEventTimings) | [Optional] By default additional timing metrics details are added to each event after they are sent to allow you to review how long it took to create serialized request. As not all users require this level of detail and it's now possible to get the same metrics via the IPerfManager and IPerfEvent, so you can now disabled this previous level. Default value is false to retain the previous behavior, if you are not using these metrics and performance is a concern then it is recommended to set this value to true. | boolean
+| [valueSanitizer](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#valueSanitizer) | [Optional] The value sanitizer to use while constructing the envelope, if not provided the default sanitizeProperty() method is called to validate and convert the fields for serialization. The path / fields names are based on the format of the envelope (serialized object) as defined via the [Common Schema 4.0](https://aka.ms/CommonSchema) specification. | IValueSanitizer
+| [stringifyObjects](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#stringifyObjects) | [Optional] During serialization, when an object is identified should the object serialized by true => JSON.stringify(theObject); otherwise theObject.toString(). Defaults to false. | boolean
+| [enableCompoundKey](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#enableCompoundKey) | [Optional] Enables support for objects with compound keys which indirectly represent an object eg. event: { "somedata.embeddedvalue": 123 }  where the "key" of the object contains a "." as part of it's name.  Defaults to false. | boolean
+| [disableOptimizeObj](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#disableOptimizeObj) | [Optional] Switch to disable the v8 `optimizeObject()` calls used to provide better serialization performance. Defaults to false. | boolean
+| [transports](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#transports) | [Optional] Either an array or single value identifying the requested `TransportType` (const enum) type that should be used. This is used during initialization to identify the requested send transport, it will be ignored if a httpXHROverride is provided. | number or number[]
+| [useSendBeacon](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#useSendBeacon) | [Optional] A flag to enable or disable the usage of the sendBeacon() API if available by the runtime. If running on ReactNative this defaults to `false` for all other cases it defaults to `true`.
+| [disableFetchKeepAlive](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#disableFetchKeepAlive) | [Optional] A flag to disable the usage of the [fetch with keep-alive](https://javascript.info/fetch-api#keepalive) support.
+| [unloadTransports](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#unloadTransports) | [Optional] Either an array or single value identifying the requested TransportType type(s) that should be used during unload or events marked as sendBeacon. This is used during initialization to identify the requested send transport, it will be ignored if a httpXHROverride is provided and alwaysUseXhrOverride is true.
+| [avoidOptions](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#avoidOptions)<br/><sub><i>(Since 3.1.10+)</i></sub><br /><sub>Default: false (Since 3.2.0)<br />Previously true</sub> | [Optional] Avoid adding request headers to the outgoing request that would cause a pre-flight (OPTIONS) request to be sent for each request. | boolean
+| [xhrTimeout](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#xhrTimeout)<br/><sub><i>(Since 3.1.11+)</i></sub>  | [Optional] Specify a timeout (in ms) to apply to requests when sending requests using XHR or fetch() requests only, does not affect sendBeacon() or XDR (XDomainRequest) usage. Defaults to undefined and therefore the runtime defaults (normally zero for browser environments) | number
+| [disableXhrSync](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#disableXhrSync)<br/><sub><i>(Since 3.1.11+)</i></sub> | [Optional] When using [Xhr](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) for sending requests disable sending as synchronous during unload or synchronous flush. __You should enable this feature for IE (when there is no sendBeacon() or fetch (with keep-alive) support) and you have clients that end up blocking the UI during page unloading__. <span style="color:red">This will cause ALL XHR requests to be sent asynchronously which during page unload may result in the lose of telemetry</span>. This does not affect any other request type (fetch(), sendBeacon() or XDR (XDomainRequest)) | boolean<br/>Default: undefined
+| [alwaysUseXhrOverride](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#alwaysUseXhrOverride)<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] By default during unload (or when you specify to use sendBeacon() or sync fetch (with keep-alive) for an event) the SDK ignores any provided httpXhrOverride and attempts to use sendBeacon() or fetch(with keep-alive) when they are available. When this configuration option is true any provided httpXhrOverride will always be used, so any provided httpXhrOverride will also need to "handle" the synchronous unload scenario. | boolean<br /> Default: false
+| [maxEventRetryAttempts](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#maxEventRetryAttempts)<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] Identifies the number of times any single event will be retried if it receives a failed (retirable) response, this  causes the event to be internally "requeued" and resent in the next batch. As each normal batched send request is retried at least once before starting to increase the internal backoff send interval, normally batched events will generally be attempted the next nearest even number of times. This means that the total number of actual send attempts will almost always be even (setting to 5 will cause 6 requests), unless using manual synchronous flushing (calling flush(false)) which is not subject to request level retry attempts. | number<br/>Default: 6
+| [maxUnloadEventRetryAttempts](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#maxUnloadEventRetryAttempts)<br /><sub><i>(Since 3.1.11+)</i></sub> | [Optional] Identifies the number of times any single event will be retried if it receives a failed (retriable) response as part of processing / flushing events once a page unload state has been detected, this causes the event to be internally "requeued" and resent in the next batch, which during page unload. Unlike the normal batching process, send requests are never retried, so the value listed here is always the maximum number of attempts for any single event.<br/>Notes: The SDK by default will use the sendBeacon() API if it exists which is treated as a fire and forget successful response, so for environments that support or supply this API the events won't be retried (because they will be deeded to be successfully sent). When an environment (IE) doesn't support sendBeacon(), this will cause multiple synchronous (by default) XMLHttpRequests to be sent, which will block the UI until a response is received. You can disable ALL synchronous XHR requests by setting the 'disableXhrSync' configuration setting and/or changing this value to 0 or 1. | number<br/>Default: 2
+| [addNoResponse](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#addNoResponse) <br /><sub><i>(Since 3.2.8+)</i></sub> | [Optional] flag to indicate whether the sendBeacon and fetch (with keep-alive flag) should add the "NoResponseBody" query string value to indicate that the server should return a 204 for successful requests. | boolean<br/>Default: true
+| [disableZip](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IChannelConfiguration.html#disableZip) <br /><sub><i>(Since 4.3.7+)</i></sub> | [Optional] flag to use CompressionStream API to compress the payload. Compression will only occur if the event is asynchronous. For events like unloads, compression will not be applied. * Note: if user set payloadPreprocessor, this zip compression will not be applied. | boolean<br/>Default: true
 
 ### [IXHROverride](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IXHROverride.html)
 
 |  Config   | Description | Type
 |----------------|----------------------------------------|----|
-|  sendPOST     |This method sends data to the specified URI using a POST request. If sync is true then the request is sent synchronously. The <i>oncomplete</i> function should always be called after the request is completed (either successfully or timed out or failed due to errors).|function
+|  [sendPOST](https://microsoft.github.io/ApplicationInsights-JS/webSdk/1ds-post-js/interfaces/IXHROverride.html#sendPOST)     |This method sends data to the specified URI using a POST request. If sync is true then the request is sent synchronously. The <i>oncomplete</i> function should always be called after the request is completed (either successfully or timed out or failed due to errors).|function
 
 ### Payload Preprocessors