Skip to content

Commit 55ec22f

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #245696 from v-jbasden/v-jbasden-javascript-sdk-updates-9
framework extensions: Move track router history to own section, add React Native Manual Device Plugin, clarify exception tracking and device info collection
2 parents e76997d + f2cde83 commit 55ec22f

File tree

1 file changed

+190
-96
lines changed

1 file changed

+190
-96
lines changed

‎articles/azure-monitor/app/javascript-framework-extensions.md‎

Lines changed: 190 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -95,17 +95,31 @@ npm install @microsoft/applicationinsights-react-js
9595

9696
#### [React Native](#tab/reactnative)
9797

98-
By default, this plugin relies on the [`react-native-device-info` package](https://www.npmjs.com/package/react-native-device-info). You must install and link to this package. Keep the `react-native-device-info` package up to date to collect the latest device names using your app.
98+
- **React Native Plugin**
9999

100-
Since v3, support for accessing the DeviceInfo has been abstracted into an interface `IDeviceInfoModule` to enable you to use / set your own device info module. This interface uses the same function names and result `react-native-device-info`.
100+
By default, the React Native Plugin relies on the [`react-native-device-info` package](https://www.npmjs.com/package/react-native-device-info). You must install and link to this package. Keep the `react-native-device-info` package up to date to collect the latest device names using your app.
101101

102-
```zsh
102+
Since v3, support for accessing the DeviceInfo has been abstracted into an interface `IDeviceInfoModule` to enable you to use / set your own device info module. This interface uses the same function names and result `react-native-device-info`.
103+
104+
```zsh
105+
106+
npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
107+
npm install --save react-native-device-info
108+
react-native link react-native-device-info
109+
110+
```
111+
112+
- **React Native Manual Device Plugin**
113+
114+
If you're using React Native Expo, add the React Native Manual Device Plugin instead of the React Native Plugin. The React Native Plugin uses the `react-native-device-info package` package, which React Native Expo doesn't support.
115+
116+
```bash
117+
118+
npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
119+
120+
```
103121

104-
npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
105-
npm install --save react-native-device-info
106-
react-native link react-native-device-info
107122

108-
```
109123

110124
#### [Angular](#tab/angular)
111125

@@ -160,40 +174,107 @@ appInsights.loadAppInsights();
160174
161175
#### [React Native](#tab/reactnative)
162176

163-
To use this plugin, you need to construct the plugin and add it as an `extension` to your existing Application Insights instance.
177+
- **React Native Plug-in**
164178

165-
> [!TIP]
166-
> If you want to add the [Click Analytics plug-in](./javascript-feature-extensions.md), uncomment the lines for Click Analytics and delete `extensions: [RNPlugin]`.
179+
To use this plugin, you need to construct the plugin and add it as an `extension` to your existing Application Insights instance.
167180

168-
```typescript
169-
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
170-
import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
171-
// Add the Click Analytics plug-in.
172-
// import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
173-
var RNPlugin = new ReactNativePlugin();
174-
// Add the Click Analytics plug-in.
175-
/* var clickPluginInstance = new ClickAnalyticsPlugin();
176-
var clickPluginConfig = {
181+
> [!TIP]
182+
> If you want to add the [Click Analytics plug-in](./javascript-feature-extensions.md), uncomment the lines for Click Analytics and delete `extensions: [RNPlugin]`.
183+
184+
```typescript
185+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
186+
import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
187+
// Add the Click Analytics plug-in.
188+
// import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
189+
var RNPlugin = new ReactNativePlugin();
190+
// Add the Click Analytics plug-in.
191+
/* var clickPluginInstance = new ClickAnalyticsPlugin();
192+
var clickPluginConfig = {
177193
autoCapture: true
178-
}; */
179-
var appInsights = new ApplicationInsights({
180-
config: {
181-
connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
182-
// If you're adding the Click Analytics plug-in, delete the next line.
183-
extensions: [RNPlugin]
184-
// Add the Click Analytics plug-in.
185-
/* extensions: [RNPlugin, clickPluginInstance],
186-
extensionConfig: {
187-
[clickPluginInstance.identifier]: clickPluginConfig
188-
} */
189-
}
190-
});
191-
appInsights.loadAppInsights();
194+
}; */
195+
var appInsights = new ApplicationInsights({
196+
config: {
197+
connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
198+
// If you're adding the Click Analytics plug-in, delete the next line.
199+
extensions: [RNPlugin]
200+
// Add the Click Analytics plug-in.
201+
/* extensions: [RNPlugin, clickPluginInstance],
202+
extensionConfig: {
203+
[clickPluginInstance.identifier]: clickPluginConfig
204+
} */
205+
}
206+
});
207+
appInsights.loadAppInsights();
192208

193-
```
209+
```
194210

195-
> [!TIP]
196-
> If you're adding the Click Analytics plug-in, see [Use the Click Analytics plug-in](./javascript-feature-extensions.md#use-the-plug-in) to continue with the setup process.
211+
> [!TIP]
212+
> If you're adding the Click Analytics plug-in, see [Use the Click Analytics plug-in](./javascript-feature-extensions.md#use-the-plug-in) to continue with the setup process.
213+
214+
215+
- **React Native Manual Device Plugin**
216+
217+
To use this plugin, you must either disable automatic device info collection or use your own device info collection class after you add the extension to your code.
218+
219+
1. Construct the plugin and add it as an `extension` to your existing Application Insights instance.
220+
221+
```typescript
222+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
223+
import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
224+
225+
var RNMPlugin = new ReactNativePlugin();
226+
var appInsights = new ApplicationInsights({
227+
config: {
228+
instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
229+
extensions: [RNMPlugin]
230+
}
231+
});
232+
appInsights.loadAppInsights();
233+
```
234+
235+
1. Do one of the following:
236+
237+
- Disable automatic device info collection.
238+
239+
```typescript
240+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
241+
242+
var RNMPlugin = new ReactNativeManualDevicePlugin();
243+
var appInsights = new ApplicationInsights({
244+
config: {
245+
instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
246+
disableDeviceCollection: true,
247+
extensions: [RNMPlugin]
248+
}
249+
});
250+
appInsights.loadAppInsights();
251+
```
252+
253+
- Use your own device info collection class.
254+
255+
```typescript
256+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
257+
258+
// Simple inline constant implementation
259+
const myDeviceInfoModule = {
260+
getModel: () => "deviceModel",
261+
getDeviceType: () => "deviceType",
262+
// v5 returns a string while latest returns a promise
263+
getUniqueId: () => "deviceId", // This "may" also return a Promise<string>
264+
};
265+
266+
var RNMPlugin = new ReactNativeManualDevicePlugin();
267+
RNMPlugin.setDeviceInfoModule(myDeviceInfoModule);
268+
269+
var appInsights = new ApplicationInsights({
270+
config: {
271+
instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
272+
extensions: [RNMPlugin]
273+
}
274+
});
275+
276+
appInsights.loadAppInsights();
277+
```
197278

198279
#### [Angular](#tab/angular)
199280

@@ -256,11 +337,77 @@ export class AppComponent {
256337

257338
This section covers configuration settings for the framework extensions for Application Insights JavaScript SDK.
258339

340+
### Track router history
341+
342+
#### [React](#tab/react)
343+
344+
| Name | Type | Required? | Default | Description |
345+
|---------|--------|-----------|---------|------------------|
346+
| history | object | Optional | null | Track router history. For more information, see the [React router package documentation](https://reactrouter.com/en/main).<br><br>To track router history, most users can use the `enableAutoRouteTracking` field in the [JavaScript SDK configuration](./javascript-sdk-configuration.md#sdk-configuration). This field collects the same data for page views as the `history` object.<br><br>Use the `history` object when you're using a router implementation that doesn't update the browser URL, which is what the configuration listens to. You shouldn't enable both the `enableAutoRouteTracking` field and `history` object, because you'll get multiple page view events. |
347+
348+
The following code example shows how to enable the `enableAutoRouteTracking` field.
349+
350+
```javascript
351+
var reactPlugin = new ReactPlugin();
352+
var appInsights = new ApplicationInsights({
353+
config: {
354+
connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
355+
enableAutoRouteTracking: true,
356+
extensions: [reactPlugin]
357+
}
358+
});
359+
appInsights.loadAppInsights();
360+
```
361+
362+
#### [React Native](#tab/reactnative)
363+
364+
React Native doesn't track router changes but does track [page views](./api-custom-events-metrics.md#page-views).
365+
366+
#### [Angular](#tab/angular)
367+
368+
| Name | Type | Required? | Default | Description |
369+
|---------|--------|-----------|---------|------------------|
370+
| router | object | Optional | null | Angular router for enabling Application Insights PageView tracking. |
371+
372+
The following code example shows how to enable tracking of router history.
373+
374+
```javascript
375+
import { Component } from '@angular/core';
376+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
377+
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
378+
import { Router } from '@angular/router';
379+
380+
381+
382+
@Component({
383+
selector: 'app-root',
384+
templateUrl: './app.component.html',
385+
styleUrls: ['./app.component.css']
386+
})
387+
export class AppComponent {
388+
constructor(
389+
private router: Router
390+
){
391+
var angularPlugin = new AngularPlugin();
392+
const appInsights = new ApplicationInsights({ config: {
393+
connectionString: 'YOUR_CONNECTION_STRING',
394+
extensions: [angularPlugin],
395+
extensionConfig: {
396+
[angularPlugin.identifier]: { router: this.router }
397+
}
398+
} });
399+
appInsights.loadAppInsights();
400+
}
401+
}
402+
```
403+
404+
---
405+
259406
### Track exceptions
260407

261408
#### [React](#tab/react)
262409

263-
[React error boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) provide a way to gracefully handle an exception when it occurs within a React application. When such an exception occurs, it's likely that the exception needs to be logged. The React plug-in for Application Insights provides an error boundary component that automatically logs the exception when it occurs.
410+
[React error boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) provide a way to gracefully handle an uncaught exception when it occurs within a React application. When such an exception occurs, it's likely that the exception needs to be logged. The React plug-in for Application Insights provides an error boundary component that automatically logs the exception when it occurs.
264411

265412
```javascript
266413
import React from "react";
@@ -280,7 +427,7 @@ The `AppInsightsErrorBoundary` requires two props to be passed to it. They're th
280427

281428
#### [React Native](#tab/reactnative)
282429

283-
Exception tracking is enabled by default. If you want to disable it, set `disableExceptionCollection` to `true`.
430+
The tracking of uncaught exceptions is enabled by default. If you want to disable the tracking of uncaught exceptions, set `disableExceptionCollection` to `true`.
284431

285432
```javascript
286433
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
@@ -361,7 +508,10 @@ N/A
361508

362509
#### [React Native](#tab/reactnative)
363510

364-
In addition to user agent info from the browser, which is collected by Application Insights web package, React Native also collects device information. Device information is automatically collected when you add the plug-in.
511+
- **React Native Plugin**: In addition to user agent info from the browser, which is collected by Application Insights web package, React Native also collects device information. Device information is automatically collected when you add the plug-in.
512+
- **React Native Manual Device Plugin**: Depending on how you configured the plugin when you added the extension to your code, this plugin either:
513+
- Doesn't collect device information
514+
- Uses your own device info collection class
365515

366516
#### [Angular](#tab/angular)
367517

@@ -376,26 +526,6 @@ N/A
376526

377527
#### [React](#tab/react)
378528

379-
#### Track router history
380-
381-
| Name | Type | Required? | Default | Description |
382-
|---------|--------|-----------|---------|------------------|
383-
| history | object | Optional | null | Track router history. For more information, see the [React router package documentation](https://reactrouter.com/en/main).<br><br>To track router history, most users can use the `enableAutoRouteTracking` field in the [JavaScript SDK configuration](./javascript-sdk-configuration.md#sdk-configuration). This field collects the same data for page views as the `history` object.<br><br>Use the `history` object when you're using a router implementation that doesn't update the browser URL, which is what the configuration listens to. You shouldn't enable both the `enableAutoRouteTracking` field and `history` object, because you'll get multiple page view events. |
384-
385-
The following code example shows how to enable the `enableAutoRouteTracking` field.
386-
387-
```javascript
388-
var reactPlugin = new ReactPlugin();
389-
var appInsights = new ApplicationInsights({
390-
config: {
391-
connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
392-
enableAutoRouteTracking: true,
393-
extensions: [reactPlugin]
394-
}
395-
});
396-
appInsights.loadAppInsights();
397-
```
398-
399529
#### Track components usage
400530

401531
A feature that's unique to the React plug-in is that you're able to instrument specific components and track them individually.
@@ -632,43 +762,7 @@ If events are getting "blocked" because the `Promise` returned via `getUniqueId`
632762
633763
#### [Angular](#tab/angular)
634764
635-
#### Track router history
636-
637-
| Name | Type | Required? | Default | Description |
638-
|---------|--------|-----------|---------|------------------|
639-
| router | object | Optional | null | Angular router for enabling Application Insights PageView tracking. |
640-
641-
The following code example shows how to enable tracking of router history.
642-
643-
```javascript
644-
import { Component } from '@angular/core';
645-
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
646-
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
647-
import { Router } from '@angular/router';
648-
649-
650-
651-
@Component({
652-
selector: 'app-root',
653-
templateUrl: './app.component.html',
654-
styleUrls: ['./app.component.css']
655-
})
656-
export class AppComponent {
657-
constructor(
658-
private router: Router
659-
){
660-
var angularPlugin = new AngularPlugin();
661-
const appInsights = new ApplicationInsights({ config: {
662-
connectionString: 'YOUR_CONNECTION_STRING',
663-
extensions: [angularPlugin],
664-
extensionConfig: {
665-
[angularPlugin.identifier]: { router: this.router }
666-
}
667-
} });
668-
appInsights.loadAppInsights();
669-
}
670-
}
671-
```
765+
N/A
672766
673767
---
674768

0 commit comments

Comments
 (0)