Interface IChannelConfiguration

The IChannelConfiguration interface holds the configuration details passed to Post module.

interface IChannelConfiguration {
    addNoResponse?: boolean;
    alwaysUseXhrOverride?: boolean;
    autoFlushEventsLimit?: number;
    avoidOptions?: boolean;
    clearTimeoutOverride?: {
        (id: number): void;
        (timeout: string | number | Timeout): void;
    };
    disableAutoBatchFlushLimit?: boolean;
    disableEventTimings?: boolean;
    disableFetchKeepAlive?: boolean;
    disableOptimizeObj?: boolean;
    disableTelemetry?: boolean;
    disableXhrSync?: boolean;
    enableCompoundKey?: boolean;
    eventsLimitInMem?: number;
    excludeCsMetaData?: boolean;
    fetchCredentials?: RequestCredentials;
    httpXHROverride?: IXHROverride;
    ignoreMc1Ms0CookieProcessing?: boolean;
    immediateEventLimit?: number;
    maxEventRetryAttempts?: number;
    maxUnloadEventRetryAttempts?: number;
    overrideEndpointUrl?: string;
    overrideInstrumentationKey?: string;
    payloadListener?: PayloadListenerFunction;
    payloadPreprocessor?: PayloadPreprocessorFunction;
    setTimeoutOverride?: {
        __promisify__<T>(delay?: number, value?: T, options?: TimerOptions): Promise<T>;
        (handler: TimerHandler, timeout?: number, ...arguments: any[]): number;
        <TArgs>(callback: ((...args: TArgs) => void), delay?: number, ...args: TArgs): NodeJS.Timeout;
        (callback: ((_: void) => void), delay?: number): NodeJS.Timeout;
    };
    stringifyObjects?: boolean;
    transports?: number | number[];
    unloadTransports?: number | number[];
    useSendBeacon?: boolean;
    valueSanitizer?: IValueSanitizer;
    xhrTimeout?: number;
}

Properties

OptionaladdNoResponse

addNoResponse?: boolean

[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. Defaults to true

OptionalalwaysUseXhrOverride

alwaysUseXhrOverride?: boolean

[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.

OptionalautoFlushEventsLimit

autoFlushEventsLimit?: number

[Optional] If defined, when the number of queued events reaches or exceeded this limit this will cause the queue to be immediately flushed rather than waiting for the normal timers. Defaults to undefined.

OptionalavoidOptions

avoidOptions?: boolean

[Optional] Avoid adding request headers to the outgoing request that would cause a pre-flight (OPTIONS) request to be sent for each request. This currently defaults to false. This is changed as the collector enables Access-Control-Max-Age to allow the browser to better cache any previous OPTIONS response. Hence, we moved some of the current dynamic values sent on the query string to a header.

OptionalclearTimeoutOverride

clearTimeoutOverride?: {
    (id: number): void;
    (timeout: string | number | Timeout): void;
}

Override for clearTimeout

Type declaration

    • (id): void

    • Parameters

      • id: number

      Returns void

    • (timeout): void

    • Cancels a Timeout object created by setTimeout().

      Parameters

      • timeout: string | number | Timeout

        A Timeout object as returned by setTimeout() or the primitive of the Timeout object as a string or a number.

      Returns void

      Since

      v0.0.1

OptionaldisableAutoBatchFlushLimit

disableAutoBatchFlushLimit?: boolean

[Optional] If defined allows you to disable the auto batch (iKey set of requests) flushing logic. This is in addition to the default transmission profile timers, autoFlushEventsLimit and eventsLimitInMem config values.

OptionaldisableEventTimings

disableEventTimings?: boolean

[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 implementations require this level of detail and it's now possible to get the same metrics via the IPerfManager and IPerfEvent we are enabling these details to be disabled. 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.

OptionaldisableFetchKeepAlive

disableFetchKeepAlive?: boolean

[Optional] A flag to disable the usage of the fetch with keep-alive support.

OptionaldisableOptimizeObj

disableOptimizeObj?: boolean

[Optional] Switch to disable the v8 optimizeObject() calls used to provide better serialization performance. Defaults to false.

OptionaldisableTelemetry

disableTelemetry?: boolean

The master off switch. Do not send any data if set to TRUE

OptionaldisableXhrSync

disableXhrSync?: boolean

[Optional] When using Xhr 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)) and you have clients that end up blocking the UI during page unloading. This will cause ALL XHR requests to be sent asynchronously which during page unload may result in the lose of telemetry.

OptionalenableCompoundKey

enableCompoundKey?: boolean

[Optional] Enables support for objects with compound keys which indirectly represent an object where the "key" of the object contains a "." as part of it's name.

Example

event: { "somedata.embeddedvalue": 123 }

OptionaleventsLimitInMem

eventsLimitInMem?: number

[Optional] The number of events that can be kept in memory before the SDK starts to drop events. By default, this is 10,000.

OptionalexcludeCsMetaData

excludeCsMetaData?: boolean

:warning: DO NOT USE THIS FLAG UNLESS YOU KNOW THAT PII DATA WILL NEVER BE INCLUDED IN THE EVENT!

[Optional] Flag to indicate whether the SDK should include the common schema metadata in the payload. Defaults to true. This flag is only applicable to the POST channel and will cause the SDK to exclude the common schema metadata from the payload, while this will reduce the size of the payload, also means that the data marked as PII will not be processed as PII by the backend and will not be included in the PII data purge process.

Since

4.1.0

OptionalfetchCredentials

fetchCredentials?: RequestCredentials

[Optional] Specify whether cross-site Access-Control fetch requests should include credentials such as cookies, authentication headers, or TLS client certificates.

Possible values:

  • "omit": never send credentials in the request or include credentials in the response.
  • "include": always include credentials, even cross-origin.
  • "same-origin": only send and include credentials for same-origin requests.

If not set, the default value will be "include".

For more information, refer to:

Since

3.3.1

OptionalhttpXHROverride

httpXHROverride?: IXHROverride

[Optional] The HTTP override that should be used to send requests, as an IXHROverride object. By default during the unload of a page or if the event specifies that it wants to use sendBeacon() or sync fetch (with keep-alive), this override will NOT be called. You can now change this behavior by enabling the 'alwaysUseXhrOverride' configuration value. The payload data (first argument) now also includes any configured 'timeout' (defaults to undefined) and whether you should avoid creating any synchronous XHR requests 'disableXhrSync' (defaults to false/undefined)

OptionalignoreMc1Ms0CookieProcessing

ignoreMc1Ms0CookieProcessing?: boolean

MC1 and MS0 cookies will not be returned from Collector endpoint.

OptionalimmediateEventLimit

immediateEventLimit?: number

[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.

OptionalmaxEventRetryAttempts

maxEventRetryAttempts?: number

[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. Defaults to 6 times.

OptionalmaxUnloadEventRetryAttempts

maxUnloadEventRetryAttempts?: number

[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. Defaults to 2 times. 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.

OptionaloverrideEndpointUrl

overrideEndpointUrl?: string

Override for Endpoint where telemetry data is sent

OptionaloverrideInstrumentationKey

overrideInstrumentationKey?: string

Override for Instrumentation key

OptionalpayloadListener

payloadListener?: PayloadListenerFunction

[Optional] POST channel listener function, used for enabling logging or reporting (RemoteDDVChannel) of the payload that is being sent.

OptionalpayloadPreprocessor

payloadPreprocessor?: PayloadPreprocessorFunction

[Optional] POST channel preprocessing function. Can be used to gzip the payload before transmission and to set the appropriate Content-Encoding header. The preprocessor is explicitly not called during teardown when using the sendBeacon() API.

OptionalsetTimeoutOverride

setTimeoutOverride?: {
    __promisify__<T>(delay?: number, value?: T, options?: TimerOptions): Promise<T>;
    (handler: TimerHandler, timeout?: number, ...arguments: any[]): number;
    <TArgs>(callback: ((...args: TArgs) => void), delay?: number, ...args: TArgs): NodeJS.Timeout;
    (callback: ((_: void) => void), delay?: number): NodeJS.Timeout;
}

Override for setTimeout

Type declaration

    • (handler, timeout?, ...arguments): number

    • Parameters

      • handler: TimerHandler
      • Optionaltimeout: number
      • Rest...arguments: any[]

      Returns number

    • <TArgs>(callback, delay?, ...args): NodeJS.Timeout

    • Schedules execution of a one-time callback after delay milliseconds.

      The callback will likely not be invoked in precisely delay milliseconds. Node.js makes no guarantees about the exact timing of when callbacks will fire, nor of their ordering. The callback will be called as close as possible to the time specified.

      When delay is larger than 2147483647 or less than 1 or NaN, the delay will be set to 1. Non-integer delays are truncated to an integer.

      If callback is not a function, a TypeError will be thrown.

      This method has a custom variant for promises that is available using timersPromises.setTimeout().

      Type Parameters

      • TArgs extends any[]

      Parameters

      • callback: ((...args: TArgs) => void)

        The function to call when the timer elapses.

          • (...args): void

          • Parameters

            Returns void

      • Optionaldelay: number

        The number of milliseconds to wait before calling the callback. Default: 1.

      • Rest...args: TArgs

        Optional arguments to pass when the callback is called.

      Returns NodeJS.Timeout

      for use with clearTimeout()

      Since

      v0.0.1

    • (callback, delay?): NodeJS.Timeout

    • Parameters

      • callback: ((_: void) => void)
          • (_): void

          • Parameters

            • _: void

            Returns void

      • Optionaldelay: number

      Returns NodeJS.Timeout

  • __promisify__:function
    • __promisify__<T>(delay?, value?, options?): Promise<T>
    • import {
        setTimeout,
      } from 'node:timers/promises';

      const res = await setTimeout(100, 'result');

      console.log(res);  // Prints 'result'

      Type Parameters

      • T = void

      Parameters

      • Optionaldelay: number

        The number of milliseconds to wait before fulfilling the promise. Default: 1.

      • Optionalvalue: T

        A value with which the promise is fulfilled.

      • Optionaloptions: TimerOptions

      Returns Promise<T>

      Since

      v15.0.0

OptionalstringifyObjects

stringifyObjects?: boolean

[Optional] During serialization, when an object is identified, should the object be serialized by JSON.stringify(theObject); (when true) otherwise by theObject.toString(). Defaults to false

Optionaltransports

transports?: number | number[]

[Optional] Either an array or single value identifying the requested TransportType 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.

OptionalunloadTransports

unloadTransports?: number | number[]

[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.

OptionaluseSendBeacon

useSendBeacon?: boolean

[Optional] A flag to enable or disable the usage of the sendBeacon() API (if available). If running on ReactNative this defaults to false for all other cases it defaults to true.

OptionalvalueSanitizer

valueSanitizer?: IValueSanitizer

[Optional] The value sanitizer to use while constructing the envelope.

OptionalxhrTimeout

xhrTimeout?: number

[Optional] Specify a timeout (in ms) to apply to requests when sending requests using XHR, XDR or fetch requests. Defaults to undefined and therefore the runtime defaults (normally zero for browser environments)

Settings

Member Visibility

On This Page

Properties
MMNEPVFCICPMFPCPTTAAATR