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

Se você estiver procurando informações para começar a usar o Crashlytics nos seus projetos do Unity, confira este guia para iniciantes.

Antes de começar

Adicione o Firebase ao projeto para Android, caso ainda não tenha feito isso. Se você não tiver um app Android, faça o download de um app de exemplo.
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.
- Caso seu projeto do Firebase não tenha o Google Analytics ativado, faça a ativação na guia Integrações das suas > Configurações do projeto no Console do Firebase.
- Se estiver criando um novo projeto do Firebase, ative o Google Analytics durante o fluxo de trabalho de criação do projeto.
Verifique se o app tem as 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 do Crashlytics NDK para Android. Para gerenciar o controle de versões das bibliotecas, recomendamos usar a BoM do Firebase para Android.

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

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

    // 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 BoM do Firebase para Android, 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 a BoM

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

Se você usa várias bibliotecas do Firebase no seu app, recomendamos utilizar a 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.0.2")
    implementation("com.google.firebase:firebase-analytics:22.0.2")
}

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

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

No arquivo Gradle no nível raiz (para envolvidos no 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
}

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
          }
      }
  }
}

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.

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.
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. Exemplo:
```
>./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT
```
O SDK do Crashlytics para NDK e o plug-in do Gradle para Crashlytics dependem da presença do ID do 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 ver os dados iniciais no painel do Console do Firebase, é necessário forçar uma falha de teste.

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));

Crie e execute seu app.
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.
Acesse o painel do Crashlytics no Console do Firebase para ver a falha do teste.

Se você atualizou o console e ainda não consegue ver a falha de teste após 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 agora está monitorando seu app em busca de falhas. Você também pode conferir 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 BoM do Firebase 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 verificar versões específicas.

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, vai 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.

Verifique se você concluiu as tarefas iniciais a seguir do fluxo de trabalho principal nesta página:
1. Ative o Crashlytics no Console do Firebase.
2. O SDK do Crashlytics para NDK e o plug-in do Gradle para Crashlytics foram adicionados.
3. A extensão foi adicionada ao build.
4. Configure o upload automático de símbolos nativos.
Para que a tarefa de upload automático de símbolos encontre as informações de símbolos, adicione o seguinte 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 buscará as bibliotecas nativas de maneira 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 é possível especificar 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 Gradle para Crashlytics v3.0.0) 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 ambos MY/NATIVE/LIBS e MY/FEATURE_X/LIBS.
Por fim, force uma falha de teste para concluir a configuração do Crashlytics e ver os dados iniciais no painel do Console do Firebase.

Opção: fazer upload de símbolos para builds que não sejam 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.

Verifique se você concluiu as tarefas iniciais a seguir do fluxo de trabalho principal nesta página:
1. Ative o Crashlytics no Console do Firebase.
2. O SDK do Crashlytics para NDK e o plug-in do Gradle para Crashlytics 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.
Configure seu ambiente e projeto para fazer upload do símbolo:
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" ... />
Crie o projeto.

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

Quando o build estiver concluído, gere um arquivo de símbolo compatível com o Crashlytics e faça upload dele para os servidores do Firebase. Para isso, execute o seguinte comando da 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.
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 buscará as bibliotecas nativas de maneira 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 informações de depuração adicionais

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

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