Incidents App Center (React Native)

Important

La mise hors service de Visual Studio App Center est prévue pour le 31 mars 2025. Bien que vous puissiez continuer à utiliser Visual Studio App Center jusqu’à sa mise hors service complète, il existe plusieurs alternatives recommandées vers lesquelles vous pouvez envisager la migration.

En savoir plus sur les chronologies et les alternatives de support.

• Android
• iOS
• MAUI/Xamarin
• UWP
• WPF/WinForms
• React Native
• macOS
• tvOS
• Unity
• Cordova

Les incidents App Center génèrent automatiquement un journal des incidents chaque fois que votre application plante. Le journal est d’abord écrit dans le stockage de l’appareil et lorsque l’utilisateur redémarre l’application, le rapport d’incident est envoyé à App Center. La collecte des incidents fonctionne à la fois pour les applications bêta et en direct, c’est-à-dire celles soumises à Google Play. Les journaux d’incident contiennent des informations précieuses pour vous aider à résoudre l’incident.

Suivez la section Prise en main si vous n’avez pas encore configuré le Kit de développement logiciel (SDK) dans votre application.

Quel que soit l’endroit où vous utilisez App Center plante, ajoutez l’importation suivante en haut du fichier.

// Import App Center Crashes at the top of the file.
import Crashes from 'appcenter-crashes';

Générer un incident de test

App Center Crashs vous fournit une API pour générer un plantage de test afin de tester facilement le Kit de développement logiciel (SDK). Cette API ne peut être utilisée que dans les applications de test/bêta et ne peut rien faire dans les applications de production.

Crashes.generateTestCrash();

Il est également facile de générer un incident JavaScript. Ajoutez la ligne suivante à votre code, ce qui génère une erreur JavaScript et provoque un blocage.

throw new Error('This is a test javascript crash!');

Conseil

Votre application React Native doit être compilée en mode de publication pour que cet incident soit envoyé à App Center.

Notes

Pour le moment, App Center ne prend pas en charge les mappages de sources pour unminifier les traces de pile JavaScript pour les applications Android React Native.

Notes

Il est recommandé d’éviter l’instruction JavaScript throw avec une valeur de chaîne (par exemple , throw 'message'), car React Native ne conserve pas la pile JavaScript complète dans ce scénario. Au lieu de cela, throw un Code JavaScript Error (par exemple , throw Error('message')).

Obtenir plus d’informations sur un incident précédent

App Center Crashes a deux API qui vous donnent plus d’informations en cas de blocage de votre application.

L’application a-t-elle reçu un avertissement de mémoire insuffisante lors de la session précédente ?

À tout moment après le démarrage du Kit de développement logiciel (SDK), vous pouvez case activée si l’application a reçu un avertissement de mémoire lors de la session précédente :

const hadLowMemoryWarning = await Crashes.hasReceivedMemoryWarningInLastSession();

Notes

Dans certains cas, un appareil avec une mémoire insuffisante peut ne pas envoyer d’événements.

L’application s’est-elle planté lors de la session précédente ?

À tout moment après le démarrage du SDK, vous pouvez case activée si l’application s’est bloquée au lancement précédent :

const didCrash = await Crashes.hasCrashedInLastSession();

Cela s’avère pratique si vous souhaitez ajuster le comportement ou l’interface utilisateur de votre application après un incident. Certains développeurs ont choisi d’afficher une interface utilisateur supplémentaire pour s’excuser auprès de leurs utilisateurs, ou veulent entrer en contact après un incident.

Détails sur le dernier incident

Si votre application s’est bloquée précédemment, vous pouvez obtenir des détails sur le dernier incident.

const crashReport = await Crashes.lastSessionCrashReport();

Personnaliser votre utilisation des incidents App Center

Les incidents App Center fournissent des rappels permettant aux développeurs d’effectuer des actions supplémentaires avant et lors de l’envoi des journaux d’incident à App Center.

Traitement des incidents dans JavaScript

Pour que vos Crash.setListener méthodes fonctionnent comme prévu, vous devez case activée si votre application est correctement configurée.

1. Ouvrez le fichier du ios/YourAppName/AppDelegate.m projet et vérifiez que vous avez [AppCenterReactNativeCrashes register]; au lieu de [AppCenterReactNativeCrashes registerWithAutomaticProcessing];.
2. Ouvrez le fichier du android/app/src/main/res/values/strings.xml projet et vérifiez que appCenterCrashes_whenToSendCrashes est défini sur ASK_JAVASCRIPT.

Tous les rappels différents de l’écouteur d’événement sont abordés un par un dans ce document, mais vous devez définir un écouteur d’événement qui définit tous les rappels à la fois.

L’incident doit-il être traité ?

Implémentez ce rappel si vous souhaitez décider si un incident particulier doit être traité ou non. Par exemple, il peut y avoir un incident au niveau du système que vous souhaitez ignorer et que vous ne souhaitez pas envoyer à App Center.

Crashes.setListener({

    shouldProcess: function (report) {
        return true; // return true if the crash report should be processed, otherwise false.
    },

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

Notes

Pour utiliser cette fonctionnalité, vous devez configurer votre application correctement pour le service d’incident.

Cette fonctionnalité dépend du traitement des incidents dans JavaScript.

Demander le consentement de l’utilisateur pour envoyer un journal d’incident

Si la confidentialité de l’utilisateur est importante pour vous, vous devez obtenir une confirmation de l’utilisateur avant d’envoyer un rapport d’incident à App Center. Le Kit de développement logiciel (SDK) expose un rappel qui indique aux incidents App Center d’attendre la confirmation de l’utilisateur avant d’envoyer des rapports d’incident.

Si vous avez choisi de le faire, il vous incombe d’obtenir la confirmation de l’utilisateur, par exemple via une invite de dialogue avec l’une des options suivantes : Toujours envoyer, Envoyer et Ne pas envoyer. En fonction de l’entrée, vous indiquerez aux incidents App Center ce qu’il faut faire et le plantage sera ensuite géré en conséquence.

Notes

Le SDK n’affiche pas de boîte de dialogue pour cela. L’application doit fournir sa propre interface utilisateur pour demander le consentement de l’utilisateur.

Le rappel suivant montre comment indiquer au SDK d’attendre la confirmation de l’utilisateur avant d’envoyer des incidents :

Crashes.setListener({

    shouldAwaitUserConfirmation: function (report) {

        // Build your own UI to ask for user consent here. SDK doesn't provide one by default.

        // Return true if you built a UI for user consent and are waiting for user input on that custom UI, otherwise false.
        return true;
    },

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

Si vous retournez true, votre application doit obtenir (à l’aide de votre propre code) l’autorisation de l’utilisateur et mettre à jour le SDK avec le résultat à l’aide de l’API suivante :

import Crashes, { UserConfirmation } from 'appcenter-crashes';

// Depending on the user's choice, call Crashes.notifyUserConfirmation() with the right value.
Crashes.notifyUserConfirmation(UserConfirmation.DONT_SEND);
Crashes.notifyUserConfirmation(UserConfirmation.SEND);
Crashes.notifyUserConfirmation(UserConfirmation.ALWAYS_SEND);

Notes

Pour utiliser cette fonctionnalité, configurez correctement votre application pour le service d’incident. La fonctionnalité dépend du traitement des incidents dans JavaScript.

Obtenir des informations sur les status d’envoi d’un journal d’incident

Parfois, vous souhaitez connaître la status de l’incident de votre application. Un cas d’usage courant est que vous souhaiterez peut-être afficher l’interface utilisateur qui indique aux utilisateurs que votre application envoie un rapport d’incident, ou, si votre application se bloque rapidement après le lancement, vous souhaitez ajuster le comportement de l’application pour vous assurer que les journaux d’incident peuvent être envoyés. App Center Crash a trois rappels différents que vous pouvez utiliser dans votre application pour être informé de ce qui se passe.

Pour ce faire, définissez un écouteur d’événements dans votre code, comme illustré dans l’exemple suivant :

Crashes.setListener({
    onBeforeSending: function (report) {
        // called after Crashes.process and before sending the crash.
    },
    onSendingSucceeded: function (report) {
        // called when crash report sent successfully.
    },
    onSendingFailed: function (report) {
        // called when crash report couldn't be sent.
    }

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

Tous les rappels sont facultatifs. Vous n’avez pas besoin de fournir les 3 méthodes dans l’objet d’écouteur d’événements. Par exemple, vous pouvez implémenter uniquement onBeforeSending.

Notes

Pour utiliser cette fonctionnalité, vous devez configurer votre application correctement pour le service d’incident.

Cette fonctionnalité dépend du traitement des incidents dans JavaScript.

Notes

Si Crashes.setListener est appelé plusieurs fois, le dernier gagne ; il remplace les écouteurs précédemment définis par Crashes.setListener.

onSendingFailed La réception signifie qu’une erreur non récupérable telle qu’un code 4xx s’est produite. Par exemple, 401 signifie que le appSecret est incorrect.

Ce rappel n’est pas déclenché s’il s’agit d’un problème réseau. Dans ce cas, le Kit de développement logiciel (SDK) continue de réessayer (et interrompt également les nouvelles tentatives lorsque la connexion réseau est interrompue). Si nous avons des problèmes réseau ou une panne sur le point de terminaison et que vous redémarrez l’application, onBeforeSending est à nouveau déclenchée après le redémarrage du processus.

Ajouter des pièces jointes à un rapport d’incident

Vous pouvez ajouter des pièces jointes binaires et de texte à un rapport d’incident. Le Kit de développement logiciel (SDK) les envoie avec le plantage afin que vous puissiez les voir dans le portail App Center. Le rappel suivant est appelé juste avant d’envoyer le blocage stocké à partir des précédents lancements de l’application. Il ne sera pas appelé lorsque l’incident se produit. Assurez-vous que le fichier de pièce jointe n’est pas nommé minidump.dmp , car ce nom est réservé aux fichiers minidump. Voici un exemple montrant comment joindre du texte et une image à un incident :

import Crashes, { ErrorAttachmentLog } from 'appcenter-crashes';

Crashes.setListener({
    getErrorAttachments(report) {
        const textAttachment = ErrorAttachmentLog.attachmentWithText('Hello text attachment!', 'hello.txt');
        const binaryAttachment = ErrorAttachmentLog.attachmentWithBinary(`${imageAsBase64string}`, 'logo.png', 'image/png');
        return [textAttachment, binaryAttachment];
    }

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

Le fileName paramètre est facultatif (peut être null) et est utilisé uniquement dans le portail App Center. À partir d’une occurrence d’incident spécifique dans le portail, vous pouvez voir les pièces jointes et les télécharger. Si vous avez spécifié un nom de fichier, il s’agit du nom de fichier à télécharger. Sinon, le nom de fichier est généré pour vous.

Pour configurer le getErrorAttachments rappel pour qu’il fonctionne avec les fonctions asynchrones/await ES2017, retournez plutôt une promesse remplie. L’exemple suivant attache un texte et une image à un incident de manière asynchrone :

import Crashes, { ErrorAttachmentLog } from 'appcenter-crashes';

Crashes.setListener({
    getErrorAttachments(report) {
        return (async () => {
            const textContent = await readTextFileAsync(); // use your async function to read text file
            const binaryContent = await readBinaryFileAsync(); // use your async function to read binary file
            const textAttachment = ErrorAttachmentLog.attachmentWithText(textContent, 'hello.txt');
            const binaryAttachment = ErrorAttachmentLog.attachmentWithBinary(binaryContent, 'logo.png', 'image/png');
            return [textAttachment, binaryAttachment];
        })();
    }

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

Notes

Pour utiliser cette fonctionnalité, vous devez configurer votre application correctement pour le service d’incident.

Cette fonctionnalité dépend du traitement des incidents dans JavaScript.

Notes

La limite de taille est actuellement de 1,4 Mo sur Android et de 7 Mo sur iOS. La tentative d’envoi d’une pièce jointe plus volumineuse déclenche une erreur.

Erreurs gérées

App Center vous permet également de suivre les erreurs à l’aide d’exceptions gérées via trackError la méthode . Une application peut éventuellement attacher des propriétés ou/et des pièces jointes à un rapport d’erreurs géré pour fournir un contexte supplémentaire.

try {
    // Throw error.
} catch (error) {

    // Prepare properties.
    const properties = { 'Category' : 'Music', 'Wifi' : 'On' };

    // Prepare attachments.
    const textAttachment = ErrorAttachmentLog.attachmentWithText('Hello text attachment!', 'hello.txt');
    const attachments = [textAttachment];

    // Create an exception model from error.
    const exceptionModel1 = ExceptionModel.createFromError(error);

    // ..or generate with your own error data.
    const exceptionModel2 = ExceptionModel.createFromTypeAndMessage("type", "message", "stacktrace");

    // Track error with custom data.
    Crashes.trackError(exceptionModel1, properties, attachments);
    Crashes.trackError(exceptionModel1, properties, nil);
    Crashes.trackError(exceptionModel2, nil, attachments);
    Crashes.trackError(exceptionModel2, nil, nil);
}

Bloc-arrêt

App Center prend en charge les blocages du bloc-notes d’Android NDK dans une React Native applications.

Suivez les étapes de configuration normales ci-dessus, et dans votre MainActivity.java remplacement OnCreate , ajoutez la configuration minidump et appelez dans votre code natif qui configure votre configuration breakpad.

Exemple :

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Crashes.getMinidumpDirectory().thenAccept(new AppCenterConsumer<String>() {
      @Override
      public void accept(String path) {
        // Path is null when Crashes is disabled.
        if (path != null) {
          // links to NDK
          setupBreakpadListener(path);
        }
      }
    });
  }

Activer ou désactiver les incidents App Center au moment de l’exécution

Vous pouvez activer et désactiver les incidents App Center au moment de l’exécution. Si vous le désactivez, le SDK n’effectuera aucun rapport d’incident pour l’application.

await Crashes.setEnabled(false);

Pour réactiver les incidents true App Center, utilisez la même API, mais passez en tant que paramètre.

await Crashes.setEnabled(true);

L’état est conservé dans le stockage de l’appareil au cours des lancements d’application.

Vérifier si les incidents App Center sont activés

Vous pouvez également case activée si les incidents App Center sont activés ou non :

const enabled = await Crashes.isEnabled();