O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Receber relatórios de erros do Android NDK

Se o app Android tiver bibliotecas nativas, será possível ativar stack traces completos e relatórios detalhados de falhas para seu código nativo no Firebase Crashlytics com algumas pequenas atualizações na configuração da compilação do seu app. Este guia descreve como configurar relatórios de erros com o novo SDK do Firebase Crashlytics.

Antes de começar

Para começar, configure o Crashlytics.

  1. Como parte da Etapa 2 (Adicionar o Firebase Crashlytics ao seu app), verifique se o app está usando o plug-in do Gradle para Crashlytics v2.4.0+, que permite fazer o upload de símbolos usando apenas seus binários com informações de depuração para gerar falhas.

Etapa 1: atualizar a configuração do Gradle

No arquivo build.gradle do app, declare a dependência de ambiente de execução do Crashlytics NDK:

Java

apply plugin: 'com.android.application'
apply plugin: 'com.google.firebase.crashlytics'

dependencies {
  // ...

  // Import the BoM for the Firebase platform
  implementation platform('com.google.firebase:firebase-bom:28.4.0')

  // Declare the dependency for the Firebase Crashlytics NDK library.
  // If you previously declared the Firebase Crashlytics dependency, replace it.
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation 'com.google.firebase:firebase-crashlytics'
  implementation 'com.google.firebase:firebase-crashlytics-ndk'
  implementation 'com.google.firebase:firebase-analytics'
}

// …
android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Crashlytics servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

Com a BoM do Firebase para Android, seu app sempre usará versões compatíveis das bibliotecas do Firebase para Android.

(Alternativa) Declare as dependências das bibliotecas do Firebase sem usar a BoM.

Se você preferir não usar a BoM do Firebase, especifique a versão de cada biblioteca do Firebase na linha de dependência correspondente.

Caso você use várias bibliotecas do Firebase no seu app, recomendamos usar a BoM para gerenciar as versões delas e garantir a compatibilidade de todas..

  dependencies {
      // Declare the dependency for the Firebase Crashlytics NDK library.
      // If you previously declared the Firebase Crashlytics dependency, replace it.
      // When NOT using the BoM, you must specify versions in Firebase library dependencies
      implementation 'com.google.firebase:firebase-crashlytics:18.2.1'
      implementation 'com.google.firebase:firebase-crashlytics-ndk:18.2.1'
      implementation 'com.google.firebase:firebase-analytics:19.0.1'
  }
  

Kotlin+KTX

apply plugin: 'com.android.application'
apply plugin: 'com.google.firebase.crashlytics'

dependencies {
  // ...

  // Import the BoM for the Firebase platform
  implementation platform('com.google.firebase:firebase-bom:28.4.0')

  // Declare the dependency for the Firebase Crashlytics NDK library.
  // If you previously declared the Firebase Crashlytics dependency, replace it.
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation 'com.google.firebase:firebase-crashlytics-ktx'
  implementation 'com.google.firebase:firebase-crashlytics-ndk'
  implementation 'com.google.firebase:firebase-analytics-ktx'
}

// …
android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Crashlytics servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

Com a BoM do Firebase para Android, seu app sempre usará versões compatíveis das bibliotecas do Firebase para Android.

(Alternativa) Declare as dependências das bibliotecas do Firebase sem usar a BoM.

Se você preferir não usar a BoM do Firebase, especifique a versão de cada biblioteca do Firebase na linha de dependência correspondente.

Caso você use várias bibliotecas do Firebase no seu app, recomendamos usar a BoM para gerenciar as versões delas e garantir a compatibilidade de todas..

  dependencies {
      // Declare the dependency for the Firebase Crashlytics NDK library.
      // If you previously declared the Firebase Crashlytics dependency, replace it.
      // When NOT using the BoM, you must specify versions in Firebase library dependencies
      implementation 'com.google.firebase:firebase-crashlytics-ktx:18.2.1'
      implementation 'com.google.firebase:firebase-crashlytics-ndk:18.2.1'
      implementation 'com.google.firebase:firebase-analytics-ktx:19.0.1'
  }
  

Obrigatório para o Crashlytics NDK versão 17.3.0: se o app usar o targetSdkLevel 30 ou versão mais recente, você também precisará desativar o recurso Pointer Tagging no app adicionando o seguinte ao seu AndroidManifest.xml:

<application android:allowNativeHeapPointerTagging="false">
...
</application>

Para ver mais informações, consulte Suporte ao desenvolvedor para o Pointer Tagging.

Etapa 2: ativar o upload de símbolos nativos

Para produzir stack traces legíveis com base nas falhas do NDK, o Crashlytics precisa saber sobre os símbolos nos seus binários nativos. Nosso plug-in do Gradle inclui a tarefa uploadCrashlyticsSymbolFileBUILD_VARIANT para automatizar esse processo. Para acessar essa tarefa, verifique se nativeSymbolUploadEnabled está definido como verdadeiro.

Para que os nomes dos métodos apareçam nos stack traces, é necessário invocar explicitamente a tarefa uploadCrashlyticsSymbolFileBUILD_VARIANT após cada compilação da sua biblioteca do NDK. Exemplo:

>./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

O Crashlytics NDK v17.3.0+ e o plug-in do Gradle v2.4.1+ dependem da presença do ID de build do GNU nos objetos compartilhados nativos. Verifique a presença desse ID executando readelf -n em cada binário. Se o ID do build estiver ausente, adicione -Wl,--build-id às sinalizações do sistema de build para corrigir o problema.

Etapa 3 (opcional): fazer upload de símbolos para módulos de biblioteca e dependências externas

Nossa tarefa de upload de símbolos pressupõe que você esteja criando suas bibliotecas nativas como parte da compilação do Gradle, usando ferramentas de compilação padrão do NDK, como o CMake. Se você estiver usando um processo personalizado de compilação do NDK no Gradle ou se suas bibliotecas nativas forem criadas em um módulo de biblioteca/recurso ou fornecidas por terceiros, talvez seja necessário especificar explicitamente o caminho para suas bibliotecas com informações de depuração. A extensão firebaseCrashlytics fornece a propriedade unstrippedNativeLibsDir para fazer isso.

Adicione o seguinte ao seu arquivo build.gradle no nível do app:

// …
android {
    // ...
    buildTypes {
        release {
            firebaseCrashlytics {
                nativeSymbolUploadEnabled true
                unstrippedNativeLibsDir file("path/to/unstripped/dir")
            }
        }
    }
}

O plug-in do Crashlytics procurará bibliotecas nativas com uma extensão .so no diretório especificado e em todos os subdiretórios dele. Depois disso, o Crashlytics extrairá os símbolos de depuração de todas essas bibliotecas e fará upload deles para os servidores do Firebase.

A propriedade unstrippedNativeLibsDir aceita qualquer argumento permitido para org.gradle.api.Project#files(Object...), incluindo java.lang.String, java.io.File e org.gradle.api.file.FileCollection. É possível especificar vários diretórios para uma única variação de build, basta fornecer uma instância FileCollection ou uma lista.

Etapa 4 (opcional): personalizar relatórios de erros do NDK

Como alternativa, é possível incluir o cabeçalho crashlytics.h no código C++ para adicionar metadados aos relatórios de erros do NDK, como registros, chaves personalizadas e IDs de usuário. crashlytics.h está disponível como uma biblioteca de C++ somente de cabeçalho no Repositório do GitHub do SDK do Firebase para Android. Leia os comentários no arquivo de cabeçalho para ver instruções sobre como usar as APIs de C++ do NDK.

Etapa 5 (opcional): ativar o arquivo de símbolo do Breakpad para simbolização

O plug-in do Gradle para o Crashlytics oferece as seguintes funcionalidades:

  • Processa seus binários nativos com símbolos para gerar arquivos de símbolo
  • Faz upload desses arquivos de símbolo para nossos servidores para que eles sejam usados posteriormente ao simbolizar falhas nativas

O plug-in do Gradle para o Crashlytics é compatível com dois tipos de formatos de arquivos de símbolo:
o do Crashlytics (cSYM) e o do Breakpad.

Um arquivo de símbolo gerado pelo Breakpad contém mais informações do que um gerado pelo Crashlytics, incluindo as informações do frame de chamada (CFI, na sigla em inglês), que são usadas no processo de análise para ajudar a calcular frames de pilha. O uso das CFI resultará em stack traces de maior fidelidade, especialmente para aplicativos altamente otimizados, como apps de mídia e jogos.

Há duas formas de ativar o gerador de arquivos de símbolo baseado no Breakpad:

  • Opção 1: ativar usando a extensão firebaseCrashlytics no seu arquivo build.gradle

    Adicione o seguinte ao seu arquivo build.gradle no nível do app:

    android {
      // ...
      buildTypes {
        // ...
        release {
          // ...
          firebaseCrashlytics {
            // existing; required for either symbol file generator
            nativeSymbolUploadEnabled true
            // Add this optional new block to specify breakpad() or csym()
            symbolGenerator {
               breakpad()
            }
          }
        }
      }
    }
    

    Para voltar ao gerador padrão de arquivos de símbolo do Crashlytics, faça uma das seguintes ações:

    • Omita o bloco symbolGenerator inteiramente, já que o plug-in usa o gerador de arquivos de símbolo do Crashlytics por padrão.

    • Mantenha o bloco, mas altere breakpad() para csym().

  • Opção 2: ativar usando uma linha de propriedade no arquivo do Gradle

    É possível usar a propriedade com.google.firebase.crashlytics.symbolGenerator para controlar qual gerador de arquivos de símbolo será usado. Os valores válidos para a propriedade são breakpad ou csym. Se não for especificado, o padrão atual será equivalente a csym, embora isso possa mudar nas versões futuras.

    É possível atualizar o arquivo de propriedades do Gradle manualmente ou atualizar o arquivo usando a linha de comando. Por exemplo, para ativar o gerador de arquivos de símbolo do Breakpad, especifique o valor de breakpad conforme mostrado no comando a seguir:

    ./gradlew -Pcom.google.firebase.crashlytics.symbolGenerator=breakpad \
    app:assembleRelease app:uploadCrashlyticsSymbolFileRelease
    

Etapa 6: ver os relatórios de falhas

Verifique se o Crashlytics está informando corretamente as falhas do NDK ao criar seu app, fazer upload de símbolos e forçar uma falha nativa. Será necessário reiniciar o app depois que ele apresentar falha para que o Crashlytics envie o relatório. Você verá a falha no Console do Firebase em alguns minutos.

Solução de problemas

Se você estiver vendo stack traces diferentes no Console do Firebase e no logcat, consulte o Guia de solução de problemas.