@microsoft/applicationinsights-react-native 2.5.6 → 3.0.0

package/dist/applicationinsights-react-native.api.json

@@ -1,7 +1,7 @@
 {
   "metadata": {
     "toolPackage": "@microsoft/api-extractor",
-    "toolVersion": "7.28.6",
+    "toolVersion": "7.28.7",
     "schemaVersion": 1009,
     "oldestForwardsCompatibleVersion": 1001,
     "tsdocConfig": {
@@ -172,6 +172,141 @@
       "name": "",
       "preserveMemberOrder": false,
       "members": [
+        {
+          "kind": "Function",
+          "canonicalReference": "@microsoft/applicationinsights-react-native!getReactNativeDeviceInfo:function(1)",
+          "docComment": "/**\n * Returns the \"react-native-device-info\" as the Device Info Module\n *\n * @returns \n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function getReactNativeDeviceInfo(): "
+            },
+            {
+              "kind": "Reference",
+              "text": "IDeviceInfoModule",
+              "canonicalReference": "@microsoft/applicationinsights-react-native!IDeviceInfoModule:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "returnTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [],
+          "name": "getReactNativeDeviceInfo"
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/applicationinsights-react-native!IDeviceInfoModule:interface",
+          "docComment": "/**\n * Interface to abstract how the plugin can access the Device Info, this is a stripped down version of the \"react-native-device-info\" interface and is mostly supplied for testing.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface IDeviceInfoModule "
+            }
+          ],
+          "releaseTag": "Public",
+          "name": "IDeviceInfoModule",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/applicationinsights-react-native!IDeviceInfoModule#getDeviceType:member",
+              "docComment": "/**\n * Returns the device type\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getDeviceType: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "() => string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "getDeviceType",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/applicationinsights-react-native!IDeviceInfoModule#getModel:member",
+              "docComment": "/**\n * Returns the Device Model\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getModel: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "() => string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "getModel",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/applicationinsights-react-native!IDeviceInfoModule#getUniqueId:member",
+              "docComment": "/**\n * Returns the unique Id for the device, to support both the current version and previous versions react-native-device-info, this may return either a `string` or `Promise<string>`, when a promise is returned the plugin will \"wait\" for the promise to `resolve` or `reject` before processing any events. This WILL cause telemetry to be BLOCKED until either of these states, so when returning a Promise it MUST `resolve` or `reject` it can't just never resolve. There is a default timeout configured via `uniqueIdPromiseTimeout` to automatically unblock event processing when this issue occurs.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getUniqueId: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "() => "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<string> | string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "getUniqueId",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 4
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@microsoft/applicationinsights-react-native!INativeDevice:interface",
@@ -287,7 +422,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@microsoft/applicationinsights-react-native!IReactNativePluginConfig#disableDeviceCollection:member",
-              "docComment": "",
+              "docComment": "/**\n * Disable automatic device collection\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -314,7 +449,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@microsoft/applicationinsights-react-native!IReactNativePluginConfig#disableExceptionCollection:member",
-              "docComment": "",
+              "docComment": "/**\n * Disable automatic exception collection\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -337,6 +472,33 @@
                 "startIndex": 1,
                 "endIndex": 2
               }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/applicationinsights-react-native!IReactNativePluginConfig#uniqueIdPromiseTimeout:member",
+              "docComment": "/**\n * Timeout value to unblock the processing of events if the DeviceInfoModule returns a Promise.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "uniqueIdPromiseTimeout?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "uniqueIdPromiseTimeout",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             }
           ],
           "extendsTokenRanges": []
@@ -643,7 +805,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/applicationinsights-react-native!ReactNativePlugin#setDeviceId:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Manually set the deviceId, if set before initialization and automatic device info collection is enabled this value may get overwritten. If you want to keep this value disable auto collection by setting the `disableDeviceCollection` config to true.\n *\n * @param newId - The value to use as the device Id.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -687,10 +849,58 @@
               "isOptional": false,
               "name": "setDeviceId"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@microsoft/applicationinsights-react-native!ReactNativePlugin#setDeviceInfoModule:member(1)",
+              "docComment": "/**\n * Set the module that will be used during initialization when collecting device is enabled (the default), automatic collection can be disabled via the `disableDeviceCollection` config. The `react-native-device-info` module will be used by default if no `deviceInfoModule` is set and collection is enabled.\n *\n * @param deviceInfoModule - \n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setDeviceInfoModule(deviceInfoModule: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "IDeviceInfoModule",
+                  "canonicalReference": "@microsoft/applicationinsights-react-native!IDeviceInfoModule:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "deviceInfoModule",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "name": "setDeviceInfoModule"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/applicationinsights-react-native!ReactNativePlugin#setDeviceModel:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Manually set the device model, if set before initialization and automatic device info collection is enabled this value may get overwritten. If you want to keep this value disable auto collection by setting the `disableDeviceCollection` config to true.\n *\n * @param newModel - The value to use as the device model.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -737,7 +947,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/applicationinsights-react-native!ReactNativePlugin#setDeviceType:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Manually set the device type (class), if set before initialization and automatic device info collection is enabled this value may get overwritten. If you want to keep this value disable auto collection by setting the `disableDeviceCollection` config to true.\n *\n * @param newType - The value to use as the device type\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

package/dist/applicationinsights-react-native.api.md

@@ -11,6 +11,16 @@ import { IProcessTelemetryContext } from '@microsoft/applicationinsights-core-js
 import { ITelemetryItem } from '@microsoft/applicationinsights-core-js';
 import { ITelemetryPlugin } from '@microsoft/applicationinsights-core-js';
 
+// @public
+export function getReactNativeDeviceInfo(): IDeviceInfoModule;
+
+// @public
+export interface IDeviceInfoModule {
+    getDeviceType: () => string;
+    getModel: () => string;
+    getUniqueId: () => Promise<string> | string;
+}
+
 // @public (undocumented)
 export interface INativeDevice {
     deviceClass?: string;
@@ -20,10 +30,9 @@ export interface INativeDevice {
 
 // @public (undocumented)
 export interface IReactNativePluginConfig {
-    // (undocumented)
     disableDeviceCollection?: boolean;
-    // (undocumented)
     disableExceptionCollection?: boolean;
+    uniqueIdPromiseTimeout?: number;
 }
 
 // @public (undocumented)
@@ -40,11 +49,9 @@ export class ReactNativePlugin extends BaseTelemetryPlugin {
     priority: number;
     // (undocumented)
     processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
-    // (undocumented)
     setDeviceId(newId: string): void;
-    // (undocumented)
+    setDeviceInfoModule(deviceInfoModule: IDeviceInfoModule): void;
     setDeviceModel(newModel: string): void;
-    // (undocumented)
     setDeviceType(newType: string): void;
 }
 

package/dist/applicationinsights-react-native.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft Application Insights react native plugin, 2.5.6
+ * Microsoft Application Insights react native plugin, 3.0.0
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -14,6 +14,38 @@ declare namespace ApplicationInsights {
     import { ITelemetryItem } from '@microsoft/applicationinsights-core-js';
     import { ITelemetryPlugin } from '@microsoft/applicationinsights-core-js';
 
+    /**
+     * Returns the "react-native-device-info" as the Device Info Module
+     * @returns
+     */
+    function getReactNativeDeviceInfo(): IDeviceInfoModule;
+
+    /**
+     * Interface to abstract how the plugin can access the Device Info, this is a stripped
+     * down version of the "react-native-device-info" interface and is mostly supplied for
+     * testing.
+     */
+    interface IDeviceInfoModule {
+        /**
+         * Returns the Device Model
+         */
+        getModel: () => string;
+        /**
+         * Returns the device type
+         */
+        getDeviceType: () => string;
+        /**
+         * Returns the unique Id for the device, to support both the current version and previous
+         * versions react-native-device-info, this may return either a `string` or `Promise<string>`,
+         * when a promise is returned the plugin will "wait" for the promise to `resolve` or `reject`
+         * before processing any events. This WILL cause telemetry to be BLOCKED until either of these
+         * states, so when returning a Promise it MUST `resolve` or `reject` it can't just never resolve.
+         * There is a default timeout configured via `uniqueIdPromiseTimeout` to automatically unblock
+         * event processing when this issue occurs.
+         */
+        getUniqueId: () => Promise<string> | string;
+    }
+
     interface INativeDevice {
         /**
          * Device type, e.g. Handset, Tablet, Tv
@@ -30,8 +62,19 @@ declare namespace ApplicationInsights {
     }
 
     interface IReactNativePluginConfig {
+        /**
+         * Disable automatic device collection
+         */
         disableDeviceCollection?: boolean;
+        /**
+         * Disable automatic exception collection
+         */
         disableExceptionCollection?: boolean;
+        /**
+         * Timeout value to unblock the processing of events if the DeviceInfoModule
+         * returns a Promise.
+         */
+        uniqueIdPromiseTimeout?: number;
     }
 
     class ReactNativePlugin extends BaseTelemetryPlugin {
@@ -44,8 +87,34 @@ declare namespace ApplicationInsights {
         initialize(config?: IReactNativePluginConfig | object, // need `| object` to coerce to interface
         core?: IAppInsightsCore, extensions?: IPlugin[]): void;
         processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
+        /**
+         * Set the module that will be used during initialization when collecting device is enabled
+         * (the default), automatic collection can be disabled via the `disableDeviceCollection`
+         * config. The `react-native-device-info` module will be used by default if no
+         * `deviceInfoModule` is set and collection is enabled.
+         * @param deviceInfoModule
+         */
+        setDeviceInfoModule(deviceInfoModule: IDeviceInfoModule): void;
+        /**
+         * Manually set the deviceId, if set before initialization and automatic device info collection
+         * is enabled this value may get overwritten. If you want to keep this value disable auto
+         * collection by setting the `disableDeviceCollection` config to true.
+         * @param newId - The value to use as the device Id.
+         */
         setDeviceId(newId: string): void;
+        /**
+         * Manually set the device model, if set before initialization and automatic device info
+         * collection is enabled this value may get overwritten. If you want to keep this value
+         * disable auto collection by setting the `disableDeviceCollection` config to true.
+         * @param newModel - The value to use as the device model.
+         */
         setDeviceModel(newModel: string): void;
+        /**
+         * Manually set the device type (class), if set before initialization and automatic device
+         * info collection is enabled this value may get overwritten. If you want to keep this value
+         * disable auto collection by setting the `disableDeviceCollection` config to true.
+         * @param newType - The value to use as the device type
+         */
         setDeviceType(newType: string): void;
     }