Android NDK kilitlenme raporlarını al

Android uygulamanız yerel kitaplıklar içeriyorsa uygulamanızın derleme yapılandırmasında birkaç küçük güncelleme yaparak Firebase Crashlytics'den itibaren yerel kodunuz için tam yığın izlemelerini ve ayrıntılı kilitlenme raporlarını etkinleştirebilirsiniz.

Bu kılavuzda, NDK için Firebase Crashlytics SDK'sı ile kilitlenme raporlamanın nasıl yapılandırılacağı açıklanmaktadır.

Unity projelerinizi Crashlytics ile kullanmaya nasıl başlayacağınızı öğrenmek istiyorsanız Unity'yi kullanmaya başlama kılavuzuna göz atın.

Başlamadan önce

1. Henüz yapmadıysanız Android projenize Firebase'i ekleyin. Android uygulamanız yoksa örnek uygulama indirebilirsiniz.

2. Önerilir: Kilitlenme, ölümcül olmayan veya ANR etkinliğine yol açan kullanıcı işlemlerini anlamak için ekmek kırıntıları günlüklerini otomatik olarak almak istiyorsanız Firebase projenizde Google Analytics'i etkinleştirmeniz gerekir.

   • Mevcut Firebase projenizde Google Analytics etkin değilse Firebase konsolunda > Proje ayarları bölümündeki Entegrasyonlar sekmesinden Google Analytics'ü etkinleştirebilirsiniz.

   • Yeni bir Firebase projesi oluşturuyorsanız proje oluşturma iş akışı sırasında Google Analytics politikasını etkinleştirin.

3. Uygulamanızın aşağıdaki minimum sürümlere sahip olduğundan emin olun:

   • Gradle 8.0
   • Android Gradle eklentisi 8.1.0
   • Google hizmetleri Gradle eklentisi 4.4.1

1. Adım: NDK için Crashlytics SDK'sını uygulamanıza ekleyin

Modül (uygulama düzeyinde) Gradle dosyanıza (genellikle <project>/<app-module>/build.gradle.kts veya <project>/<app-module>/build.gradle) Android için Crashlytics NDK kitaplığına ait bağımlılık ekleyin. Kitaplık sürümlendirmesini kontrol etmek için Firebase Android BoM simgesini kullanmanızı öneririz.

Crashlytics ile en iyi deneyimi yaşamak için Firebase projenizde Google Analytics'i etkinleştirmenizi ve Google Analytics için Firebase SDK'sını uygulamanıza eklemenizi öneririz.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.9.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")
}

Firebase Android BoM kullanıldığında uygulamanız Firebase Android kitaplıklarının daima uyumlu sürümlerini kullanır.

(Alternatif) BoM

Firebase BoM kullanmamayı seçerseniz her Firebase kitaplık sürümünü bağımlılık satırında belirtmeniz gerekir.

Uygulamanızda birden fazla Firebase kitaplığı kullanıyorsanız kitaplık sürümlerini yönetmek için BoM'ı kullanmanızı önemle tavsiye ederiz. Bu, tüm sürümlerin uyumlu olmasını sağlar.

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.4.0")
    implementation("com.google.firebase:firebase-analytics:22.2.0")
}

Kotlin'e özgü bir kitaplık modülü mü arıyorsunuz? Ekim 2023'ten (Firebase BoM 32.5.0) itibaren hem Kotlin hem de Java geliştiricileri ana kitaplık modülünden yararlanabilir (ayrıntılar için bu girişimle ilgili SSS bölümüne bakın).

2. Adım: Crashlytics Gradle eklentisini uygulamanıza ekleyin

1. Kök düzeyindeki (proje düzeyindeki) Gradle dosyanıza (<project>/build.gradle.kts veya <project>/build.gradle) plugins bloğuna Crashlytics Gradle eklentisini ekleyin:

   Kotlin

   buildscript söz dizimini kullanmaya devam ediyor musunuz? Bu söz dizimini kullanarak Firebase eklentileri eklemeyi öğrenin.

   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.3" apply false
   }

   Groovy

   buildscript söz dizimini kullanmaya devam ediyor musunuz? Bu söz dizimini kullanarak Firebase eklentileri eklemeyi öğrenin.

   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.3' apply false
   }

   Uygulamanız Gradle'ın daha eski bir sürümünü mü kullanıyor? Yükseltme yapmayı düşünün. Aksi takdirde, Crashlytics Gradle eklentisinin 2.9.9 sürümünü kullanmanız gerekir.

2. Modül (uygulama düzeyi) Gradle dosyanıza (genellikle <project>/<app-module>/build.gradle.kts veya <project>/<app-module>/build.gradle) Crashlytics Gradle eklentisini ekleyin:

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

3. Adım: Crashlytics uzantısını derlemenize ekleyin

Modül (uygulama düzeyi) Gradle dosyanızda (genellikle <project>/<app-module>/build.gradle.kts veya <project>/<app-module>/build.gradle) Crashlytics uzantısını yapılandırın.

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

Not: Crashlytics NDK dağıtımı, Android NDK tarafından desteklenen tüm mimariler için yerel ikili dosyaları içerir. Uygulamanız belirli bir alt kümeyi hedefliyorsa gereksiz mimarileri hariç tutmak için ABI bölmelerini kullanabilirsiniz.

4. Adım: Yerel simgelerin otomatik olarak yüklenmesini ayarlayın

NDK kilitlenmelerinden okunabilir yığın izlemeleri oluşturmak için Crashlytics'ün, yerel ikili dosyalarınızdaki semboller hakkında bilgi sahibi olması gerekir. Crashlytics Gradle eklentisi, bu işlemi otomatikleştirmek için uploadCrashlyticsSymbolFileBUILD_VARIANT görevini içerir.

Not: Crashlytics, uygulamanızın yapılandırmasına ve Gradle dışı derlemeler gibi araçlara bağlı olarak simgeleri yüklemek için alternatif seçenekleri destekler.

1. Otomatik simge yükleme görevine erişebilmek için modülünüzün (uygulama düzeyinde) Gradle dosyasında nativeSymbolUploadEnabled değerinin true olarak ayarlandığından emin olun.

2. Yöntem adlarının yığın izlemelerinizde görünmesi için NDK kitaplığınız her derlendikten sonra uploadCrashlyticsSymbolFileBUILD_VARIANT görevini açıkça çağırmanız gerekir. Örneğin:

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT

3. Hem NDK için Crashlytics SDK'sı hem de Crashlytics Gradle eklentisi, yerel paylaşılan nesnelerde GNU derleme kimliğinin bulunmasına bağlıdır.

   Her ikili dosyada readelf -n çalıştırarak bu kimliğin varlığını doğrulayabilirsiniz. Derleme kimliği yoksa sorunu düzeltmek için derleme sisteminizin işaretlerine -Wl,--build-id ekleyin.

5. adım: Kurulumu tamamlamak için test kilitlenmesini zorlama

Crashlytics'ü ayarlamayı tamamlamak ve Firebase konsolunun Crashlytics kontrol panelinde ilk verileri görmek için test kilitlenmesini zorlamanız gerekir.

1. Uygulamanıza, test amaçlı kilitlenme yapmak için kullanabileceğiniz kod ekleyin.

   Uygulamanıza, basıldığında kilitlenme oluşturan bir düğme eklemek için uygulamanızın MainActivity bölümünde aşağıdaki kodu kullanabilirsiniz. Düğmenin etiketi "Test Kilitlenmesi"dir.

   Kotlin

   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. Uygulamanızı derleyip çalıştırın.

3. Uygulamanızın ilk kilitlenme raporunu göndermek için test kilitlenmesini zorlama:

   1. Uygulamanızı test cihazınızdan veya emülatörden açın.

   2. Uygulamanızda, yukarıdaki kodu kullanarak eklediğiniz "Kilitlenmeyi Test Et" düğmesine basın.

   3. Uygulamanız kilitlendikten sonra, kilitlenme raporunu Firebase'e gönderebilmesi için uygulamanızı yeniden başlatın.

4. Test kilitlenmenizi görmek için Firebase konsolunun Crashlytics kontrol paneline gidin.

   Konsolu yeniledikten sonra beş dakika geçmesine rağmen testin kilitlendiğini görmüyorsanız uygulamanızın kilitlenme raporu gönderip göndermediğini görmek için hata ayıklama günlük kaydını etkinleştirin.

Hepsi bu kadar. Crashlytics artık uygulamanızı kilitlenmeler açısından izliyor. Kilitlenme raporlarını ve istatistiklerini Crashlytics kontrol panelinde görüntüleyip inceleyebilirsiniz.

Sonraki adımlar

• (Önerilen) GWP-ASan raporlarını toplayarak yerel bellek hatalarından kaynaklanan kilitlenmelerde hata ayıklama konusunda yardım alın. Bellekle ilgili bu hatalar, uygulamanızdaki bellek bozulmasıyla ilişkilendirilebilir. Bu durum, uygulama güvenlik açıklarının başlıca nedenidir. Bu hata ayıklama özelliğinden yararlanmak için uygulamanızda GWP-ASan'ın açıkça etkinleştirildiğinden ve NDK için en son Crashlytics SDK'sının (v18.3.6 veya üzeri ya da Firebase BoM v31.3.0 veya üzeri) kullanıldığından emin olun.

• Etkinleştirme raporları, günlükler, anahtarlar ve ölümcül olmayan hataların izlenmesini ekleyerek kilitlenme raporu ayarlarınızı özelleştirin.

• Android uygulamanızın kilitlenme raporlarını doğrudan Crashlytics kontrol panelinde Google Play kanalına göre filtreleyebilmek için Google Play ile entegrasyon yapın. Bu sayede kontrol panelinizi belirli derlemelere daha iyi odaklayabilirsiniz.

Sorun giderme

Firebase konsolunda ve logcat'te farklı yığın izlemeleri görüyorsanız Sorun giderme kılavuzuna bakın.

---

Simge yüklemeyle ilgili alternatif seçenekler

Yukarıdaki bu sayfada yer alan ana iş akışı, standart Gradle derlemeleri için geçerlidir. Ancak bazı uygulamalar farklı bir yapılandırma veya araç kullanır (ör. Gradle dışında bir derleme işlemi). Bu durumlarda, sembolleri başarıyla yüklemek için aşağıdaki seçeneklerden yararlanabilirsiniz.

Seçenek: Kitaplık modülleri ve harici bağımlılıklara yönelik simgeleri yükleme

Bu seçenek aşağıdaki durumlarda faydalı olabilir:

• Gradle'de özelleştirilmiş bir NDK derleme süreci kullanıyorsanız
• Yerel kitaplıklarınız bir kitaplık/özellik modülünde oluşturulduysa veya üçüncü taraf tarafından sağlandıysa
• Otomatik simge yükleme görevi başarısız oluyorsa veya kontrol panelinde simgesiz kilitlenmeler görüyorsanız

Bu seçenekle ilgili talimatları görüntüleme

Standart Crashlytics simge yükleme görevi, yerel kitaplıklarınızı CMake gibi standart NDK derleme araçlarını kullanarak uygulama modülünüzün Gradle derlemesi kapsamında oluşturduğunuzu varsayar.

Ancak Gradle'de özelleştirilmiş bir NDK derleme işlemi kullanıyorsanız veya yerel kitaplıklarınız bir kitaplık/özellik modülünde derlenmişse ya da üçüncü taraflarca sağlanmışsa sadeleştirilmemiş kitaplıklarınızın yolunu açıkça belirtmeniz gerekebilir. Bunu yapmak için Gradle derleme dosyanızdaki Crashlytics uzantısına unstrippedNativeLibsDir mülkünü ekleyebilirsiniz.

1. Bu sayfanın başlarındaki ana iş akışında aşağıdaki ilk görevleri tamamladığınızdan emin olun:

   1. Firebase konsolunda Crashlytics etkinleştirildi.

   2. NDK için Crashlytics SDK'sı ve Crashlytics Gradle eklentisi eklendi.

   3. Crashlytics uzantısını derlemenize ekleyin.

   4. Yerel sembollerin otomatik olarak yüklenmesini ayarlayın.

2. Otomatik simge yükleme görevinin simge bilgilerinizi bulabilmesi için modül (uygulama düzeyi) Gradle dosyanıza (genellikle <project>/<app-module>/build.gradle.kts veya <project>/<app-module>/build.gradle) aşağıdakileri ekleyin:

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

   Crashlytics eklentisi, belirtilen dizini .so uzantılı yerel kitaplıklar için yinelemeli olarak arar. Crashlytics daha sonra bu tür tüm kitaplıklardan hata ayıklama simgelerini ayıklayıp Firebase sunucularına yükler.

   unstrippedNativeLibsDir mülkünde şunları belirtebilirsiniz:

   • Aşağıdakiler dahil olmak üzere org.gradle.api.Project#files(Object...) için izin verilen tüm bağımsız değişkenler: java.lang.String, java.io.File veya org.gradle.api.file.FileCollection

   • Liste veya FileCollection örneği sağlayarak tek bir derleme çeşidi için birden fazla dizin

   • (Crashlytics Gradle eklentisi 3.0.0 sürümünden itibaren) Birden fazla dizini tek bir üründe toplayın ve derleme varyantları oluşturun.

   Birden çok dizin içeren bir örnek görüntüleme

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

   uploadCrashlyticsSymbolFilesBasicRelease görevi yalnızca MY/NATIVE/LIBS'daki simgeleri yükler ancak uploadCrashlyticsSymbolFilesFeatureXRelease hem MY/NATIVE/LIBS hem de MY/FEATURE_X/LIBS'daki simgeleri yükler.

3. Son olarak, Crashlytics kurulumunu tamamlamak ve Firebase konsolunun Crashlytics kontrol panelinde ilk verileri görmek için test kilitlenmesini zorla.

Seçenek: Gradle dışı derlemeler veya erişilemeyen, sarmalayıcısı kaldırılmamış yerel kitaplıklar için simgeleri yükleme

Bu seçenek aşağıdaki durumlarda faydalı olabilir:

• Gradle dışında bir derleme süreci kullanıyorsanız

• Çıplak yerel kitaplıklarınız Gradle derlemeleri sırasında erişilemeyecek şekilde sağlanıyorsa

Bu seçenekle ilgili talimatları görüntüleme

Bu seçenek, Firebase konsolunda sembolize edilmiş yığın izlemelerini görmek istediğiniz bir sürüm derlemesi veya herhangi bir derleme oluşturduğunuzda bir Firebase CLI komutu çalıştırmanızı gerektirir.

1. Bu sayfanın başlarındaki ana iş akışında aşağıdaki ilk görevleri tamamladığınızdan emin olun:

   1. Firebase konsolunda Crashlytics etkinleştirildi.

   2. NDK için Crashlytics SDK'sı ve Crashlytics Gradle eklentisi eklendi.

   Bu seçenekte, simge dosyalarınızı oluşturmak ve yüklemek için Firebase CLI'yi (aşağıdaki sonraki adımlar) kullanacağınızdan firebaseCrashlyticsuzantı eklemenize veya otomatik simge yüklemeyi ayarlamanıza gerek olmadığını unutmayın.

2. Ortamınızı ve projenizi simge yükleme için ayarlayın:

   1. Firebase KSA'yı yükleme talimatlarını uygulayın.

      CLI'yi daha önce yüklediyseniz en son sürüme güncellediğinizden emin olun.

   2. (yalnızca Android API düzeyi 30 ve sonraki sürümleri kullanan uygulamalar için) İşaretçi etiketlemeyi devre dışı bırakmak üzere uygulamanızın AndroidManifest.xml şablonunu güncelleyin:

      1. Android Oynatıcı Ayarları > Yayınlama Ayarları > Derleme > Özel Ana Manifest kutusunu işaretleyin.

      2. Assets/Plugins/Android/AndroidManifest.xml adresindeki manifest şablonunu açın.

      3. Uygulama etiketine aşağıdaki özelliği ekleyin: <application android:allowNativeHeapPointerTagging="false" ... />

3. Projenizi oluşturun.

4. Simge bilgilerinizi yükleyin.

   Not: Başlamak için bu adımı tamamlayın. Ardından, gelecekte bir sürüm derlemesi veya Firebase konsolunda sembolize edilmiş yığın izlemelerini görmek istediğiniz herhangi bir derleme oluşturduğunuzda bu adımı tamamlayın.

   Derlemeniz tamamlandıktan sonra Crashlytics ile uyumlu bir simge dosyası oluşturun ve aşağıdaki Firebase CLI komutunu çalıştırarak Firebase sunucularına yükleyin:

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

   • FIREBASE_APP_ID: Firebase Android uygulama kimliğiniz (paket adınız değil)
     Firebase Android uygulama kimliği örneği: 1:567383003300:android:17104a2ced0c9b9b

     Firebase uygulama kimliğinizi bulmanız mı gerekiyor?

     Firebase uygulama kimliğinizi bulmanın iki yolu vardır:

     • google-services.json dosyanızdaki uygulama kimliğiniz mobilesdk_app_id değeridir veya

     • Firebase konsolunda Proje ayarlarınıza gidin. Uygulamalarınız kartına gidin ve uygulama kimliğini bulmak için istediğiniz Firebase uygulamasını tıklayın.

   • PATH/TO/SYMBOLS: KSA tarafından oluşturulan simge dosyasının yolu

     • Android Studio projesine aktarılır. PATH/TO/SYMBOLS herhangi bir dizin olabilir. Firebase CLI, belirtilen dizini .so uzantılı yerel kitaplıklar için yinelemeli olarak arar.

     • APK doğrudan Unity'den derlendi. PATH/TO/SYMBOLS, derlemeniz tamamlandığında proje kök dizininde oluşturulan sıkıştırılmış simge dosyasının yoludur (ör. myproject/myapp-1.0-v100.symbols.zip).

   Simge dosyası oluşturma ve yükleme için Firebase CLI komutunu kullanmayla ilgili gelişmiş seçenekleri görüntüleme

   İşaret	Açıklama
   --generator=csym	Varsayılan Breakpad oluşturucu yerine eski cSYM simge dosyası oluşturucuyu kullanır Kullanılması önerilmez. Varsayılan Breakpad simge dosyası oluşturucuyu kullanmanızı öneririz.
   --generator=breakpad	Breakpad sembol dosyası oluşturucuyu kullanır Simge dosyası oluşturma işleminin varsayılan olarak Breakpad olduğunu unutmayın. Bu işareti yalnızca derleme yapılandırmanıza symbolGenerator { csym() } eklediyseniz ve bunun yerine Breakpad kullanmak için bu işareti geçersiz kılmak istiyorsanız kullanın.
   --dry-run	Simge dosyalarını oluşturur ancak yüklemez Bu işaret, gönderilen dosyaların içeriğini incelemek isterseniz kullanışlıdır.
   --debug	Ek hata ayıklama bilgileri sağlar

5. Son olarak, Crashlytics kurulumunu tamamlamak ve Firebase konsolunun Crashlytics kontrol panelinde ilk verileri görmek için test kilitlenmesini zorla.

   Kilitlenmeyi zorlama kapsamında uygulamanızı oluşturduktan sonra simge dosyanızı yüklemek için Firebase CLI crashlytics:symbols:upload komutunu çalıştırdığınızdan emin olun.

---