Fazer upgrade para o SDK do Firebase Crashlytics

iOS+ Android Unity

Não há mais suporte para o SDK do Fabric desde 15 de novembro de 2020. Para continuar recebendo relatórios de erros no Console do Firebase, siga as instruções nesta página para fazer upgrade e usar o SDK do Firebase Crashlytics.

Agora, é possível configurar o Crashlytics no seu app usando o novo SDK oficial do Firebase Crashlytics, que oferece APIs aprimoradas que são mais intuitivas e consistentes com outros produtos Firebase.

Neste guia, você verá como fazer upgrade para o novo SDK usando o SDK do Fabric legado. Ele descreve as alterações que acompanham as novas APIs, o motivo das alterações e como atualizar seu código, se necessário.

Antes de começar

Etapa 1: adicionar um arquivo de configuração do Firebase

1. Abra suas Configurações do projeto. No card Seus apps, selecione o ID do pacote do app que precisa de um arquivo de configuração.

2. Clique em Fazer o download do GoogleService-Info.plist para conseguir o arquivo de configuração das plataformas Apple do Firebase (GoogleService-Info.plist).

   • É possível fazer de novo o download do arquivo de configuração das plataformas Apple do Firebase a qualquer momento.

   • Verifique se o nome do arquivo de configuração não foi anexado com caracteres extras, como (2).

3. Mova o arquivo de configuração para a raiz do seu projeto Xcode. Se solicitado, selecione adicionar o arquivo de configuração a todos os destinos.

Se o projeto tiver vários IDs de pacotes, associe cada ID com um app registrado no Console do Firebase para que tenha o próprio arquivo GoogleService-Info.plist.

Observação: o arquivo de configuração do Firebase contém identificadores exclusivos, mas não secretos, para seu projeto.
Acesse Noções básicas sobre projetos do Firebase para mais informações sobre esse arquivo de configuração.

Etapa 2: adicionar o SDK do Firebase Crashlytics

1. No Cocoapods, substitua os pods Fabric e Crashlytics por um pod Firebase/Crashlytics em todos os destinos.

   Recomendado: para ter uma experiência ideal com o Firebase Crashlytics, também recomendamos adicionar o SDK do Firebase para o Google Analytics ao seu app.

   # Add the pod for Firebase Crashlytics
   pod 'Firebase/Crashlytics'
   
   # Recommended: Add the Firebase pod for Google Analytics
   pod 'Firebase/Analytics'
   

2. Desinstale ou remova diretamente dependências de terceiros do Fabric, como dependências do Fabric Answers e de kits de terceiros.

3. Instale e atualize os pods e abra o arquivo .xcworkspace para ver o projeto no Xcode:

   pod install

   open YOUR_PROJECT.xcworkspace

Etapa 3: atualizar seu código

1. No Xcode, recrie o app e abra novamente o arquivo .xcworkspace.

2. Revise as seguintes alterações do SDK e faça as atualizações adequadas no seu código:

---

O Crashlytics agora alterna os IDs com base nos IDs de instalação do Firebase.

O Crashlytics usa o UUID de instalação dele para identificar instâncias do app e associar os dados dos usuários aos dispositivos. Antes, o Crashlytics alternava o UUID de instalação do usuário quando o ID de publicidade do dispositivo era alterado. Agora, o Crashlytics alterna o UUID de instalação com base no ID de instalação do Firebase (FID, na sigla em inglês) do usuário. Para mais informações, acesse Gerenciar IDs de instalação do Firebase.

Motivo para a alteração

O uso de FIDs (IDs de instalação do Firebase, na sigla em inglês) é consistente com outros SDKs do Firebase.

---

Os scripts de execução e de símbolos de upload agora estão no Firebase Crashlytics.

Observação: upload-symbols está em processo de integração com o restante das ferramentas da Firebase CLI.

Agora você consegue acessar os scripts run e upload-symbols da nova biblioteca FirebaseCrashlytics. Observe que você ainda consegue chamar upload-symbols de qualquer lugar no processo de criação para fazer o upload manual dos dSYMs.

Além disso, o API_KEY e o BUILD_SECRET do Fabric não estão mais incluídos no novo SDK. Em vez disso, o Crashlytics agora usa o GoogleService-info.plist do seu app para associá-lo ao projeto do Firebase e reter os dados históricos de falhas.

SDK do Fabric

${PODS_ROOT}/Fabric/run API_KEY BUILD_SECRET
/path/to/pods/directory/Fabric/upload-symbols

SDK do Firebase Crashlytics

${PODS_ROOT}/FirebaseCrashlytics/run
/path/to/pods/directory/FirebaseCrashlytics/upload-symbols

Motivo para a alteração

O Crashlytics não usa mais o SDK do Fabric como uma dependência. Por isso, estamos migrando nossas ferramentas de CLI para uma nova biblioteca.

---

A biblioteca do Crashlytics agora é chamada de FirebaseCrashlytics.

No app, atualize os caminhos de importação:

SDK do Fabric

Swift

import Crashlytics

Objective-C

@import Crashlytics

SDK do Firebase Crashlytics

Swift

import FirebaseCrashlytics

Objective-C

@import FirebaseCrashlytics

Motivo para a alteração

Atualizar o nome da biblioteca Crashlytics torna-a consistente com outras bibliotecas do Firebase (por exemplo, FirebaseFirestore e FirebaseAuth).

---

O FirebaseCrashlytics não funciona mais com o SDK do Fabric.

Agora, FirebaseCrashlytics só pode ser inicializado com o SDK do Firebase Crashlytics. Para iniciar uma instância do FirebaseCrashlytics, chame FirebaseApp.configure no Swift ou [FIRApp configure] no Objective-C.

No application:didFinishLaunchingWithOptions, substitua as chamadas para Fabric.with e startWithAPIKey por uma chamada para FirebaseApp:

SDK do Fabric

Swift

Fabric.with([Crashlytics.self])

Objective-C

[Fabric with:@[[Crashlytics class]]];
+ startWithAPIKey:
+ startWithAPIKey:delegate:

SDK do Firebase Crashlytics

Swift

FirebaseApp.configure()

Objective-C

[FIRApp configure];

Motivo para a alteração

Usar os novos métodos para inicializar o Crashlytics é mais consistente com a maneira como outros serviços do Firebase são inicializados.

---

Os métodos crash e throwException foram removidos.

O novo SDK não inclui mais os métodos crash ou throwException. Em vez disso, use fatalError no Swift ou uma matriz vazia no Objective-C para forçar uma falha.

SDK do Firebase Crashlytics

Swift

// Force a test crash
fatalError()

Objective-C

// Force a test crash
@[][1];

Motivo para a alteração

Diferentes tipos de falhas podem ocorrer por vários motivos e esses métodos não especificam claramente se as falhas resultantes ocorreram durante o tempo de execução ou no SDK nativo do app.

---

O método sharedInstance agora é chamado de crashlytics.

O novo SDK não inclui mais o método sharedInstance. Para inicializar o Crashlytics, use crashlytics (leia a documentação de referência do Swift ou Objective-C para mais informações). No representante do app, atualize o script de inicialização:

SDK do Fabric

Swift

Crashlytics.sharedInstance()

Objective-C

[Crashlytics sharedInstance];

SDK do Firebase Crashlytics

Swift

Crashlytics.crashlytics()

Objective-C

[FIRCrashlytics crashlytics];

Motivo para a alteração

Renomeamos o método getter de instância para que fique consistente com outros SDKs do Firebase.

---

O setUserIdentifier agora é setUserID. O setUserName e setUserEmail foram removidos.

Antes, era possível definir um nome ou e-mail associado a uma falha usando setUserName e setUserEmail. No entanto, esses métodos não serão mais definidos. O novo método preferencial para definir IDs dos seus usuários consiste em usar setUserID.

SDK do Fabric

Swift

Crashlytics.sharedInstance().setUserIdentifier("user_id")

Crashlytics.sharedInstance().setUserEmail("user_email")

Crashlytics.sharedInstance().setUserName("user_name")

Objective-C

[[Crashlytics sharedInstance] setUserIdentifier:@"user_id"];

[[Crashlytics sharedInstance] setUserEmail:@"user_email"];

[[Crashlytics sharedInstance] setUserName:@"user_name"];

SDK do Firebase Crashlytics

Swift

Crashlytics.crashlytics().setUserID("user_id")

Objective-C

[[FIRCrashlytics crashlytics] setUserID:@"user_id"];

Motivo para a alteração

Adotamos o nome do método setUserID para que fique consistente com outras APIs do Firebase e removemos setUserName e setUserEmail para desestimular o registro de PII por meio do Crashlytics.

---

O CLSLogv e CLSNSLogv foram substituídos por funções de geração de registros.

O novo SDK não inclui mais as funções CLSLogv ou CLSNSLogv. Para adicionar mensagens de registro personalizadas, use os novos métodos de geração de registros na biblioteca Crashlytics. Os novos métodos não são mais impressos em stdout ou NSLog. Recomendamos que você grave um wrapper se quiser manter esse comportamento.

SDK do Fabric

Swift

CLSLogv("%@, %@", getVaList([first_arg, second_arg]))

CLSNSLogv("%@, %@", getVaList([first_arg, second_arg]))

Objective-C

CLSLog(@"%@, %@", first_arg, second_arg);
CLSNSLog(@"%@, %@", first_arg, second_arg);

CLSLogv(@"%@, %@", args_va_list);
CLSNSLogv(@"%@, %@", args_va_list);

CLS_LOG(@"%@, %@", first_arg, second_arg);

SDK do Firebase Crashlytics

Swift

Crashlytics.crashlytics().log("\(first_arg), \(second_arg)")

Crashlytics.crashlytics().log(format: "%@, %@", arguments: getVaList([first_arg, second_arg]))

Objective-C

[[FIRCrashlytics crashlytics] log:@"first_arg, second_arg"];

[[FIRCrashlytics crashlytics] logWithFormat:@"%@, %@", first_arg, second_arg];

Se você usou CLS_LOG, adicione o seguinte a um arquivo de cabeçalho para continuar recebendo nomes de arquivos e números de linha nos log statements:

#define CLS_LOG(__FORMAT__, ...) [[FIRCrashlytics crashlytics] logWithFormat:@"%s line %d $ " __FORMAT__, __PRETTY_FUNCTION__, __LINE__, ##__VA_ARGS__]

Motivo para a alteração

Os novos métodos exigem instâncias, o que facilita o teste de código.

---

setCustomValue substitui setObjectValue, setIntValue, setFloatValue e setBoolValue.

Os métodos setter personalizados não estão mais incluídos no novo SDK. Antes, era possível usar os métodos para definir pares de chave-valor para enviar com seu relatório de erros. Agora, é possível usar setCustomValue:forKey para definir pares de chave-valor para todos os tipos de dados.

SDK do Fabric

Swift

Crashlytics.sharedInstance().setObjectValue("value", forKey: "object_key")

Crashlytics.sharedInstance().setIntValue(100, forKey: "int_key")

Crashlytics.sharedInstance().setFloatValue(99.9, forKey: "float_key")

Crashlytics.sharedInstance().setBoolValue(true, forKey: "bool_key")

Objective-C

[[Crashlytics sharedInstance] setObjectValue:@"key" forKey:@"object_key"];

[[Crashlytics sharedInstance] setIntValue:100 forKey:@"int_key"];

[[Crashlytics sharedInstance] setFloatValue:99.9 forKey:@"float_key"];

[[Crashlytics sharedInstance] setBoolValue:YES forKey:@"bool_key"];

SDK do Firebase Crashlytics

Swift

Crashlytics.crashlytics().setCustomValue("value", forKey: "object_key")

Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

Crashlytics.crashlytics().setCustomValue(99.9, forKey: "float_key")

Crashlytics.crashlytics().setCustomValue(true, forKey: "bool_key")

Objective-C

[[FIRCrashlytics crashlytics] setCustomValue:@"value" forKey:@"object_key"];

[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

[[FIRCrashlytics crashlytics] setCustomValue:@(99.9) forKey:@"float_key"];

[[FIRCrashlytics crashlytics] setCustomValue:@YES forKey:@"bool_key"];

Motivo para a alteração

O novo nome do método é exclusivo ao Crashlytics e deixa explícito que o Crashlytics não é compatível com chaves-valor.

---

recordCustomExceptionName:reason:frameArray: foi substituído pela API Exception Model.

Se o app for executado em um ambiente não nativo (por exemplo, JavaScript ou Unity), use a API Exception Model para reportar metadados de falha no formato de exceção nativo do app.

SDK do Fabric

Swift

Deixe topFrame = CLSStackFrame() topFrame.symbol = "doSomethingBad" topFrame.fileName = "bad.cc" topFrame.lineNumber = 23

let middleFrame = CLSStackFrame()
middleFrame.symbol = "doOtherStuff"
middleFrame.fileName = "stuff.cc"
middleFrame.lineNumber = 23;

let bottomFrame = CLSStackFrame()
bottomFrame.symbol = "main"
bottomFrame.fileName = "main.cc"
bottomFrame.lineNumber = 123

Crashlytics.sharedInstance().recordCustomExceptionName("FooException",
                                                       reason: "There was a foo.",
                                                       frameArray: [topFrame, middleFrame, bottomFrame])

Objective-C

CLSStackFrame *topFrame = [[CLSStackFrame alloc] init];
topFrame.symbol = @"doSomethingBad";
topFrame.fileName = @"bad.cc";
topFrame.lineNumber = 23;

CLSStackFrame *middleFrame = [[CLSStackFrame alloc] init];
middleFrame.symbol = @"doOtherStuff";
middleFrame.fileName = @"stuff.cc";
middleFrame.lineNumber = 23;

CLSStackFrame *bottomFrame = [[CLSStackFrame alloc] init];
bottomFrame.symbol = @"main";
bottomFrame.fileName = @"main.cc";
bottomFrame.lineNumber = 123;

[[Crashlytics sharedInstance] recordCustomExceptionName:@"FooException"
                                                 reason:@"There was a foo."
                                             frameArray:@[topFrame, middleFrame, bottomFrame]];

SDK do Firebase Crashlytics

Swift

var  ex = ExceptionModel.init(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame.init(symbol:"makeError" fileName:"handler.js" lineNumber:495),
  StackFrame.init(symbol:"then" fileName:"routes.js" lineNumber:102),
  StackFrame.init(symbol:"main" fileName:"app.js" lineNumber:12),
]

crashlytics.record(exceptionModel:ex)

Objective-C

model.stackTrace = @[
  [FIRStackFrame stackFrameWithSymbol:@"makeError" fileName:@"handler.js" lineNumber:495],
  [FIRStackFrame stackFrameWithSymbol:@"then" fileName:@"routes.js" lineNumber:102],
  [FIRStackFrame stackFrameWithSymbol:@"main" fileName:@"app.js" lineNumber:12],
];

Motivo para a alteração

Esse recurso foi solicitado há muito tempo e permite estender o Crashlytics para outras plataformas, como Unity, Flutter ou React Native.

---

O CrashlyticsDelegate foi substituído por métodos separados para processar relatórios de erros.

Agora é possível usar um novo conjunto de métodos para processar relatórios de erros:

• didFinishLaunchingWithOptions foi substituído pelo novo gerenciador checkForUnsentReportsWithCompletion.

• crashlyticsDidDetectReportForLastExecution foi substituído por didCrashDuringPreviousExecution. O didCrashDuringPreviousExecution permite detectar de maneira conveniente as falhas que ocorreram durante a última execução do app.

• crashlyticsCanUseBackgroundSessions foi definido permanentemente como verdadeiro.

• Não é mais possível inspecionar o objeto CLSReport no representante.

Por padrão, o Crashlytics faz o upload automático dos relatórios de erros na inicialização e é possível chamar didFinishLaunchingWithOptions para permitir que os usuários ativem os relatórios de erros. Agora, quando você chama setCrashlyticsCollectionEnabled=false para desativar os relatórios de falhas automáticos, o Crashlytics chama checkForUnsentReportsWithCompletion, que permite que os usuários escolham enviar relatórios de falhas quando o app falhar. Em seguida, chame sendUnsentReports se o usuário ativar ou deleteUnsentReports se ele desativar.

Também é possível chamar sendUnsentReports e deleteUnsentReports fora do checkForUnsentReportsWithCompletion. Por exemplo, talvez você queira configurar ou desativar permanentemente os relatórios de erros caso seus usuários tenham concedido a você uma aprovação geral ou reprovação para enviar relatórios de erros. Talvez você nunca receba relatórios de erros se o app falhar no início do ciclo de vida.

SDK do Fabric

Swift

class YourClassName: CrashlyticsDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions

    ...
    Crashlytics.sharedInstance().delegate = self
    ...

    return true
  }

  func crashlyticsDidDetectReport(forLastExecution report: CLSReport, completionHandler: @escaping (Bool) -> Void) {
    /* ... handle unsent reports */
  }

  func crashlyticsCanUseBackgroundSessions(_ crashlytics: Crashlytics) -> Bool {
    return true
  }
}

Objective-C

@interface YourClassName <CrashlyticsDelegate> ()
@end

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  ...
  [[Crashlytics sharedInstance] setDelegate:self];
  ...

  return YES;
}

-(void)crashlyticsDidDetectReportForLastExecution:(CLSReport *)report completionHandler:(void (^)(BOOL submit))completionHandler {
  // ... handle unsent reports
}

-(BOOL)crashlyticsCanUseBackgroundSessions:(Crashlytics *)crashlytics {
  return YES;
}

@end

SDK do Firebase Crashlytics

Swift

/* You must set setCrashlyticsCollectionEnabled to false in order to use
checkForUnsentReportsWithCompletion. */

Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(false)

Crashlytics.crashlytics().checkForUnsentReports { hasUnsentReport in
  let hasUserConsent = false
  // ...get user consent.

  if hasUserConsent && hasUnsentReport {
    Crashlytics.crashlytics().sendUnsentReports()
  } else {
    Crashlytics.crashlytics().deleteUnsentReports()
  }
}

// Detect when a crash happens during your app's last run.
if Crashlytics.crashlytics().didCrashDuringPreviousExecution() {
  // ...notify the user.
}

Objective-C

/* You must set setCrashlyticsCollectionEnabled to false in order to use
checkForUnsentReportsWithCompletion. */

[[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:false];

[[FIRCrashlytics crashlytics] checkForUnsentReportsWithCompletion:^(BOOL hasUnsentReports) {
  BOOL hasConsent = false;
  // ...get consent from user.

  if (hasConsent && hasUnsentReports) {
    [[FIRCrashlytics crashlytics] sendUnsentReports];
  } else {
    [[FIRCrashlytics crashlytics] deleteUnsentReports];
  }
}];

// Detect when a crash happens during your app's last run.
if ([[FIRCrashlytics crashlytics] didCrashDuringPreviousExecution]) {
  // ...notify the user.
}

Motivo para a alteração

O novo conjunto de métodos oferece mais controle sobre o comportamento dos relatórios do seu app. Além disso, não é mais necessário configurar o CrashlyticsDelegate antes de inicializar o Crashlytics.

---

O firebase_crashlytics_collection_enabled foi substituído pelo FirebaseCrashlyticsCollectionEnabled.

Quando você define FirebaseCrashlyticsCollectionEnabled como falso no Info.plist, o Crashlytics para de enviar relatórios de erros automaticamente na inicialização. Após a primeira execução do app, você também tem a opção de desativar o relatório de erros. Para isso, defina setCrashlyticsCollectionEnabled como false no Crashlytics.h, mas observe que setCrashlyticsCollectionEnabled modifica essa sinalização.

Para desativar a coleção automática, substitua a chave firebase_crashlytics_collection_enabled no Info.plist:

• Chave: FirebaseCrashlyticsCollectionEnabled

• Valor: false

Após a primeira execução do app, você também tem a opção de desativar a coleta automática. Para isso, adicione o seguinte ao seu Crashlytics.h:

SDK do Firebase Crashlytics

Swift

// setCrashlyticsCollectionEnabled is set to true by default.
Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(false)

Objective-C

// setCrashlyticsCollectionEnabled is set to true by default.
[[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:false];

Motivo para a alteração

Agora você tem mais controle sobre como o Crashlytics processa relatórios de erros não enviados ao desativar os relatórios de erros automáticos. Depois de definir FirebaseCrashlyticsCollectionEnabled como falso, chame checkForUnsentReportsWithCompletion de qualquer lugar no seu app e envie ou exclua relatórios não enviados, dependendo do que o usuário escolher.

---

Agora, o Crashlytics sempre usará sessões em segundo plano.

Antes, era possível definir crashlyticsCanUseBackgroundSessions como falso para desativar as sessões em segundo plano se você não quisesse oferecer suporte a elas no seu app. Agora, crashlyticsCanUseBackgroundSessions está sempre definido como verdadeiro.

Motivo para a alteração

Não oferecemos mais suporte para as versões do iOS anteriores à 7.0 ou do macOS anteriores à OS X 10.9, porque são compatíveis com sessões em segundo plano.

---

O Crashlytics só pode usar dados coletados pelo Google Analytics.

Não é mais possível coletar dados com o Fabric Answers após o upgrade para o SDK do Firebase Crashlytics. Para ver métricas de usuários sem falhas e navegações estruturais, mude para o Google Analytics. Não é possível migrar seus dados históricos do Answers para o Firebase.

Acesse Começar a usar o Google Analytics para saber como adicionar o Google Analytics ao seu aplicativo.

Observação: quando você envia um app que tem o SDK do Firebase Crashlytics instalado, o Fabric Answers deixa de receber dados desse app. Isso também se aplica a versões posteriores do app.

Motivo para a alteração

Agora oferecemos o Google Analytics para ajudar você a conseguir mais informações sobre seus dados de falhas. O Analytics permite que você continue coletando estatísticas para seu app no Console do Firebase.

Próximas etapas

• Teste sua implementação forçando uma falha de teste que enviará um relatório de falha ao painel do Crashlytics no Console do Firebase.

• Para personalizar a configuração do relatório de erros, adicione relatórios de ativação, registros, chaves e rastreamento de erros não fatais.

• Adicione o Google Analytics ao seu aplicativo. Combine o poder do Google Analytics com o Firebase Crashlytics para ver estatísticas de usuários sem falhas no Console do Firebase.