Interface ISnippetConfig

Configuration options for the Application Insights SDK Loader (snippet) that is embedded directly in an HTML page. These options control how the SDK script is loaded from the CDN, error reporting behavior, security policies, and the SDK initialization configuration.

This interface represents the configuration object passed to the self-executing snippet function. For a simplified interface used with the getSdkLoaderScript() helper, see SdkLoaderConfig.

Internet Explorer Fallback: When the SDK Loader detects Internet Explorer (via the msie or trident/ user agent strings), it automatically rewrites the src URL to load the v2.x SDK instead of v3.x (e.g. ai.3.gbl.min.js becomes ai.2.gbl.min.js). This means v3.x-only APIs — including the new OpenTelemetry-based APIs — will not be available for those users.

Example

<script type="text/javascript">
!function(T,l,y){/* snippet code */}(window, document, {
  src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js",
  crossOrigin: "anonymous",
  onInit: function (sdk) {
    sdk.addTelemetryInitializer(function (envelope) {
      envelope.data.someField = 'This item passed through my telemetry initializer';
    });
  },
  cfg: {
    connectionString: "YOUR_CONNECTION_STRING"
  }
});
</script>
interface ISnippetConfig {
    cfg: IConfiguration;
    cr?: boolean;
    crossOrigin?: string;
    dle?: boolean;
    ld?: number;
    name?: string;
    nt?: string;
    onInit?: any;
    pl?: boolean;
    pn?: string;
    src: string;
    sri?: boolean;
    ttp?: TrustedTypePolicy;
    useXhr?: boolean;
}

Properties

cfg cr? crossOrigin? dle? ld? name? nt? onInit? pl? pn? src sri? ttp? useXhr?

Properties

cfg

cfg: IConfiguration

[required] The IConfiguration configuration object passed to the Application Insights SDK during initialization.

Example

cfg: {
  connectionString: "YOUR_CONNECTION_STRING",
  enableAutoRouteTracking: true
}

Optionalcr

cr?: boolean

(Optional) Controls CDN fallback retry behavior. By default (true), if the SDK fails to load from the configured src URL, the snippet automatically attempts to load from multiple supported CDN domains in case one or more of them is temporarily unavailable. Set to false to disable this fallback and only attempt the single configured src URL.

OptionalcrossOrigin

crossOrigin?: string

(Optional) The crossOrigin attribute value for the script tag added to download the SDK. Recommended values: not defined (the default), "", or "anonymous". See HTML attribute: crossorigin.

Optionaldle

dle?: boolean

(Optional) When set to true, prevents the SDK from reporting load failure telemetry.

Optionalld

ld?: number

(Optional) Defines the load delay (in ms) before attempting to load the SDK. Default is 0ms. A negative value immediately adds the script tag to the <head> region, blocking the page load event until the script is loaded or fails.

Optionalname

name?: string

(Optional) The global name for the initialized SDK instance. Defaults to "appInsights". So window.appInsights will be a reference to the initialized instance. If you provide a name value or a previous instance appears to be assigned (via the global name appInsightsSDK), this name will also be defined in the global namespace as window.appInsightsSDK=<name value>.

Optionalnt

nt?: string

(Optional) The nonce attribute value that will be applied to the script tag when it is added to the page, for use with Content Security Policy (CSP).

OptionalonInit

onInit?: any

(Optional) Callback function called after the main SDK script has been successfully loaded and initialized from the CDN. It receives a reference to the SDK instance and is called before the first initial page view. If the SDK has already been loaded and initialized, this callback will still be called.

Note: As this callback is called during the processing of the sdk.queue array, you CANNOT add additional items to the queue — they will be ignored and dropped.

Example

onInit: function (sdk) {
  sdk.addTelemetryInitializer(function (envelope) {
    envelope.data.someField = 'custom value';
  });
}

Optionalpl

pl?: boolean

(Optional) When set to true, enables Trusted Type policy validation on the snippet.

Optionalpn

pn?: string

(Optional) The name of the Trusted Type policy to use. Defaults to "aiPolicy".

src

src: string

[required] The full URL for where to load the SDK from. This value is used for the src attribute of a dynamically added <script> tag. You can use the public CDN location or your own privately hosted one.

Note: When Internet Explorer is detected, the SDK Loader automatically rewrites this URL to load the v2.x SDK (e.g. ai.3.gbl.min.js becomes ai.2.gbl.min.js).

Example

src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js"

Optionalsri

sri?: boolean

(Optional) When set to true, enables Sub-Resource Integrity (SRI) checking. The snippet will fetch an integrity file and validate the SDK script hash before execution. When this option is used, the integrity file is loaded first, affecting the load order and script execution. The ld option will be ignored. Additionally, if the page navigates away before the integrity file is loaded, some events may be lost.

Optionalttp

ttp?: TrustedTypePolicy

(Optional) A pre-created TrustedTypePolicy instance to apply to the snippet src URL.

OptionaluseXhr

useXhr?: boolean

(Optional) Use XHR instead of fetch to report SDK load failures. Only needed in environments where fetch would fail to send the failure events.

Settings

Member Visibility

On This Page

Properties