Plantages d’App Center (Unity)

Important

Visual Studio App Center doit être mis hors service le 31 mars 2025. Bien que vous puissiez continuer à utiliser Visual Studio App Center jusqu’à ce qu’il soit entièrement mis hors service, il existe plusieurs alternatives recommandées vers lesquelles vous pouvez envisager de migrer.

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

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

App Center plante automatiquement un journal d’incident chaque fois que votre application se bloque, avec un stockage de journal sur l’appareil. Lorsqu’un utilisateur redémarre l’application, le Kit de développement logiciel (SDK) envoie le rapport d’incident à App Center. La collecte des incidents fonctionne à la fois pour les applications bêta et actives, c’est-à-dire les plantages envoyés à Google Play. Les journaux d’incident contiennent des informations précieuses pour vous aider à résoudre le blocage.

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

Les journaux d’incident sur iOS nécessitent une symbolique. Pour activer la symbolique, reportez-vous à la documentation relative aux diagnostics App Center, qui explique comment fournir des symboles pour votre application.

Important

Le Kit de développement logiciel (SDK) Crash pour Unity ne prend pas en charge UWP. Les instructions de cette page couvrent uniquement Android et iOS.

Notes

Le KIT de développement logiciel (SDK) ne transfère aucun journal d’incident si vous avez attaché le débogueur. Assurez-vous que le débogueur n’est pas attaché lorsque vous plantez l’application.

Notes

Si vous avez Enable CrashReport API activé dans PlayerSettings, le KIT de développement logiciel (SDK) ne collecte pas les journaux d’incident.

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 SDK. Cette API recherche les configurations de débogage et de mise en production. Vous ne pouvez donc l’utiliser que lors du débogage, car il ne fonctionnera pas pour les applications de mise en production.

Crashes.GenerateTestCrash();

Notes

Cette méthode fonctionne uniquement avec le paramètre Build de développement activé.

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

App Center Crashs a deux API qui vous donnent plus d’informations en cas de plantage 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 :

bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;

Notes

Cette méthode ne fonctionnera pas dans Awake().

Notes

Dans certains cas, un appareil avec une mémoire insuffisante ne peut 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 Kit de développement logiciel (SDK), vous pouvez case activée si l’application s’est plantée lors du lancement précédent :

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

L’appel HasCrashedInLastSessionAsync est utile si vous souhaitez ajuster le comportement ou l’interface utilisateur de votre application après un incident. Certains développeurs montrent 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 plantée précédemment, vous pouvez obtenir des détails sur le dernier incident.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Le cas d’usage le plus courant pour cette API est lorsqu’un utilisateur implémente son délégué ou écouteur de plantage personnalisé.

Personnaliser votre utilisation des incidents d’App Center

App Center Crash fournit des rappels permettant aux développeurs d’effectuer des actions supplémentaires avant et quand ils envoient des journaux d’incident à App Center.

Notes

Définissez le rappel avant le démarrage d’App Center, par exemple dans Awake la méthode, car App Center démarre le traitement se bloque immédiatement après le démarrage.

Le blocage doit-il être traité ?

Définissez le rappel suivant 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 non envoyer à App Center.

Crashes.ShouldProcessErrorReport = (ErrorReport report) =>
{
     // Check the report in here and return true or false depending on the ErrorReport.
    return true;
};

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

Si la confidentialité des utilisateurs est importante pour vous, vous pouvez 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 à App Center Crashs d’attendre la confirmation de l’utilisateur avant d’envoyer des rapports d’incident.

Si votre code utilise ce rappel, vous êtes responsable de l’obtention de la confirmation de l’utilisateur. Une option consiste à utiliser 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 au Centre d’applications que l’application bloque ce qu’il doit faire et que l’incident sera ensuite géré en conséquence.

Notes

Le Kit de développement logiciel (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 KIT de développement logiciel (SDK) d’attendre la confirmation de l’utilisateur avant de bloquer l’envoi :

Crashes.ShouldAwaitUserConfirmation = () =>
{
    // 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;
};

Si le rappel retourne true, vous devez obtenir l’autorisation utilisateur et envoyer un message au KIT de développement logiciel (SDK) avec le résultat à l’aide de l’API suivante :

// Depending on the user's choice, call Crashes.NotifyUserConfirmation() with the right value.
Crashes.NotifyUserConfirmation(UserConfirmation.DontSend);
Crashes.NotifyUserConfirmation(UserConfirmation.Send);
Crashes.NotifyUserConfirmation(UserConfirmation.AlwaysSend);

Par exemple, vous pouvez vous référer à notre exemple de boîte de dialogue personnalisée.

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

Parfois, vous souhaitez connaître le status de l’incident de votre application. Un cas d’usage courant consiste à afficher une interface utilisateur qui informe l’utilisateur que l’application envoie un rapport d’incident. Un autre scénario consiste à ajuster le comportement de l’application pour vous assurer que les journaux d’incident peuvent être envoyés peu de temps après la relance. App Center Crash fournit trois rappels différents que vous pouvez effectuer pour être informé de ce qui s’est produit :

Le rappel suivant sera appelé avant que le KIT de développement logiciel (SDK) envoie un journal d’incident

Crashes.SendingErrorReport += (errorReport) =>
{
    // Your code, e.g. to present a custom UI.
};

Si nous avons des problèmes réseau ou une panne sur le point de terminaison et que vous redémarrez l’application, SendingErrorReport est à nouveau déclenché après le redémarrage du processus.

Le rappel suivant sera appelé une fois que le KIT de développement logiciel (SDK) a envoyé un journal d’incident avec succès

Crashes.SentErrorReport += (errorReport) =>
{
    // Your code, e.g. to hide the custom UI.
};

Le rappel suivant sera appelé si le KIT de développement logiciel (SDK) n’a pas pu envoyer un journal d’incident

Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
    // Your code goes here.
};

FailedToSendErrorReport 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).

Ajouter des pièces jointes à un rapport d’incident ou d’exception non pris en charge

Vous pouvez également ajouter éventuellement des pièces jointes binaires et de texte à un rapport d’exception sur incident ou non pris en charge . Le Kit de développement logiciel (SDK) les envoie avec le rapport afin que vous puissiez les voir dans le portail App Center. Le rappel suivant sera appelé juste avant l’envoi du rapport stocké. Pour les plantages, il se produit au prochain lancement de l’application. Pour les exceptions non gérées, vous devez choisir d’envoyer des pièces jointes. 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 de la façon d’attacher du texte et une image à un rapport :

Crashes.GetErrorAttachments = (ErrorReport report) =>
{
    // Your code goes here.
    return new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
};

Les incidents sont différenciés des exceptions non gérées dans les rapports avec la IsCrash propriété . La propriété sera true pour les plantages et false dans le cas contraire.

Notes

La limite de taille est pour les pièces jointes actuellement de 7 Mo. La tentative d’envoi d’une pièce jointe plus volumineuse déclenche une erreur.

Notes

GetErrorAttachmentsest appelé sur le thread main et ne fractionne pas le travail sur les images. Pour éviter de bloquer la boucle de jeu, n’effectuez pas de tâches de longue durée dans ce rappel.

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

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

Crashes.SetEnabledAsync(false);

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

Crashes.SetEnabledAsync(true);

Vous n’avez pas besoin d’attendre cet appel pour rendre d’autres appels d’API (tels que IsEnabledAsync) cohérents.

L’état est conservé dans le stockage de l’appareil entre les lancements d’application.

Vérifiez si les blocages d’App Center sont activés

Vous pouvez également case activée si les incidents d’App Center sont activés :

bool isEnabled = await Crashes.IsEnabledAsync();

Exceptions gérées dans Unity

App Center vous permet également de suivre les erreurs à l’aide d’exceptions gérées dans Unity. Pour ce faire, utilisez la TrackError méthode :

try {
    // your code goes here.
} catch (Exception exception) {
    Crashes.TrackError(exception);
}

Pour plus de contexte sur votre erreur, vous pouvez également y attacher des propriétés. Passez les propriétés en tant que dictionnaire de chaînes. Cette étape est facultative.

try {
    // your code goes here.
} catch (Exception exception) {
    var properties = new Dictionary<string, string>
    {
        { "Category", "Music" },
        { "Wifi", "On" }
    };
    Crashes.TrackError(exception, properties);
}

Vous pouvez également ajouter éventuellement des pièces jointes binaires et de texte à un rapport d’erreurs géré. Passez les pièces jointes en tant que tableau d’objets ErrorAttachmentLog , comme illustré dans l’exemple ci-dessous.

try {
    // your code goes here.
} catch (Exception exception) {
    var attachments = new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
    Crashes.TrackError(exception, attachments: attachments);
}

Exceptions non gérées dans Unity

Signaler des exceptions non gérées

Par défaut, le Kit de développement logiciel (SDK) App Center ne signale pas les exceptions non gérées levées dans votre application qui ne provoquent pas d’incident fatal. Pour activer cette fonctionnalité, appelez la méthode suivante :

Crashes.ReportUnhandledExceptions(true);

Après avoir appelé cette API, App Center consigne toutes les exceptions non gérées en tant que Problèmes dans le portail App Center, comme les exceptions gérées mentionnées précédemment. Pour désactiver cette fonctionnalité, appelez le même passage false d’API que le paramètre.

Crashes.ReportUnhandledExceptions(false);

Notes

Certaines exceptions non gérées détectées par le Kit de développement logiciel (SDK) App Center s’affichent en tant qu’erreurs dans l’interface utilisateur d’App Center. Cela est dû au fait que Unity intercepte les exceptions non gérées par défaut, ce qui signifie que l’application ne se ferme pas et n’est pas considérée comme un incident.

Ajouter des pièces jointes à un rapport d’exception non pris en charge

Par défaut, le Kit de développement logiciel (SDK) App Center n’active pas les pièces jointes sur les exceptions non gérées. Pour activer cette fonctionnalité, définissez le enableAttachmentsCallback paramètre booléen de la méthode sur ReportUnhandledExceptionstrue:

Crashes.ReportUnhandledExceptions(true, true);

Ensuite, vous pouvez éventuellement ajouter des pièces jointes à un rapport d’exception non pris en charge en implémentant le rappel GetErrorAttachments .

Signalement des incidents du NDK

Rapports d’incidents

Pour recevoir des rapports d’incident appropriés dans App Center, vérifiez d’abord que le Kit de développement logiciel (SDK) App Center Crashs est configuré en suivant les instructions ci-dessus.

Création de la bibliothèque de blocs d’arrêt

Ensuite, vous devez inclure et compiler Google Breakpad en suivant les instructions répertoriées dans le google breakpad pour Android README officiel. Pour l’utiliser dans Unity, incluez le fichier binaire avec votre application.

Notes

Le Kit de développement logiciel (SDK) App Center ne regroupe pas Google Breakpad par défaut.

Attachement du gestionnaire d’exceptions

Une fois que google breakpad est inclus, attachez le gestionnaire d’incidentS NDK :

/* Attach NDK Crash Handler. */
var minidumpDir = Crashes.GetMinidumpDirectoryAsync();
setupNativeCrashesListener(minidumpDir.Result);

...

[DllImport("YourLib")]
private static extern void setupNativeCrashesListener(string path);

La méthode setupNativeCrashesListener est une méthode native que vous devez implémenter en C/C++ :

#include <android/log.h>
#include "google-breakpad/src/client/linux/handler/exception_handler.h"
#include "google-breakpad/src/client/linux/handler/minidump_descriptor.h"

static google_breakpad::ExceptionHandler exception_handler(google_breakpad::MinidumpDescriptor(), NULL, dumpCallback, NULL, true, -1);

/**
 * Registers breakpad as the exception handler for NDK code.
 * @param path minidump directory path returned from Crashes.GetMinidumpDirectoryAsync()
 */
extern "C" void setupNativeCrashesListener(const char *path) {
    google_breakpad::MinidumpDescriptor descriptor(path);
    exception_handler.set_minidump_descriptor(descriptor);
}

Où dumpCallback est utilisé pour la résolution des problèmes :

/*
 * Triggered automatically after an attempt to write a minidump file to the breakpad folder.
 */
static bool dumpCallback(const google_breakpad::MinidumpDescriptor &descriptor,
                         void *context,
                         bool succeeded) {

    /* Allow system to log the native stack trace. */
    __android_log_print(ANDROID_LOG_INFO, "YourLogTag",
                        "Wrote breakpad minidump at %s succeeded=%d\n", descriptor.path(),
                        succeeded);
    return false;
}

Une fois ces méthodes correctement configurées, l’application envoie automatiquement le minidump à App Center au redémarrage. Pour résoudre les problèmes, vous pouvez utiliser des journaux détaillés pour case activée si des minidumps sont envoyés après le redémarrage de l’application.

Notes

App Center utilise le nom minidump.dmp réservé pour les pièces jointes minidump. Veillez à donner un autre nom à votre pièce jointe, sauf s’il s’agit d’un fichier minidump afin que nous puissions le gérer correctement.

Avertissement

Il existe un bogue connu dans le bloc d’arrêt qui rend impossible la capture des plantages sur les émulateurs x86.

Symbolique

Pour plus d’informations sur le traitement des incidents, consultez la documentation Diagnostics .