В этом руководстве описывается, как настроить отчеты о сбоях с помощью API Crashlytics. По умолчанию Crashlytics автоматически собирает отчеты о сбоях платформы для всех пользователей вашего приложения (вместо этого вы можете отключить автоматические отчеты о сбоях и включить для своих пользователей возможность создавать отчеты о сбоях ). Crashlytics предоставляет пять механизмов ведения журналов «из коробки»: пользовательские ключи , пользовательские журналы , идентификаторы пользователей , перехваченные и неперехваченные исключения.
Для приложений Flutter отчеты о фатальных ошибках отправляются в Crashlytics в режиме реального времени без необходимости перезапуска приложения пользователем. Нефатальные отчеты записываются на диск и отправляются вместе со следующим фатальным отчетом или при перезапуске приложения.
Сообщать о неперехваченных исключениях
Вы можете автоматически перехватывать все «фатальные» ошибки, возникающие в рамках Flutter, переопределив FlutterError.onError
с помощью FirebaseCrashlytics.instance.recordFlutterFatalError
. В качестве альтернативы, чтобы также перехватывать «нефатальные» исключения, переопределите FlutterError.onError
с помощью FirebaseCrashlytics.instance.recordFlutterError
:
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp();
bool weWantFatalErrorRecording = true;
FlutterError.onError = (errorDetails) {
if(weWantFatalErrorRecording){
FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
} else {
FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
}
};
runApp(MyApp());
}
Асинхронные ошибки
Асинхронные ошибки не улавливаются платформой Flutter:
ElevatedButton(
onPressed: () async {
throw Error();
}
...
)
Чтобы отловить такие ошибки, вы можете использовать обработчик PlatformDispatcher.instance.onError
:
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp();
FlutterError.onError = (errorDetails) {
FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
};
// Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
PlatformDispatcher.instance.onError = (error, stack) {
FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
return true;
};
runApp(MyApp());
}
Ошибки вне Flutter
Чтобы перехватывать ошибки, возникающие вне контекста Flutter, установите прослушиватель ошибок в текущем Isolate
:
Isolate.current.addErrorListener(RawReceivePort((pair) async {
final List<dynamic> errorAndStacktrace = pair;
await FirebaseCrashlytics.instance.recordError(
errorAndStacktrace.first,
errorAndStacktrace.last,
fatal: true,
);
}).sendPort);
Сообщить об обнаруженных исключениях
Помимо автоматического сообщения о сбоях вашего приложения, Crashlytics позволяет записывать нефатальные исключения и отправляет их вам при следующем сообщении о фатальном событии или при перезапуске приложения.
Используйте метод recordError
для записи нефатальных исключений в блоках catch вашего приложения. Например:
await FirebaseCrashlytics.instance.recordError(
error,
stackTrace,
reason: 'a non-fatal error'
);
// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
Вы также можете захотеть записать дополнительную информацию об ошибке, что возможно с помощью свойства information
:
await FirebaseCrashlytics.instance.recordError(
error,
stackTrace,
reason: 'a non-fatal error',
information: ['further diagnostic information about the error', 'version 2.0'],
);
Эти исключения отображаются как нефатальные проблемы в консоли Firebase. Сводка проблем содержит всю информацию о состоянии, которую вы обычно получаете при сбоях, а также разбивку по версиям и аппаратным устройствам.
Crashlytics обрабатывает исключения в выделенном фоновом потоке, чтобы минимизировать влияние на производительность вашего приложения. Чтобы уменьшить сетевой трафик ваших пользователей, Crashlytics при необходимости ограничит количество отчетов, отправляемых с устройства.
Добавить пользовательские ключи
Пользовательские ключи помогают вам получить конкретное состояние вашего приложения, приводящее к сбою. Вы можете связать произвольные пары ключ/значение с отчетами о сбоях, а затем использовать пользовательские ключи для поиска и фильтрации отчетов о сбоях в консоли Firebase.
На панели управления Crashlytics вы можете искать проблемы, соответствующие пользовательскому ключу.
Просматривая конкретную проблему в консоли, вы можете просмотреть связанные пользовательские ключи для каждого события (подвкладка «Ключи ») и даже отфильтровать события по пользовательским ключам (меню «Фильтр» вверху страницы).
Используйте метод экземпляра setCustomKey
для установки пар ключ/значение. Вот некоторые примеры:
// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');
// Set a key to a boolean.
FirebaseCrashlytics.instance.setCustomKey("bool_key", true);
// Set a key to an int.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1);
// Set a key to a long.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1L);
// Set a key to a float.
FirebaseCrashlytics.instance.setCustomKey("float_key", 1.0f);
// Set a key to a double.
FirebaseCrashlytics.instance.setCustomKey("double_key", 1.0);
Добавить пользовательские сообщения журнала
Чтобы получить больше контекста для событий, приведших к сбою, вы можете добавить в свое приложение собственные журналы Crashlytics. Crashlytics связывает журналы с данными о сбоях и отображает их в консоли Firebase на вкладке Журналы Crashlytics.
Используйте log
, чтобы выявить проблемы. Например:
FirebaseCrashlytics.instance.log("Higgs-Boson detected! Bailing out");
Установить идентификаторы пользователей
Для диагностики проблемы часто полезно знать, у кого из ваших пользователей произошел данный сбой. Crashlytics включает в себя способ анонимной идентификации пользователей в отчетах о сбоях.
Чтобы добавить идентификаторы пользователей в отчеты, назначьте каждому пользователю уникальный идентификатор в форме идентификационного номера, токена или хеш-значения:
FirebaseCrashlytics.instance.setUserIdentifier("12345");
Если вам когда-нибудь понадобится очистить идентификатор пользователя после его установки, сбросьте значение на пустую строку. Очистка идентификатора пользователя не удаляет существующие записи Crashlytics. Если вам нужно удалить записи, связанные с идентификатором пользователя, обратитесь в службу поддержки Firebase .
Включить подписку на получение отчетов
По умолчанию Crashlytics автоматически собирает отчеты о сбоях для всех пользователей вашего приложения. Чтобы предоставить пользователям больше контроля над отправляемыми ими данными, вы можете включить возможность включения отчетов, отключив автоматические отчеты и отправляя данные в Crashlytics только тогда, когда вы решите это сделать в своем коде:
Отключите автоматический сбор:
платформы Apple
Добавьте новый ключ в файл
Info.plist
:- Ключ:
FirebaseCrashlyticsCollectionEnabled
- Значение:
false
Андроид
В блоке
application
вашего файлаAndroidManifest.xml
добавьте тегmeta-data
, чтобы отключить автоматический сбор:<meta-data android:name="firebase_crashlytics_collection_enabled" android:value="false" />
- Ключ:
Включите сбор для избранных пользователей, вызвав переопределение сбора данных Crashlytics во время выполнения.
Значение переопределения сохраняется при запуске вашего приложения, поэтому Crashlytics может автоматически собирать отчеты. Чтобы отказаться от автоматического сообщения о сбоях, передайте
false
в качестве значения переопределения. Если установлено значениеfalse
, новое значение не применяется до следующего запуска приложения.FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
Управление данными Crash Insights
Crash Insights помогает вам решать проблемы, сравнивая анонимные трассировки стека со трассировками из других приложений Firebase и сообщая вам, является ли ваша проблема частью более широкой тенденции. Для многих проблем Crash Insights даже предоставляет ресурсы, которые помогут вам устранить сбой.
Crash Insights использует агрегированные данные о сбоях для выявления общих тенденций стабильности. Если вы предпочитаете не делиться данными своего приложения, вы можете отказаться от Crash Insights в меню Crash Insights в верхней части списка проблем Crashlytics в консоли Firebase .