Receber relatórios de erros do Android NDK

Se o app Android tem bibliotecas nativas, é 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 do build do seu app.

Neste guia, você verá como configurar relatórios de erros com o SDK do Firebase Crashlytics para NDK.

Caso esteja em busca de informações para começar a usar o Crashlytics nos seus projetos do Unity, confira Guia para iniciantes do Unity.

Antes de começar

1. Adicione o Firebase ao projeto para Android, caso ainda não tenha feito isso. Caso você não tenha um app Android, faça o download de um app de exemplo.

2. Recomendado: para gerar automaticamente registros de navegação estrutural e entender as ações do usuário que levam a uma falha, um evento não fatal ou um ANR, você precisa para ativar o Google Analytics no seu projeto do Firebase.

   • Se o Google Analytics não estiver ativado no seu projeto do Firebase, ative o Google Analytics na guia Integrações das suas > Configurações do projeto no console do Firebase.

   • Se você estiver criando um novo projeto do Firebase, ative o Google Analytics durante a criação.

3. Verifique se o app tem estas versões mínimas necessárias:

   • Gradle 8.0
   • Plug-in do Android para Gradle 8.1.0
   • Plug-in do Google Services para Gradle 4.4.1

Etapa 1: adicionar ao seu app o SDK do Crashlytics para NDK

No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), adicione a dependência da biblioteca de NDK do Crashlytics para Android. Recomendamos o uso do Firebase Android BoM para controlar o controle de versões da biblioteca.

Para uma experiência ideal com o Crashlytics, recomendamos ativar o Google Analytics no seu projeto do Firebase e adicionar o SDK do Firebase para Google Analytics ao seu app.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.0"))

    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk")
    implementation("com.google.firebase:firebase-analytics")
}

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

(Alternativa) Adicionar dependências das bibliotecas do Firebase sem usar o BoM

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

Se você usa várias bibliotecas do Firebase no app, recomendamos utilizar o BoM para gerenciar as versões delas, porque isso ajuda a garantir a compatibilidade de todas as bibliotecas.

dependencies {
    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk:19.2.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}

Está procurando um módulo de biblioteca específico do Kotlin? A partir de outubro de 2023 (Firebase BoM 32.5.0), os desenvolvedores Kotlin e Java poderão depender do módulo da biblioteca principal. Para mais detalhes, consulte as Perguntas frequentes sobre essa iniciativa.

Etapa 2: adicionar ao seu app o plug-in do Gradle para o Crashlytics

1. No seu arquivo Gradle de nível raiz (do projeto) (<project>/build.gradle.kts ou <project>/build.gradle), adicione o plug-in do Gradle para Crashlytics ao bloco plugins:

   Kotlin

   Você ainda usa a sintaxe buildscript? Saiba como adicionar plug-ins do Firebase usando essa sintaxe.

   plugins {
       // Make sure that you have the AGP plugin 8.1+ dependency
       id("com.android.application") version "8.1.4" apply false
       // ...
   
       // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
       id("com.google.gms.google-services") version "4.4.2" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.2" apply false
   }

   Groovy

   Você ainda usa a sintaxe buildscript? Saiba como adicionar plug-ins do Firebase usando essa sintaxe.

   plugins {
       // Make sure that you have the AGP plugin 8.1+ dependency
       id 'com.android.application' version '8.1.4' apply false
       // ...
   
       // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
       id 'com.google.gms.google-services' version '4.4.2' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.2' apply false
   }

   Seu app usa uma versão antiga do Gradle? Considere fazer o upgrade. Caso contrário, use a v2.9.9 do plug-in do Gradle para Crashlytics.

2. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), adicione o plug-in do Gradle para Crashlytics:

   Kotlin

   plugins {
     id("com.android.application")
     // ...
   
     // Make sure that you have the Google services Gradle plugin
     id("com.google.gms.google-services")
   
     // Add the Crashlytics Gradle plugin
     id("com.google.firebase.crashlytics")
   }

   Groovy

   plugins {
     id 'com.android.application'
     // ...
   
     // Make sure that you have the Google services Gradle plugin
     id 'com.google.gms.google-services'
   
     // Add the Crashlytics Gradle plugin
     id 'com.google.firebase.crashlytics'
   }

Etapa 3: adicionar a extensão do Crashlytics ao seu build

No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), configure a extensão do Crashlytics.

Kotlin

import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension

// ...

android {
  // ...
  buildTypes {
      getByName("release") {
          // Add this extension
          configure<CrashlyticsExtension> {
              // Enable processing and uploading of native symbols to Firebase 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
          }
      }
  }
}

Groovy

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase 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
          }
      }
  }
}

Observação: a distribuição do NDK do Crashlytics inclui binários nativos para todas as arquiteturas aceitas pelo Android NDK. Se o app segmentar um subconjunto específico, será possível usar as divisões da ABI para excluir arquiteturas desnecessárias.

Etapa 4: configurar o upload automático de símbolos nativos

Para produzir stack traces legíveis usando falhas do NDK, o Crashlytics precisa saber sobre os símbolos nos seus binários nativos. O plug-in do Gradle para Crashlytics inclui a tarefa uploadCrashlyticsSymbolFileBUILD_VARIANT para automatizar esse processo.

Note: o Crashlytics funciona com opções alternativas para fazer upload de símbolos, dependendo da configuração e das ferramentas do app, como builds que não são do Gradle.

1. Para acessar a tarefa de upload automático de símbolos, verifique se nativeSymbolUploadEnabled está definido como true no arquivo Gradle do seu módulo no app.

2. Para que os nomes dos métodos apareçam nos stack traces, é necessário invocar explicitamente a tarefa uploadCrashlyticsSymbolFileBUILD_VARIANT após cada build da biblioteca do NDK. Por exemplo:

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT

3. O SDK do Crashlytics para NDK e o plug-in do Crashlytics para Gradle 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 5: forçar uma falha no teste para concluir a configuração

Para concluir a configuração do Crashlytics e conferir os dados iniciais no painel do Crashlytics no console do Firebase, é necessário forçar uma falha de teste.

1. Adicione um código ao app que possa ser usado para forçar uma falha no teste.

   É possível usar o código a seguir no MainActivity do seu app para adicionar um botão que, quando pressionado, causa uma falha. O botão é chamado de "Testar falha".

   Kotlin+KTX

   val crashButton = Button(this)
   crashButton.text = "Test Crash"
   crashButton.setOnClickListener {
      throw RuntimeException("Test Crash") // Force a crash
   }
   
   addContentView(crashButton, ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.MATCH_PARENT,
          ViewGroup.LayoutParams.WRAP_CONTENT))

   Java

   Button crashButton = new Button(this);
   crashButton.setText("Test Crash");
   crashButton.setOnClickListener(new View.OnClickListener() {
      public void onClick(View view) {
          throw new RuntimeException("Test Crash"); // Force a crash
      }
   });
   
   addContentView(crashButton, new ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.MATCH_PARENT,
          ViewGroup.LayoutParams.WRAP_CONTENT));

2. Crie e execute seu app.

3. Force a falha de teste para enviar o primeiro relatório de erros do app:

   1. Abra o app no dispositivo ou emulador de teste.

   2. No app, pressione o botão "Testar falha" que você adicionou usando o código acima.

   3. Depois que o app falhar, reinicie-o para que ele possa enviar o relatório de falhas ao Firebase.

4. Acesse o painel do Crashlytics no console do Firebase para ver a falha do teste.

   Se você já atualizou o console e ainda não está vendo a falha de teste depois de cinco minutos, ative a geração de registros de depuração para ver se o app está enviando relatórios de falha.

Pronto. O Crashlytics já está monitorando seu app em busca de falhas. Você também pode ver e investigar relatórios de erros e estatísticas no painel do Crashlytics.

Próximas etapas

• (Recomendado) Receba ajuda para depurar falhas causadas por erros de memória nativa coletando relatórios do GWP-ASan. Esses erros relacionados à memória podem ser associados à corrupção da memória no seu app, que é a principal causa de vulnerabilidades de segurança. Para aproveitar esse recurso de depuração, seu app precisa ter o GWP-ASan ativado explicitamente e usar o SDK do Crashlytics para NDK mais recente (v18.3.6+ ou a Firebase BoM v31.3.0+).

• 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.

• Faça a integração com o Google Play para filtrar os relatórios de erros do app Android pela faixa do Google Play diretamente no painel do Crashlytics. Isso permite que você configure o painel para monitorar builds específicos.

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.

---

Opções alternativas para o upload de símbolos

O fluxo de trabalho principal na página acima se aplica a builds padrão do Gradle. No entanto, alguns apps usam configurações ou ferramentas diferentes, como um processo de compilação que não seja o Gradle. Nessas situações, as opções a seguir podem ser úteis para o upload dos símbolos.

Opção: fazer upload de símbolos para módulos de biblioteca e dependências externas

Essa opção pode ser útil nas seguintes situações:

• Se você usa um processo personalizado de compilação do NDK no Gradle
• Caso suas bibliotecas nativas sejam criadas em um módulo de recurso/biblioteca ou fornecidas por um terceiro
• Se a tarefa de upload automático de símbolos estiver falhando ou você estiver vendo falhas não simbolizadas no painel

Ver instruções para essa opção

A tarefa de upload de símbolos padrão do Crashlytics presume que você está criando suas bibliotecas nativas como parte do build do Gradle do módulo do app, com ferramentas de build padrão do NDK, como o CMake.

Mas se estiver usando um processo de build personalizado do NDK no Gradle ou se as bibliotecas nativas forem criadas em um módulo de biblioteca/recurso ou fornecidas por terceiros, será necessário especificar explicitamente o caminho para elas com informações ou símbolos de depuração. Para fazer isso, adicione a propriedade unstrippedNativeLibsDir na extensão do Crashlytics ao seu arquivo de build do Gradle.

1. Verifique se você concluiu as tarefas iniciais a seguir do fluxo de trabalho principal nesta página:

   1. O Crashlytics foi ativado no console do Firebase.

   2. O SDK do Crashlytics para NDK e o plug-in do Crashlytics para Gradle foram adicionados.

   3. A extensão do Crashlytics foi adicionada ao build.

   4. Configure o upload automático de símbolos nativos.

2. Para que a tarefa de upload automático de símbolos encontre as informações de símbolos, adicione o conteúdo a seguir ao arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle):

   Kotlin

   import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension
   
   // ...
   
   android {
       // ...
       buildTypes {
           release {
               configure<CrashlyticsExtension> {
                   nativeSymbolUploadEnabled = true
                   unstrippedNativeLibsDir = file("PATH/TO/UNSTRIPPED/DIRECTORY")
               }
           }
       }
   }

   Groovy

   // ...
   
   android {
       // ...
       buildTypes {
           release {
               firebaseCrashlytics {
                   nativeSymbolUploadEnabled true
                   unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY")
               }
           }
       }
   }

   O plug-in do Crashlytics vai buscar as bibliotecas nativas de forma recursiva no diretório especificado com uma extensão .so. Em seguida, o Crashlytics extrai símbolos de depuração de todas essas bibliotecas e faz upload deles nos servidores do Firebase.

   Veja o que pode ser especificado na propriedade unstrippedNativeLibsDir:

   • Qualquer argumento permitido para org.gradle.api.Project#files(Object...), incluindo: java.lang.String, java.io.File ou org.gradle.api.file.FileCollection

   • Vários diretórios para uma única variação de build ao fornecer uma lista ou instância FileCollection

   • (A partir do plug-in do Crashlytics para Gradle v3.0.0) Opção de acumular vários diretórios em produtos individuais e variações de build.

   Ver um exemplo com vários diretórios

     buildTypes {
       release {
         configure<CrashlyticsExtension> {
           nativeSymbolUploadEnabled = true
           unstrippedNativeLibsDir = file("MY/NATIVE/LIBS")
         }
       }
       productFlavors {
         flavorDimensions += "feature"
         create("basic") {
           dimension = "feature"
           // ...
         }
         create("featureX") {
           dimension = "feature"
           configure<CrashlyticsExtension> {
             unstrippedNativeLibsDir = file("MY/FEATURE_X/LIBS")
           }
         }
       }
     }
     

   A tarefa uploadCrashlyticsSymbolFilesBasicRelease só vai fazer upload dos símbolos em MY/NATIVE/LIBS, mas uploadCrashlyticsSymbolFilesFeatureXRelease vai fazer upload dos símbolos em MY/NATIVE/LIBS e também em MY/FEATURE_X/LIBS.

3. Por fim, force uma falha de teste para concluir a configuração do Crashlytics e conferir os dados iniciais no painel do Crashlytics no console do Firebase.

Opção: fazer upload de símbolos para builds que não são do Gradle ou bibliotecas nativas com símbolos inacessíveis

Essa opção pode ser útil nas seguintes situações:

• Se você usa um processo de compilação diferente do Gradle

• Se as bibliotecas nativas com símbolos forem fornecidas de uma maneira que impeça o acesso a elas durante os builds do Gradle

Ver instruções para essa opção

Essa opção exige que você execute um comando da CLI do Firebase ao criar um build de lançamento ou qualquer build com stack traces simbólicos que você quer ver no console do Firebase.

1. Verifique se você concluiu as tarefas iniciais a seguir do fluxo de trabalho principal nesta página:

   1. O Crashlytics foi ativado no console do Firebase.

   2. O SDK do Crashlytics para NDK e o plug-in do Crashlytics para Gradle foram adicionados.

   Com essa opção, você não precisa adicionar a extensão firebaseCrashlytics ou configurar o upload automático de símbolos, porque a CLI do Firebase (próximas etapas a seguir) será usada para gerar e fazer upload dos arquivos de símbolos.

2. Configure seu ambiente e projeto para fazer upload de símbolos:

   1. Siga as instruções para instalar a CLI do Firebase.

      Se você já instalou a CLI, atualize-a para a versão mais recente.

   2. (somente para apps que usam o nível 30 da API do Android ou níveis acima desse) Atualize o modelo AndroidManifest.xml do seu app para desativar a inclusão de tags do ponteiro:

      1. Marque a caixa de seleção de Android Player Settings > Publishing Settings > Build > Custom Main Manifest.

      2. Abra o modelo de manifesto localizado em Assets/Plugins/Android/AndroidManifest.xml.

      3. Adicione o seguinte atributo à tag do aplicativo: <application android:allowNativeHeapPointerTagging="false" ... />

3. Crie o projeto.

4. Faça upload das informações dos símbolos.

   Observação: conclua esta etapa para começar. No futuro, siga essa etapa sempre que criar um build de lançamento ou qualquer build do qual você queira mostrar stack traces simbolizados no console do Firebase.

   Quando o build estiver concluído, gere um arquivo de símbolos compatível com o Crashlytics e faça upload dele para os servidores do Firebase executando o comando a seguir na CLI do Firebase:

   firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS

   • FIREBASE_APP_ID: seu ID do app Android do Firebase (não o nome do pacote)
     Exemplo de ID do app Android do Firebase: 1:567383003300:android:17104a2ced0c9b9b

     Precisa encontrar o ID do app Firebase?

     Veja duas maneiras de encontrar o ID do app Firebase:

     • No arquivo google-services.json, o ID do app é o valor mobilesdk_app_id; ou

     • No console do Firebase, acesse as Configurações do projeto. Role a tela para baixo até o card Seus apps e clique no app Firebase que você quer para encontrar o ID respectivo.

   • PATH/TO/SYMBOLS: o caminho para o arquivo de símbolo gerado pela CLI

     • Exportado para um projeto do Android Studio: PATH/TO/SYMBOLS pode ser qualquer diretório. A CLI do Firebase vai buscar as bibliotecas nativas de forma recursiva no diretório especificado com uma extensão .so.

     • Crie o APK diretamente do Unity: PATH/TO/SYMBOLS é o caminho do arquivo de símbolo compactado, gerado no diretório raiz do projeto quando o build foi concluído (por exemplo: myproject/myapp-1.0-v100.symbols.zip).

   Veja opções avançadas para usar o comando da CLI do Firebase para gerar e fazer upload de arquivos de símbolos

   Flag	Descrição
   --generator=csym	Usa o gerador de arquivos de símbolo legado do cSYM em vez do gerador padrão do Breakpad. Não recomendado. Recomendamos o uso do gerador de arquivos de símbolo padrão do Breakpad.
   --generator=breakpad	Usa o gerador de arquivos de símbolo do Breakpad O padrão para a geração de arquivos de símbolo é o Breakpad. Use essa sinalização apenas se você tiver adicionado symbolGenerator { csym() } à configuração do build e quiser substitui-la para utilizar o Breakpad.
   --dry-run	Gera os arquivos de símbolo, mas não faz upload deles Essa sinalização é útil se você quiser inspecionar o conteúdo dos arquivos enviados.
   --debug	Fornece mais informações de depuração

5. Por fim, force uma falha de teste para concluir a configuração do Crashlytics e conferir os dados iniciais no painel do Crashlytics no console do Firebase.

   Depois de criar seu app como parte do processo de forçar uma falha, execute o comando crashlytics:symbols:upload da CLI do Firebase para fazer upload do arquivo de símbolo.

---