Habilitar uma extensão de estrutura para o SDK do JavaScript do Application Insights

• Verifique se a versão do plug-in React que deseja instalar é compatível com sua versão do Application Insights. Para obter mais informações, consulte Matriz de compatibilidade para o plug-in React.

• Você deve usar uma versão >= 2.0.0 de @microsoft/applicationinsights-web. Esse plug-in funciona apenas em aplicativos react-native. Ele não funciona com aplicativos usando a estrutura Expo ou Create React Native App, que se baseia na estrutura Expo.

• O plug-in do Angular não é compatível com ECMAScript 3 (ES3).
• Quando adicionamos suporte para uma nova versão do Angular, nosso pacote NPM se torna incompatível com versões do Angular de nível inferior. Continue a usar pacotes NPM mais antigos até estar pronto para atualizar sua versão do Angular.

O plug-in React para o SDK JavaScript do Application Insights permite o seguinte:

• Acompanhar o histórico do roteador
• Acompanhar exceções
• Acompanhar o uso de componentes
• Usar o Application Insights com React Context

O plug-in do React Native para o SDK do JavaScript do Application Insights permite:

• Acompanhar exceções

• Coletar informações do dispositivo

  Por padrão, esse plug-in coleta automaticamente:

  • ID exclusiva do dispositivo (também conhecida como ID de instalação).
  • Nome do modelo do dispositivo (como iPhone XS, Samsung Galaxy Fold, Huawei P30 Pro etc.)
  • Tipo de dispositivo (por exemplo, celular, tablet etc.)

• Desabilitar a coleta automática de informações do dispositivo

• Use sua própria classe de coleta de informações do dispositivo

• Substituir as informações do dispositivo

O plug-in do Angular para o SDK do JavaScript do Application Insights permite:

• Acompanhar o histórico do roteador
• Acompanhar exceções
• Encadear mais manipuladores de exceção personalizados

npm install @microsoft/applicationinsights-react-js

• Plug-in React Native

  Por padrão, o plug-in React Native depende do react-native-device-info pacote. Você deve instalar e vincular a este pacote. Mantenha o pacote react-native-device-info atualizado para coletar os nomes de dispositivo mais recentes usando seu aplicativo.

  Desde a v3, o suporte para acessar o DeviceInfo foi abstraído em uma interface IDeviceInfoModule para permitir que você use/defina seu próprio módulo de informações do dispositivo. Essa interface usa os mesmos nomes de função e resultado react-native-device-info.

  
  npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
  npm install --save react-native-device-info
  react-native link react-native-device-info
  
  

• Plug-in de dispositivo manual do React Native

  Se você estiver usando React Native Expo, adicione o plug-in de dispositivo manual React Native em vez do plug-in React Native. O plug-in React Native usa o pacote react-native-device-info package, que não tem suporte do React Native Expo.

  
  npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
  
  

npm install @microsoft/applicationinsights-angularplugin-js

Inicializar uma conexão com o Application Insights:

import React from 'react';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ReactPlugin } from '@microsoft/applicationinsights-react-js';
import { createBrowserHistory } from "history";
const browserHistory = createBrowserHistory({ basename: '' });
var reactPlugin = new ReactPlugin();
// *** Add the Click Analytics plug-in. ***
/* var clickPluginInstance = new ClickAnalyticsPlugin();
   var clickPluginConfig = {
     autoCapture: true
}; */
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        // *** If you're adding the Click Analytics plug-in, delete the next line. ***
        extensions: [reactPlugin],
     // *** Add the Click Analytics plug-in. ***
     // extensions: [reactPlugin, clickPluginInstance],
        extensionConfig: {
          [reactPlugin.identifier]: { history: browserHistory }
       // *** Add the Click Analytics plug-in. ***
       // [clickPluginInstance.identifier]: clickPluginConfig
        }
    }
});
appInsights.loadAppInsights();

• Plug-in React Native

  Para usar esse plug-in, você precisa construí-lo e adicioná-lo como um extension à instância do Application Insights existente.

  import { ApplicationInsights } from '@microsoft/applicationinsights-web';
  import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
  // *** Add the Click Analytics plug-in. ***
  // import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
  var RNPlugin = new ReactNativePlugin();
  // *** Add the Click Analytics plug-in. ***
  /* var clickPluginInstance = new ClickAnalyticsPlugin();
  var clickPluginConfig = {
  autoCapture: true
  }; */
  var appInsights = new ApplicationInsights({
      config: {
          connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
          // *** If you're adding the Click Analytics plug-in, delete the next line. ***
          extensions: [RNPlugin]
       // *** Add the Click Analytics plug-in. ***
       /* extensions: [RNPlugin, clickPluginInstance],
               extensionConfig: {
                   [clickPluginInstance.identifier]: clickPluginConfig
            } */
      }
  });
  appInsights.loadAppInsights();
  
  

• Plug-in de dispositivo manual do React Native

  Para usar esse plug-in, você deve desabilitar a coleta automática de informações do dispositivo ou usar sua própria classe de coleção de informações de dispositivo depois de adicionar a extensão ao código.

  1. Construa o plug-in adicione-o como um extension à instância do Application Insights existente.

     import { ApplicationInsights } from '@microsoft/applicationinsights-web';
     import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
     
     var RNMPlugin = new ReactNativePlugin();
     var appInsights = new ApplicationInsights({
         config: {
             instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
             extensions: [RNMPlugin]
         }
     });
     appInsights.loadAppInsights();
     

  2. Realize um dos seguintes procedimentos:

     • Desabilitar a coleta automática de informações do dispositivo.

       import { ApplicationInsights } from '@microsoft/applicationinsights-web';
       
       var RNMPlugin = new ReactNativeManualDevicePlugin();
       var appInsights = new ApplicationInsights({
           config: {
               instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
               disableDeviceCollection: true,
               extensions: [RNMPlugin]
           }
       });
       appInsights.loadAppInsights();
       

     • Use sua própria classe de coleta de informações do dispositivo.

       import { ApplicationInsights } from '@microsoft/applicationinsights-web';
       
       // Simple inline constant implementation
       const myDeviceInfoModule = {
           getModel: () => "deviceModel",
           getDeviceType: () => "deviceType",
           // v5 returns a string while latest returns a promise
           getUniqueId: () => "deviceId",         // This "may" also return a Promise<string>
       };
       
       var RNMPlugin = new ReactNativeManualDevicePlugin();
       RNMPlugin.setDeviceInfoModule(myDeviceInfoModule);
       
       var appInsights = new ApplicationInsights({
           config: {
               instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
               extensions: [RNMPlugin]
           }
       });
       
       appInsights.loadAppInsights();
       

Configure uma instância do Application Insights no componente de entrada do seu aplicativo:

import { Component } from '@angular/core';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
// *** Add the Click Analytics plug-in. ***
// import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
import { Router } from '@angular/router';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor(
        private router: Router
    ){
        var angularPlugin = new AngularPlugin();
     // *** Add the Click Analytics plug-in. ***
     /* var clickPluginInstance = new ClickAnalyticsPlugin();
        var clickPluginConfig = {
          autoCapture: true
        }; */
        const appInsights = new ApplicationInsights({
            config: {
                connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
                // *** If you're adding the Click Analytics plug-in, delete the next line. ***  
                extensions: [angularPlugin],
             // *** Add the Click Analytics plug-in. ***
             // extensions: [angularPlugin, clickPluginInstance],
                extensionConfig: {
                    [angularPlugin.identifier]: { router: this.router }
                 // *** Add the Click Analytics plug-in. ***
                 // [clickPluginInstance.identifier]: clickPluginConfig
                }
            } 
         });
        appInsights.loadAppInsights();
    }
}

O exemplo de código a seguir mostra como habilitar o campo enableAutoRouteTracking.

var reactPlugin = new ReactPlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        enableAutoRouteTracking: true,
        extensions: [reactPlugin]
    }
});
appInsights.loadAppInsights();

O React Native não controla as alterações do roteador, mas controla as exibições de página.

O exemplo de código a seguir mostra como habilitar o acompanhamento do histórico do roteador.

import { Component } from '@angular/core';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
import { Router } from '@angular/router';



@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor(
        private router: Router
    ){
        var angularPlugin = new AngularPlugin();
        const appInsights = new ApplicationInsights({ config: {
        connectionString: 'YOUR_CONNECTION_STRING',
        extensions: [angularPlugin],
        extensionConfig: {
            [angularPlugin.identifier]: { router: this.router }
        }
        } });
        appInsights.loadAppInsights();
    }
}

Os limites de erro do React fornecem uma maneira de tratar adequadamente uma exceção não capturada quando ela ocorre em um aplicativo React. Quando essa exceção ocorre, é provável que a exceção precise ser registrada. O plug-in React do Application Insights fornece um componente de limite de erro que registra automaticamente a exceção quando el ocorre.

import React from "react";
import { reactPlugin } from "./AppInsights";
import { AppInsightsErrorBoundary } from "@microsoft/applicationinsights-react-js";

const App = () => {
    return (
        <AppInsightsErrorBoundary onError={() => <h1>I believe something went wrong</h1>} appInsights={reactPlugin}>
            /* app here */
        </AppInsightsErrorBoundary>
    );
};

O AppInsightsErrorBoundary requer que dois adereços sejam transmitidos a ele. Eles são a instância ReactPlugin criada para o aplicativo e um componente a ser renderizado no caso da exceção. Quando ocorre uma exceção sem tratamento, trackException é chamado com as informações fornecidas ao limite do erro e o componente onError aparece.

O acompanhamento de exceções não capturadas é habilitado por padrão. Se você quiser desabilitar o acompanhamento de exceções não capturadas, defina disableExceptionCollection como true.

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

var RNPlugin = new ReactNativePlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        disableExceptionCollection: true,
        extensions: [RNPlugin]
    }
});
appInsights.loadAppInsights();

Para rastrear exceções não capturadas, configure ApplicationinsightsAngularpluginErrorService em app.module.ts:

import { ApplicationinsightsAngularpluginErrorService } from '@microsoft/applicationinsights-angularplugin-js';

@NgModule({
  ...
  providers: [
    {
      provide: ErrorHandler,
      useClass: ApplicationinsightsAngularpluginErrorService
    }
  ]
  ...
})
export class AppModule { }

Encadear mais manipuladores de exceção personalizados

Encadeie mais manipuladores de exceção personalizados quando quiser que o aplicativo manipule normalmente o que anteriormente seria uma exceção sem tratamento, mas você ainda deseja relatar essa exceção como uma falha do aplicativo.

Encadear mais manipuladores de exceção personalizados:

1. Crie manipuladores de exceção personalizados que implementem o IErrorService.

   import { IErrorService } from '@microsoft/applicationinsights-angularplugin-js';
   
   export class CustomErrorHandler implements IErrorService {
       handleError(error: any) {
           ...
       }
   }
   

2. Passe a matriz errorServices através de extensionConfig.

   extensionConfig: {
           [angularPlugin.identifier]: {
             router: this.router,
             errorServices: [new CustomErrorHandler()]
           }
         }
   

As informações do dispositivo, que incluem Navegador, sistema operacional, versão e idioma, já estão sendo coletadas pelo pacote da Web do Application Insights.

• Plug-in do React NativeAlém das informações do agente de usuário do navegador, que são coletadas pelo pacote da Web do Application Insights, o React Native também coleta informações do dispositivo. As informações do dispositivo são coletadas automaticamente quando você adiciona o plug-in.
• Plugin de Dispositivo Manual Nativo do React: dependendo de como você configurou o plug-in quando adicionou a extensão ao seu código, esse plug-in pode ser:
  • Não coleta informações do dispositivo
  • Usa sua própria classe de coleta de informações do dispositivo

As informações do dispositivo, que incluem Navegador, sistema operacional, versão e idioma, já estão sendo coletadas pelo pacote da Web do Application Insights.

Acompanhar o uso de componentes

Um recurso exclusivo do plug-in React é que você pode instrumentar componentes específicos e rastreá-los individualmente.

Para instrumentar componentes React com acompanhamento de uso, aplique a função de componente de ordem superior withAITracking. Para habilitar o Application Insights para um componente, envolva withAITracking em torno do componente:

import React from 'react';
import { withAITracking } from '@microsoft/applicationinsights-react-js';
import { reactPlugin, appInsights } from './AppInsights';

// To instrument various React components usage tracking, apply the `withAITracking` higher-order
// component function.

class MyComponent extends React.Component {
    ...
}

// withAITracking takes 4 parameters (reactPlugin, Component, ComponentName, className). 
// The first two are required and the other two are optional.

export default withAITracking(reactPlugin, MyComponent);

Ele mede o tempo do evento ComponentDidMount até o evento ComponentWillUnmount. Para tornar o resultado mais preciso, ele subtrai o tempo em que o usuário ficou ocioso usando React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

Explorar seus dados

Usa o Gerenciador de Métricas do Azure Monitor para plotar um gráfico para o nome da métrica personalizada React Component Engaged Time (seconds) e dividir essa métrica personalizada por Component Name.

Também é possível executar consultas personalizadas para dividir os dados do Application Insights e gerar relatórios e visualizações de acordo com seus requisitos. Aqui está um exemplo de uma consulta personalizada. Vá em frente e cole-o diretamente no editor de consultas para testá-lo.

customMetrics
| where name contains "React Component Engaged Time (seconds)"
| summarize avg(value), count() by tostring(customDimensions["Component Name"])

Pode levar até 10 minutos para que novas métricas personalizadas apareçam no portal do Azure.

Usar o Application Insights com React Context

Fornecemos ganchos gerais para permitir que você personalize o controle de alterações para componentes individuais. Como alternativa, você pode useTrackMetric ou useTrackEvent, que são contatos predefinidos que fornecemos para acompanhar as alterações nos componentes.

Os ganchos do React para o Application Insights são projetados para usar o Contexto do React como o aspecto que o contém. Para usar o contexto, inicialize o Application Insights e importe o objeto de contexto:

import React from "react";
import { AppInsightsContext } from "@microsoft/applicationinsights-react-js";
import { reactPlugin } from "./AppInsights";

const App = () => {
    return (
        <AppInsightsContext.Provider value={reactPlugin}>
            /* your application here */
        </AppInsightsContext.Provider>
    );
};

Esse provedor de contexto disponibiliza o Application Insights como um gancho useContext em todos os componentes filhos:

import React from "react";
import { useAppInsightsContext } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const metricData = {
        average: engagementTime,
        name: "React Component Engaged Time (seconds)",
        sampleCount: 1
      };
    const additionalProperties = { "Component Name": 'MyComponent' };
    appInsights.trackMetric(metricData, additionalProperties);
    
    return (
        <h1>My Component</h1>
    );
}
export default MyComponent;

useTrackMetric

O gancho useTrackMetric replica a funcionalidade do componente de ordem superior withAITracking sem adicionar outro componente à estrutura de componentes. O Gancho usa dois argumentos:

• A instância do Application Insights, que pode ser obtida no Gancho useAppInsightsContext.
• Um identificador para o componente a ser acompanhado, como seu nome.

import React from "react";
import { useAppInsightsContext, useTrackMetric } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const trackComponent = useTrackMetric(appInsights, "MyComponent");
    
    return (
        <h1 onHover={trackComponent} onClick={trackComponent}>My Component</h1>
    );
}
export default MyComponent;

Ele opera como o componente de ordem superior, mas responde a eventos de ciclo de vida de ganchos em vez de a um ciclo de vida de componente. Se houver necessidade de execução em interações específicas, o Gancho precisará ser explicitamente fornecido para os eventos do usuário.

useTrackEvent

Use o gancho useTrackEvent para rastrear qualquer evento personalizado que um aplicativo possa precisar rastrear, como um clique de botão ou outra chamada de API. Ele usa quatro argumentos:

• Instância do Application Insights, que pode ser obtida no gancho useAppInsightsContext.
• O nome do evento.
• Objeto de dados de evento que encapsula as alterações que precisam ser rastreadas.
• O sinalizador skipFirstRun (opcional) para ignorar a chamada trackEvent na inicialização. O valor padrão é definido como true para imitar mais precisamente a forma como a versão que não é de gancho funciona. Com os ganchos useEffect, o efeito é disparado em cada atualização de valor, incluindo a configuração inicial do valor. Como resultado, o rastreamento começa muito cedo, o que faz com que eventos potencialmente indesejados sejam rastreados.

import React, { useState, useEffect } from "react";
import { useAppInsightsContext, useTrackEvent } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const [cart, setCart] = useState([]);
    const trackCheckout = useTrackEvent(appInsights, "Checkout", cart);
    const trackCartUpdate = useTrackEvent(appInsights, "Cart Updated", cart);
    useEffect(() => {
        trackCartUpdate({ cartCount: cart.length });
    }, [cart]);
    
    const performCheckout = () => {
        trackCheckout();
        // submit data
    };
    
    return (
        <div>
            <ul>
                <li>Product 1 <button onClick={() => setCart([...cart, "Product 1"])}>Add to Cart</button></li>
                <li>Product 2 <button onClick={() => setCart([...cart, "Product 2"])}>Add to Cart</button></li>
                <li>Product 3 <button onClick={() => setCart([...cart, "Product 3"])}>Add to Cart</button></li>
                <li>Product 4 <button onClick={() => setCart([...cart, "Product 4"])}>Add to Cart</button></li>
            </ul>
            <button onClick={performCheckout}>Checkout</button>
        </div>
    );
}

export default MyComponent;

Quando o gancho é usado, uma carga de dados pode ser fornecida a ele para adicionar mais dados ao evento quando ele é armazenado no Application Insights.

Desabilitar a coleta automática de informações do dispositivo

Se não quiser coletar as informações do dispositivo, você poderá definir disableDeviceCollection como true.

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

var RNPlugin = new ReactNativePlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        disableDeviceCollection: true,
        extensions: [RNPlugin]
    }
});
appInsights.loadAppInsights();

Use sua própria classe de coleta de informações do dispositivo

Se você quiser substituir as informações do seu próprio dispositivo, poderá usar myDeviceInfoModule para coletar as informações do seu próprio dispositivo.

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

// Simple inline constant implementation
const myDeviceInfoModule = {
    getModel: () => "deviceModel",
    getDeviceType: () => "deviceType",
    // v5 returns a string while latest returns a promise
    getUniqueId: () => "deviceId",         // This "may" also return a Promise<string>
};

var RNPlugin = new ReactNativePlugin();
RNPlugin.setDeviceInfoModule(myDeviceInfoModule);

var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        extensions: [RNPlugin]
    }
});

appInsights.loadAppInsights();

Substituir as informações do dispositivo

Use a interface IDeviceInfoModule para abstrair como o plug-in pode acessar as Informações do Dispositivo. Essa interface é uma versão despojada da interface react-native-device-info e é fornecida principalmente para teste.

export 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`. Tt 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;
}

Se os eventos estiverem sendo "bloqueados" porque o Promise retornado via getUniqueId nunca é resolvido/rejeitado, você pode chamar setDeviceId() no plug-in para "desbloquear" esse estado de espera. Também há um tempo limite automático configurado por meio de uniqueIdPromiseTimeout (o padrão é 5 segundos), que chamará setDeviceId() internamente com qualquer valor configurado anteriormente.

N/D

Confira a Demonstração do React do Application Insights.

Atualmente indisponível.

Confira a Demonstração do Angular do Application Insights.