@microsoft/applicationinsights-web-basic 2.8.0-beta.2203-04 → 2.8.0-beta.2203-07

package/dist/applicationinsights-web-basic.api.json

@@ -708,7 +708,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#addPlugin:member(1)",
-              "docComment": "/**\n * Add a new plugin to the installation\n *\n * @param plugin - The new plugin to add\n *\n * @param replaceExisting - should any existing plugin be replaced\n *\n * @param doAsync - Should the add be performed asynchronously\n */\n",
+              "docComment": "/**\n * Add a new plugin to the installation\n *\n * @param plugin - The new plugin to add\n *\n * @param replaceExisting - should any existing plugin be replaced, default is false\n *\n * @param doAsync - Should the add be performed asynchronously\n *\n * @param addCb - [Optional] callback to call after the plugin has been added\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -742,7 +742,7 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ", replaceExisting: "
+                  "text": ", replaceExisting?: "
                 },
                 {
                   "kind": "Content",
@@ -750,7 +750,7 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ", doAsync: "
+                  "text": ", doAsync?: "
                 },
                 {
                   "kind": "Content",
@@ -979,6 +979,96 @@
               "parameters": [],
               "name": "evtNamespace"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#flush:member(1)",
+              "docComment": "/**\n * Flush and send any batched / cached data immediately\n *\n * @param async - send data asynchronously when true (defaults to true)\n *\n * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called. If the caller doesn't return true the caller should assume that it may never be called.\n *\n * @param sendReason - specify the reason that you are calling \"flush\" defaults to ManualFlush (1) if not specified\n *\n * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.\n *\n * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "flush(isAsync?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", callBack?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "(flushComplete?: boolean) => void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", sendReason?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "SendRequestReason",
+                  "canonicalReference": "@microsoft/applicationinsights-web-basic!SendRequestReason:enum"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", cbTimeout?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean | void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 9,
+                "endIndex": 10
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "isAsync",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  }
+                },
+                {
+                  "parameterName": "callBack",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  }
+                },
+                {
+                  "parameterName": "sendReason",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  }
+                },
+                {
+                  "parameterName": "cbTimeout",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 7,
+                    "endIndex": 8
+                  }
+                }
+              ],
+              "name": "flush"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#getCookieMgr:member(1)",
@@ -1543,7 +1633,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#unload:member(1)",
-              "docComment": "/**\n * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous unload call return `true` stating that all plugins reported that they also unloaded, the recommended approach is to create a new instance and initialize that instance. This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable to successfully remove any global references or they may just be completing the unload process asynchronously.\n */\n",
+              "docComment": "/**\n * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous unload call return `true` stating that all plugins reported that they also unloaded, the recommended approach is to create a new instance and initialize that instance. This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable to successfully remove any global references or they may just be completing the unload process asynchronously.\n *\n * @param isAsync - Can the unload be performed asynchronously (default)\n *\n * @param unloadComplete - An optional callback that will be called once the unload has completed\n *\n * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -1559,7 +1649,24 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "() => void"
+                  "text": "(unloadState: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ITelemetryUnloadState",
+                  "canonicalReference": "@microsoft/applicationinsights-web-basic!ITelemetryUnloadState:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ") => void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", cbTimeout?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
                 },
                 {
                   "kind": "Content",
@@ -1576,8 +1683,8 @@
               ],
               "isOptional": false,
               "returnTypeTokenRange": {
-                "startIndex": 5,
-                "endIndex": 6
+                "startIndex": 9,
+                "endIndex": 10
               },
               "releaseTag": "Public",
               "overloadIndex": 1,
@@ -1593,7 +1700,14 @@
                   "parameterName": "unloadComplete",
                   "parameterTypeTokenRange": {
                     "startIndex": 3,
-                    "endIndex": 4
+                    "endIndex": 6
+                  }
+                },
+                {
+                  "parameterName": "cbTimeout",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 7,
+                    "endIndex": 8
                   }
                 }
               ],

package/dist/applicationinsights-web-basic.api.md

@@ -45,7 +45,7 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     // Warning: (ae-forgotten-export) The symbol "INotificationListener" needs to be exported by the entry point index.d.ts
     addNotificationListener?(listener: INotificationListener): void;
     // Warning: (ae-forgotten-export) The symbol "ITelemetryPlugin" needs to be exported by the entry point index.d.ts
-    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting?: boolean, doAsync?: boolean, addCb?: (added?: boolean) => void): void;
     // Warning: (ae-forgotten-export) The symbol "TelemetryInitializerFunction" needs to be exported by the entry point index.d.ts
     // Warning: (ae-forgotten-export) The symbol "ITelemetryInitializerHandler" needs to be exported by the entry point index.d.ts
     addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
@@ -54,6 +54,8 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     // (undocumented)
     config: IConfiguration;
     evtNamespace(): string;
+    // Warning: (ae-forgotten-export) The symbol "SendRequestReason" needs to be exported by the entry point index.d.ts
+    flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason, cbTimeout?: number): boolean | void;
     // Warning: (ae-forgotten-export) The symbol "ICookieMgr" needs to be exported by the entry point index.d.ts
     getCookieMgr(): ICookieMgr;
     getNotifyMgr(): INotificationManager;
@@ -78,7 +80,8 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     stopPollingInternalLogs?(): void;
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
-    unload(isAsync?: boolean, unloadComplete?: () => void): void;
+    // Warning: (ae-forgotten-export) The symbol "ITelemetryUnloadState" needs to be exported by the entry point index.d.ts
+    unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
 }
 
 // @public
@@ -265,7 +268,6 @@ export class Sender extends BaseTelemetryPlugin implements IChannelControlsAI {
     readonly _senderConfig: ISenderConfig;
     // (undocumented)
     teardown(): void;
-    // Warning: (ae-forgotten-export) The symbol "SendRequestReason" needs to be exported by the entry point index.d.ts
     triggerSend(async?: boolean, forcedSender?: SenderFunction, sendReason?: SendRequestReason): void;
     // Warning: (ae-forgotten-export) The symbol "XDomainRequest" needs to be exported by the entry point index.d.ts
     _xdrOnLoad(xdr: XDomainRequest, payload: string[]): void;

package/dist/applicationinsights-web-basic.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 2.8.0-beta.2203-04
+ * Microsoft.ApplicationInsights, 2.8.0-beta.2203-07
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -107,10 +107,20 @@ declare namespace ApplicationInsights {
          * approach is to create a new instance and initialize that instance.
          * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
          * to successfully remove any global references or they may just be completing the unload process asynchronously.
+         * @param isAsync - Can the unload be performed asynchronously (default)
+         * @param unloadComplete - An optional callback that will be called once the unload has completed
+         * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.
          */
-        unload(isAsync?: boolean, unloadComplete?: () => void): void;
+        unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
         getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
-        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
+        /**
+         * Add a new plugin to the installation
+         * @param plugin - The new plugin to add
+         * @param replaceExisting - should any existing plugin be replaced, default is false
+         * @param doAsync - Should the add be performed asynchronously
+         * @param addCb - [Optional] callback to call after the plugin has been added
+         */
+        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting?: boolean, doAsync?: boolean, addCb?: (added?: boolean) => void): void;
         /**
          * Returns the unique event namespace that should be used
          */
@@ -120,7 +130,23 @@ declare namespace ApplicationInsights {
          * @param handler - the handler
          */
         addUnloadCb(handler: UnloadHandler): void;
+        /**
+         * Flush and send any batched / cached data immediately
+         * @param async - send data asynchronously when true (defaults to true)
+         * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
+         * If the caller doesn't return true the caller should assume that it may never be called.
+         * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
+         * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
+         */
+        flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): void;
         protected releaseQueue(): void;
+        /**
+         * Hook for Core extensions to allow them to update their own configuration before updating all of the plugins.
+         * @param updateCtx - The plugin update context
+         * @param updateState - The Update State
+         * @returns boolean - True means the extension class will call updateState otherwise the Core will
+         */
+        protected _updateHook?(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
     }
 
     /**
@@ -177,6 +203,14 @@ declare namespace ApplicationInsights {
          * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
          */
         protected _doTeardown?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void) => void | boolean;
+        /**
+         * Extension hook to allow implementations to perform some additional update operations before the BaseTelemetryPlugin finishes it's removal
+         * @param updateCtx - This is the context that should be used during updating.
+         * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+         * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async update operations.
+         * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
+         */
+        protected _doUpdate?: (updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: () => void) => void | boolean;
         constructor();
         initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
         /**
@@ -189,6 +223,13 @@ declare namespace ApplicationInsights {
          */
         teardown(unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState): void | boolean;
         abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
+        /**
+         * The the plugin should re-evaluate configuration and update any cached configuration settings.
+         * @param updateCtx - This is the context that should be used during updating.
+         * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+         * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+         */
+        update(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
         /**
          * Add an unload handler that will be called when the SDK is being unloaded
          * @param handler - the handler
@@ -388,8 +429,11 @@ declare namespace ApplicationInsights {
          * approach is to create a new instance and initialize that instance.
          * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
          * to successfully remove any global references or they may just be completing the unload process asynchronously.
+         * @param isAsync - Can the unload be performed asynchronously (default)
+         * @param unloadComplete - An optional callback that will be called once the unload has completed
+         * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.
          */
-        unload(isAsync?: boolean, unloadComplete?: () => void): void;
+        unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
         /**
          * Find and return the (first) plugin with the specified identifier if present
          * @param pluginIdentifier
@@ -398,10 +442,11 @@ declare namespace ApplicationInsights {
         /**
          * Add a new plugin to the installation
          * @param plugin - The new plugin to add
-         * @param replaceExisting - should any existing plugin be replaced
+         * @param replaceExisting - should any existing plugin be replaced, default is false
          * @param doAsync - Should the add be performed asynchronously
+         * @param addCb - [Optional] callback to call after the plugin has been added
          */
-        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
+        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting?: boolean, doAsync?: boolean, addCb?: (added?: boolean) => void): void;
         /**
          * Returns the unique event namespace that should be used when registering events
          */
@@ -411,6 +456,16 @@ declare namespace ApplicationInsights {
          * @param handler - the handler
          */
         addUnloadCb(handler: UnloadHandler): void;
+        /**
+         * Flush and send any batched / cached data immediately
+         * @param async - send data asynchronously when true (defaults to true)
+         * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
+         * If the caller doesn't return true the caller should assume that it may never be called.
+         * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
+         * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.
+         * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
+         */
+        flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason, cbTimeout?: number): boolean | void;
     }
 
     /**
@@ -1467,6 +1522,11 @@ declare namespace ApplicationInsights {
      * You must always supply the error callback
      */
     interface IInstrumentHooksCallbacks {
+        /**
+         * [Optional] Namespace details (same as the namespace used for events), useful for debugging and testing to
+         * identify the source of the instrumented hooks
+         */
+        ns?: string | string[];
         /**
          * The hook callback to call before the original function is called
          */
@@ -1978,8 +2038,8 @@ declare namespace ApplicationInsights {
     }
 
     /**
-     * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
-     * between multiple AppInsights instances
+     * The current context for the current call to teardown() implementations, used to support when plugins are being removed
+     * or the SDK is being unloaded.
      */
     interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
         /**
@@ -1998,6 +2058,27 @@ declare namespace ApplicationInsights {
         createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUnloadContext;
     }
 
+    /**
+     * The current context for the current call to the plugin update() implementations, used to support the notifications
+     * for when plugins are added, removed or the configuration was changed.
+     */
+    interface IProcessTelemetryUpdateContext extends IBaseProcessingContext {
+        /**
+         * This Plugin has finished unloading, so unload the next one
+         * @param updateState - The update State
+         * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
+         */
+        processNext: (updateState: ITelemetryUpdateState) => boolean | void;
+        /**
+         * Create a new context using the core and config from the current instance, returns a new instance of the same type
+         * @param plugins - The execution order to process the plugins, if null or not supplied
+         *                  then the current execution order will be copied.
+         * @param startAt - The plugin to start processing from, if missing from the execution
+         *                  order then the next plugin will be NOT set.
+         */
+        createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUpdateContext;
+    }
+
     interface IRequestContext {
         status?: number;
         xhr?: XMLHttpRequest;
@@ -2233,6 +2314,15 @@ declare namespace ApplicationInsights {
          * to later plugins (vs appending items to the telemetry item)
          */
         processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
+        /**
+         * The the plugin should re-evaluate configuration and update any cached configuration settings or
+         * plugins. If implemented this method will be called whenever a plugin is added or removed and if
+         * the configuration has bee updated.
+         * @param updateCtx - This is the context that should be used during updating.
+         * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+         * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+         */
+        update?: (updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) => void | boolean;
     }
 
     interface ITelemetryUnloadState {
@@ -2241,6 +2331,27 @@ declare namespace ApplicationInsights {
         flushComplete?: boolean;
     }
 
+    interface ITelemetryUpdateState {
+        /**
+         * Identifies the reason for the update notification, this is a bitwise numeric value
+         */
+        reason: TelemetryUpdateReason;
+        /**
+         * If this is a configuration update this was the previous configuration that was used
+         */
+        /**
+         * If this is a configuration update is the new configuration that is being used
+         */
+        /**
+         * This holds a collection of plugins that have been added (if the reason identifies that one or more plugins have been added)
+         */
+        added?: IPlugin[];
+        /**
+         * This holds a collection of plugins that have been removed (if the reason identifies that one or more plugins have been removed)
+         */
+        removed?: IPlugin[];
+    }
+
     interface ITraceTelemetry extends IPartC {
         /**
          * @description A message string
@@ -2437,6 +2548,27 @@ declare namespace ApplicationInsights {
         SdkUnload = 50
     }
 
+    /**
+     * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+     */
+    const enum TelemetryUpdateReason {
+        /**
+         * Unknown.
+         */
+        Unknown = 0,
+        /**
+         * The configuration has ben updated or changed
+         */
+        /**
+         * One or more plugins have been added
+         */
+        PluginAdded = 16,
+        /**
+         * One or more plugins have been removed
+         */
+        PluginRemoved = 32
+    }
+
     type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
 
     interface XDomainRequest extends XMLHttpRequestEventTarget {