Memahami error pada game Unity menggunakan fitur Crashlytics lanjutan

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara menggunakan fitur lanjutan Crashlytics yang akan memberi Anda visibilitas yang lebih baik terhadap error dan situasi yang mungkin menyebabkannya.

Anda akan menambahkan fungsi baru ke game contoh, MechaHamster: Tingkatkan Kemampuan dengan Edisi Firebase. Game contoh ini adalah versi baru dari game Firebase klasik MechaHamster yang menghapus sebagian besar fungsi Firebase bawaannya, sehingga memberi Anda kesempatan untuk menerapkan penggunaan baru Firebase di tempatnya.

Anda akan menambahkan menu debug ke game. Menu debug ini memanggil metode yang akan Anda buat dan memungkinkan Anda menggunakan berbagai fungsi Crashlytics. Metode ini akan menunjukkan cara memberi anotasi pada laporan error otomatis dengan kunci kustom, log kustom, error non-fatal, dan lainnya.

Setelah membangun game, Anda akan menggunakan menu debug, dan memeriksa hasilnya untuk memahami tampilan unik yang mereka berikan tentang cara game Anda berjalan di alam liar.

Yang akan Anda pelajari

• Jenis error yang otomatis ditangkap oleh Crashlytics.
• Error tambahan yang dapat dicatat secara sengaja.
• Cara menambahkan informasi lebih lanjut ke error ini agar lebih mudah dipahami.

Yang Anda butuhkan

• Unity (Versi Minimum yang Direkomendasikan 2019+) dengan salah satu atau kedua hal berikut:
  • Dukungan Build iOS
  • Dukungan Build Android
• (Khusus Android) Firebase CLI (digunakan untuk mengupload simbol untuk laporan error)
  • Ikuti petunjuk untuk menginstal Firebase CLI.
    Jika Anda sudah menginstal CLI, pastikan untuk mengupdate ke versi terbarunya.

2. Menyiapkan lingkungan pengembangan

Bagian berikut menjelaskan cara mendownload kode Level Up with Firebase dan membukanya di Unity.

Perhatikan bahwa game contoh Level Up with Firebase ini digunakan oleh beberapa codelab Firebase + Unity lainnya, jadi Anda mungkin telah menyelesaikan tugas-tugas di bagian ini. Jika ya, Anda dapat langsung membuka langkah terakhir di halaman ini: "Tambahkan Firebase SDK untuk Unity".

Mendownload kode

Clone repositori GitHub codelab ini dari command line:

git clone https://github.com/firebase/level-up-with-firebase.git

Atau, jika Anda belum menginstal git, Anda dapat mendownload repositori sebagai file ZIP.

Buka Level Up with Firebase di editor Unity

1. Luncurkan Unity Hub dan, dari tab Projects, klik panah drop-down di samping Open.
2. Klik Tambahkan project dari disk.
3. Buka direktori yang berisi kode, lalu klik OK.
4. Jika diminta, pilih versi editor Unity yang akan digunakan dan platform target Anda (Android atau iOS).
5. Klik nama project, level-up-with-firebase, dan project akan terbuka di editor Unity.
6. Jika editor Anda tidak membukanya secara otomatis, buka MainGameScene di Assets > Hamster di tab Project pada Unity Editor.
   

Untuk mengetahui informasi selengkapnya tentang cara menginstal dan menggunakan Unity, lihat Bekerja di Unity.

3. Menambahkan Firebase ke project Unity

Membuat project Firebase

1. Login ke Firebase console menggunakan Akun Google Anda.
2. Klik tombol untuk membuat project baru, lalu masukkan nama project (misalnya, Mechahamster Codelab).
   

   Nama project ini digunakan sebagai nama tampilan di antarmuka Firebase, dan Firebase akan otomatis membuat project ID unik berdasarkan nama project ini. Perhatikan bahwa Anda dapat mengklik ikon Edit sekarang untuk menetapkan project ID pilihan Anda, tetapi Anda tidak dapat mengubah ID ini setelah project dibuat.

   Ingat project ID Anda karena Anda akan memerlukannya nanti untuk mengidentifikasi project Firebase Anda di Firebase CLI. Jika lupa ID, Anda dapat menemukannya nanti di Setelan Project.

3. Klik Lanjutkan.
4. Jika diminta, tinjau dan setujui persyaratan Firebase, lalu klik Continue.
5. (Opsional) Aktifkan bantuan AI di Firebase console (disebut "Gemini di Firebase").
6. Untuk codelab ini, Anda memerlukan Google Analytics agar dapat menggunakan produk Firebase secara optimal. Jadi, tetap aktifkan opsi Google Analytics. Ikuti petunjuk di layar untuk menyiapkan Google Analytics.
7. Klik Buat project, tunggu hingga project Anda disediakan, lalu klik Lanjutkan.

Mendaftarkan aplikasi ke Firebase

1. Masih di Firebase console, dari bagian tengah halaman ringkasan project, klik ikon Unity untuk meluncurkan alur kerja penyiapan atau, jika Anda sudah menambahkan aplikasi ke project Firebase, klik Tambahkan aplikasi untuk menampilkan opsi platform.
2. Pilih untuk mendaftarkan target build Apple (iOS) dan Android.
3. Masukkan ID khusus platform project Unity Anda. Untuk codelab ini, masukkan yang berikut:
   • Untuk Apple (iOS): Masukkan com.google.firebase.level-up di kolom ID paket iOS.
   • Untuk Android: Masukkan com.google.firebase.level_up di kolom Nama paket Android.

   Penting: ID paket iOS dan nama paket Android di atas berbeda. ID iOS tidak valid untuk Android dan sebaliknya. Pastikan Anda menggunakan ID yang benar.

4. (Opsional) Masukkan nama panggilan khusus platform project Unity Anda.
5. Klik Daftarkan aplikasi, lalu lanjutkan ke bagian Download file konfigurasi.

Menambahkan file konfigurasi Firebase

Setelah mengklik Register app, Anda akan diminta untuk mendownload dua file konfigurasi (satu file konfigurasi untuk setiap target build). Project Unity Anda memerlukan metadata Firebase dalam file ini untuk terhubung dengan Firebase.

1. Download kedua file konfigurasi yang tersedia:
   • Untuk Apple (iOS): Download GoogleService-Info.plist.
   • Untuk Android: Download google-services.json.
2. Buka jendela Project untuk project Unity Anda, lalu pindahkan kedua file konfigurasi ke folder Assets.

   Penting: Meskipun Anda berencana membangun hanya iOS atau Android, Anda harus mendownload kedua file dan menambahkannya ke project Anda.

3. Kembali ke Firebase console, di alur kerja penyiapan, klik Next dan lanjutkan ke Menambahkan Firebase SDK untuk Unity.

Catatan: Anda selalu dapat mendownload ulang file ini di lain waktu dengan membuka setelan umum project, men-scroll ke bawah ke bagian Aplikasi Anda, lalu mengklik tombol download untuk file konfigurasi yang diinginkan.

Menambahkan Firebase SDK untuk Unity

1. Klik Download Firebase Unity SDK di Firebase console.

   Catatan: SDK ini mungkin memerlukan waktu beberapa saat untuk didownload. Ambil kopi atau teh - tetap terhidrasi, teman-teman.

2. Ekstrak SDK di tempat yang mudah diakses.
3. Pada Project Unity yang terbuka, buka Assets > Import Package > Custom Package.
4. Dalam dialog Import package, buka direktori yang berisi SDK yang telah diekstrak, pilih FirebaseAnalytics.unitypackage, lalu klik Open.
5. Dari dialog Import Unity Package yang muncul, klik Import.
6. Ulangi langkah sebelumnya untuk mengimpor FirebaseCrashlytics.unitypackage.
7. Kembali ke Firebase console dan, di alur kerja penyiapan, klik Next.

Untuk mengetahui informasi selengkapnya tentang cara menambahkan Firebase SDK ke project Unity, lihat Opsi penginstalan Unity tambahan.

4. Menyiapkan Crashlytics di project Unity Anda

Untuk menggunakan Crashlytics di project Unity, Anda harus melakukan beberapa langkah penyiapan lagi. Tentu saja, Anda harus melakukan inisialisasi SDK. Selain itu, Anda harus mengupload simbol agar dapat melihat stacktrace yang disimbolkan di Firebase console, dan Anda harus memaksa error pengujian untuk memastikan bahwa Firebase mendapatkan peristiwa error Anda.

Menginisialisasi Crashlytics SDK

1. Di Assets/Hamster/Scripts/MainGame.cs, tambahkan pernyataan using berikut:

   using Firebase.Crashlytics;
   using Firebase.Extensions;
   

   Modul pertama memungkinkan Anda menggunakan metode dari Crashlytics SDK dan modul kedua berisi beberapa ekstensi ke C# Tasks API. Tanpa pernyataan both using, kode berikut tidak akan berfungsi.
2. Masih di MainGame.cs, tambahkan inisialisasi Firebase ke metode Start() yang ada dengan memanggil InitializeFirebaseAndStartGame():

   void Start()
   {
     Screen.SetResolution(Screen.width / 2, Screen.height / 2, true);
     InitializeFirebaseAndStartGame();
   }
   

3. Sekali lagi, di MainGame.cs, temukan InitializeFirebaseAndStartGame(), deklarasikan variabel aplikasi, lalu ganti implementasi metode seperti berikut:

   public Firebase.FirebaseApp app = null;
   
   // Begins the firebase initialization process and afterwards, opens the main menu.
   private void InitializeFirebaseAndStartGame()
   {
     Firebase.FirebaseApp.CheckAndFixDependenciesAsync()
     .ContinueWithOnMainThread(
       previousTask => 
       {
         var dependencyStatus = previousTask.Result;
         if (dependencyStatus == Firebase.DependencyStatus.Available) {
           // Create and hold a reference to your FirebaseApp,
           app = Firebase.FirebaseApp.DefaultInstance;
           // Set the recommended Crashlytics uncaught exception behavior.
           Crashlytics.ReportUncaughtExceptionsAsFatal = true;
           InitializeCommonDataAndStartGame();
         } else {
           UnityEngine.Debug.LogError(
             $"Could not resolve all Firebase dependencies: {dependencyStatus}\n" +
             "Firebase Unity SDK is not safe to use here");
         }
       });
   }
   

Menempatkan logika inisialisasi di sini akan mencegah interaksi pemain sebelum dependensi Firebase diinisialisasi.

Manfaat dan efek pelaporan pengecualian yang tidak tertangani sebagai fatal dibahas dalam FAQ Crashlytics.

Build project Anda dan upload simbol

Catatan: Selesaikan langkah-langkah di bagian ini untuk menyiapkan Crashlytics. Kemudian, pada masa mendatang, selesaikan langkah-langkah ini setiap kali Anda membuat build rilis atau build apa pun yang ingin Anda lihat stack trace tersimbolisasinya di Firebase console (dalam codelab ini, setelah setiap langkah).

Langkah-langkah untuk membuat dan mengupload simbol berbeda untuk aplikasi iOS dan Android.

iOS+ (platform Apple)

1. Dari dialog Build Settings, ekspor project Anda ke ruang kerja Xcode.
2. Bangun aplikasi Anda.
   Untuk platform Apple, plugin Firebase Unity Editor secara otomatis mengonfigurasi project Xcode Anda untuk membuat dan mengupload file simbol yang kompatibel dengan Crashlytics ke server Firebase untuk setiap build. Informasi simbol ini diperlukan untuk melihat stack trace tersimbolisasi di dasbor Crashlytics.

Android

1. (hanya selama penyiapan awal, bukan untuk setiap build) Siapkan build Anda:
   1. Buat folder baru bernama Builds di root direktori project Anda (yaitu, sebagai folder yang setara dengan direktori Assets), lalu buat sub-folder bernama Android.
   2. Di File > Build Settings > Player Settings > Configuration, setel Scripting Backend ke IL2CPP.
      • IL2CPP umumnya menyebabkan build menjadi lebih kecil dan memiliki performa yang lebih baik.
      • IL2CPP juga merupakan SATU-SATUNYA opsi yang tersedia di iOS dan memilihnya di sini memungkinkan kedua platform memiliki paritas yang lebih baik dan membuat perbedaan proses debug antara keduanya (jika Anda memilih untuk membuat keduanya) menjadi lebih sederhana.
2. Bangun aplikasi Anda. Di File > Build Settings, selesaikan langkah-langkah berikut:
   1. Pastikan Create symbols.zip dicentang (atau jika ada dropdown, pilih Debugging).
   2. Build APK langsung dari Unity Editor ke sub-folder Builds/Android yang baru saja Anda buat.
3. Setelah build selesai, Anda harus membuat file simbol yang kompatibel dengan Crashlytics dan menguploadnya ke server Firebase. Informasi simbol ini diperlukan untuk melihat stack trace tersimbolisasi untuk error library native di dasbor Crashlytics.
   
   Buat dan upload file simbol ini dengan menjalankan perintah Firebase CLI berikut:

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

   • FIREBASE_APP_ID: ID Aplikasi Android Firebase Anda (bukan nama paket). Temukan nilai ini di file google-services.json yang Anda download sebelumnya. Nilai ini adalah nilai mobilesdk_app_id.
     Contoh ID Aplikasi Android Firebase: 1:567383003300:android:17104a2ced0c9b9b
   • PATH/TO/SYMBOLS: jalur file simbol terkompresi yang dihasilkan di direktori Builds/Android saat build Anda selesai (misalnya: Builds/Android/myapp-1.0-v100.symbols.zip).

     Catatan: Nama file ini akan berubah saat project dibangun dengan angka yang berbeda yang ditetapkan untuk Version dan Bundle Version Code di File > Build Settings > Player Settings > Identification.

Memaksa error pengujian untuk menyelesaikan penyiapan

Untuk menyelesaikan penyiapan Crashlytics dan melihat data awal di dasbor Crashlytics pada Firebase console, Anda harus memaksa error pengujian.

1. Di MainGameScene, temukan EmptyObject GameObject di Hierarchy editor, tambahkan skrip berikut ke dalamnya, lalu simpan adegan. Skrip ini akan menyebabkan error pengujian beberapa detik setelah Anda menjalankan aplikasi.

   using System;
   using UnityEngine;
   
   public class CrashlyticsTester : MonoBehaviour {
       // Update is called once per frame
       void Update()
       {
           // Tests your Crashlytics implementation by
           // throwing an exception every 60 frames.
           // You should see reports in the Firebase console
           // a few minutes after running your app with this method.
           if(Time.frameCount >0 && (Time.frameCount%60) == 0)
           {
               throw new System.Exception("Test exception; please ignore");
           }
       }
   }
   

2. Bangun aplikasi Anda dan upload informasi simbol setelah build selesai.
   • iOS: Plugin Firebase Unity Editor otomatis mengonfigurasi project Xcode untuk mengupload file simbol.
   • Android: Jalankan perintah crashlytics:symbols:upload Firebase CLI untuk mengupload file simbol Anda.

   Catatan: Jika ini pertama kalinya Anda membangun untuk target seluler tertentu, waktu pembangunan ini bisa mencapai beberapa menit. Build berikutnya akan jauh lebih cepat.

3. Jalankan aplikasi Anda. Setelah aplikasi berjalan, pantau log perangkat dan tunggu hingga pengecualian dipicu dari CrashlyticsTester.
   • iOS: Lihat log di panel bawah Xcode.
   • Android: Lihat log dengan menjalankan perintah berikut di terminal: adb logcat.
4. Buka dasbor Crashlytics untuk melihat pengecualian. Anda akan melihatnya di tabel Masalah di bagian bawah dasbor. Nanti di codelab ini, Anda akan mempelajari lebih lanjut cara menjelajahi laporan ini.
5. Setelah Anda mengonfirmasi bahwa peristiwa telah diupload ke Crashlytics, pilih EmptyObject GameObject yang Anda lampirkan, hapus hanya komponen CrashlyticsTester, lalu simpan adegan untuk memulihkannya ke kondisi semula.

5. Mengaktifkan dan memahami Menu Debug

Sejauh ini, Anda telah menambahkan Crashlytics ke project Unity, menyelesaikan penyiapan, dan mengonfirmasi bahwa Crashlytics SDK mengupload peristiwa ke Firebase. Sekarang Anda akan membuat menu di project Unity yang akan menunjukkan cara menggunakan fungsi Crashlytics yang lebih canggih di game Anda. Project Unity Level Up with Firebase sudah memiliki Menu Debug tersembunyi yang akan Anda buat terlihat dan tulis fungsinya.

Mengaktifkan Menu Debug

Tombol untuk mengakses Menu Debug ada di project Unity Anda, tetapi saat ini tidak diaktifkan. Anda harus mengaktifkan tombol untuk mengaksesnya dari prefab MainMenu:

1. Di Unity Editor, buka prefab bernama MainMenu.
2. Dalam hierarki prefab, temukan sub-objek yang dinonaktifkan bernama DebugMenuButton, lalu pilih.
3. Aktifkan DebugMenuButton dengan mencentang kotak di sudut kiri atas di sebelah kiri kolom teks yang berisi DebugMenuButton.
4. Simpan prefab.
5. Jalankan game di editor atau di perangkat Anda. Menu kini dapat diakses.

Penting: Karena metode error saat ini belum diterapkan, mengetuk tombolnya masing-masing akan memunculkan System.NotImplementedException dan tidak melakukan apa pun.

Melihat pratinjau dan memahami isi metode untuk Menu Debug

Selanjutnya dalam codelab ini, Anda akan menulis isi metode untuk beberapa metode Crashlytics debug yang telah dikonfigurasi sebelumnya. Namun, di project Unity Level Up with Firebase, metode ditentukan dan dipanggil dari DebugMenu.cs.

Meskipun beberapa metode ini akan memanggil metode Crashlytics dan memunculkan error, kemampuan Crashlytics untuk menangkap error ini tidak bergantung pada pemanggilan metode tersebut terlebih dahulu. Sebaliknya, laporan error yang dihasilkan dari error yang ditangkap secara otomatis akan ditingkatkan dengan informasi yang ditambahkan oleh metode ini.

Buka DebugMenu.cs, lalu temukan metode berikut:

Metode untuk membuat dan menganotasi masalah Crashlytics:

• CrashNow
• LogNonfatalError
• LogStringsAndCrashNow
• SetAndOverwriteCustomKeyThenCrash
• SetLogsAndKeysBeforeANR

Metode untuk mencatat log peristiwa Analytics guna membantu proses pen-debug-an:

• LogProgressEventWithStringLiterals
• LogIntScoreWithBuiltInEventAndParams

Pada langkah-langkah selanjutnya dalam codelab ini, Anda akan menerapkan metode ini dan mempelajari cara metode ini membantu mengatasi situasi tertentu yang dapat terjadi dalam pengembangan game.

6. Memastikan pengiriman laporan kerusakan dalam pengembangan

Sebelum Anda mulai menerapkan metode debug ini dan melihat pengaruhnya terhadap laporan error, pastikan Anda memahami cara peristiwa dilaporkan ke Crashlytics.

Untuk project Unity, peristiwa error dan pengecualian dalam game Anda akan segera ditulis ke disk. Untuk pengecualian yang tidak tertangkap yang tidak membuat game Anda error (misalnya, pengecualian C# yang tidak tertangkap dalam logika game), Anda dapat meminta Crashlytics SDK melaporkannya sebagai peristiwa fatal dengan menetapkan properti Crashlytics.ReportUncaughtExceptionsAsFatal ke true tempat Anda menginisialisasi Crashlytics dalam project Unity Anda. Peristiwa ini dilaporkan ke Crashlytics secara real-time tanpa mengharuskan pengguna akhir memulai ulang game. Perhatikan bahwa error native selalu dilaporkan sebagai peristiwa fatal dan dikirim saat pengguna akhir memulai ulang game.

Catatan: Untuk melaporkan pengecualian yang tidak tertangkap sebagai peristiwa fatal, project Unity Anda harus menggunakan Firebase Crashlytics Unity SDK v10.4.0 dan yang lebih baru.

Selain itu, perhatikan perbedaan kecil—tetapi signifikan—berikut antara cara lingkungan runtime yang berbeda mengirimkan informasi Crashlytics ke Firebase:

Simulator iOS:

• Informasi Crashlytics dilaporkan jika dan hanya jika Anda melepaskan Xcode dari simulator. Jika Xcode terlampir, Xcode akan menangkap error di upstream, sehingga mencegah pengiriman informasi.

Perangkat fisik seluler (Android dan iOS):

• Khusus Android: ANR hanya dilaporkan di Android 11+. ANR dan peristiwa non-fatal dilaporkan pada proses berikutnya.

Editor Unity:

• Informasi Crashlytics dari editor dalam mode pemutaran atau secara mandiri TIDAK dicatat atau diupload ke Firebase. Selain itu, alur kerja pengembangan Firebase Desktop tidak mendukung Crashlytics.

Uji game Anda yang mengalami error dengan satu sentuhan tombol di CrashNow()

Setelah Crashlytics disiapkan di game Anda, Crashlytics SDK akan otomatis mencatat error dan pengecualian yang tidak tertangkap, lalu menguploadnya ke Firebase untuk dianalisis. Laporan ditampilkan di dasbor Crashlytics di Firebase console.

1. Untuk menunjukkan bahwa hal ini memang otomatis: buka DebugMenu.cs, lalu ganti metode CrashNow() sebagai berikut:

   void CrashNow()
   {
       TestCrash();
   }
   

2. Bangun aplikasi Anda.
3. (Khusus Android) Upload simbol Anda dengan menjalankan perintah Firebase CLI berikut:

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

4. Ketuk tombol Crash Now, lalu lanjutkan ke langkah berikutnya dalam codelab ini untuk mengetahui cara melihat dan menafsirkan laporan error.

7. Memahami laporan masalah di Firebase console

Saat melihat laporan error, ada sedikit hal lagi yang perlu Anda ketahui tentang cara mendapatkan hasil maksimal dari laporan tersebut. Setiap metode yang Anda tulis akan menunjukkan cara menambahkan berbagai jenis informasi ke laporan Crashlytics.

1. Ketuk tombol Crash Now, lalu mulai ulang aplikasi Anda.
2. Buka dasbor Crashlytics. Scroll ke bawah ke tabel Masalah di bagian bawah dasbor tempat Crashlytics mengelompokkan peristiwa yang memiliki penyebab utama yang sama ke dalam "masalah".
3. Klik masalah baru yang tercantum dalam tabel Masalah. Dengan melakukannya, Ringkasan acara tentang setiap acara individual yang dikirim ke Firebase akan ditampilkan.
   
   Anda akan melihat sesuatu seperti screenshot berikut. Perhatikan bagaimana Ringkasan peristiwa menampilkan stack trace panggilan yang menyebabkan error.

Metadata tambahan

Tab lain yang berguna adalah tab Unity Metadata. Bagian ini memberi tahu Anda tentang atribut perangkat tempat terjadinya peristiwa, termasuk fitur fisik, model/spesifikasi CPU, dan semua jenis metrik GPU.

Berikut contoh saat informasi di tab ini mungkin berguna:
Bayangkan game Anda banyak menggunakan shader untuk mencapai tampilan tertentu, tetapi tidak semua ponsel memiliki GPU yang mampu merender fitur ini. Informasi di tab Metadata Unity dapat memberi Anda gambaran yang lebih baik tentang hardware yang harus diuji oleh aplikasi Anda saat memutuskan fitur yang akan tersedia secara otomatis atau dinonaktifkan sepenuhnya.

Meskipun bug atau error mungkin tidak pernah terjadi di perangkat Anda, karena keragaman perangkat Android yang sangat besar di luar sana, hal ini membantu memahami "hotspot" tertentu di perangkat audiens Anda dengan lebih baik.

8. Menampilkan, menangkap, dan mencatat pengecualian

Sering kali, sebagai developer, meskipun kode Anda menangkap dan menangani pengecualian runtime dengan benar, sebaiknya catat bahwa pengecualian tersebut terjadi, dan dalam keadaan apa. Crashlytics.LogException dapat digunakan untuk tujuan yang sama persis ini—untuk mengirim peristiwa pengecualian ke Firebase sehingga Anda dapat men-debug lebih lanjut masalah di Firebase console.

1. Di Assets/Hamster/Scripts/States/DebugMenu.cs, tambahkan kode berikut ke pernyataan using:

   // Import Firebase
   using Firebase.Crashlytics;
   

2. Masih di DebugMenu.cs, ganti LogNonfatalError() sebagai berikut:

   void LogNonfatalError()
   {
       try
       {
           throw new System.Exception($"Test exception thrown in {nameof(LogNonfatalError)}");
       }
       catch(System.Exception exception)
       {
           Crashlytics.LogException(exception);
       }
   }
   

3. Bangun aplikasi Anda.
4. (Khusus Android) Upload simbol Anda dengan menjalankan perintah Firebase CLI berikut:

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

5. Ketuk tombol Log Nonfatal Error, lalu mulai ulang aplikasi Anda.
6. Buka dasbor Crashlytics, dan Anda akan melihat sesuatu yang mirip dengan yang Anda lihat di langkah terakhir codelab ini.
7. Namun, kali ini batasi filter Event type ke Non-fatals agar Anda hanya melihat error non-fatal, seperti yang baru saja Anda catat.
   

9. Mencatat string ke Crashlytics untuk lebih memahami alur eksekusi program

Pernahkah Anda mencoba mencari tahu mengapa baris kode yang dipanggil dari beberapa jalur, ratusan bahkan ribuan kali per sesi, tiba-tiba dapat menghasilkan pengecualian atau error? Meskipun mungkin lebih baik menelusuri kode di IDE dan melihat nilai dengan lebih cermat, bagaimana jika hal ini hanya terjadi pada sebagian kecil pengguna Anda? Lebih buruk lagi, apa yang akan Anda lakukan jika Anda tidak dapat mereplikasi kerusakan ini, apa pun yang Anda lakukan?

Dalam situasi seperti ini, memiliki beberapa konteks dapat membuat perbedaan besar. Dengan Crashlytics.Log, Anda dapat menuliskan konteks yang Anda butuhkan. Anggap pesan ini sebagai petunjuk untuk diri Anda di masa depan tentang apa yang mungkin terjadi.

Meskipun log dapat digunakan dalam berbagai cara, log biasanya paling berguna untuk merekam situasi saat urutan dan/atau tidak adanya panggilan merupakan informasi yang sangat penting.

1. Di Assets/Hamster/Scripts/States/DebugMenu.cs, ganti LogStringsAndCrashNow() sebagai berikut:

   void LogStringsAndCrashNow()
   {
       Crashlytics.Log($"This is the first of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       const bool RUN_OPTIONAL_PATH = false;
       if(RUN_OPTIONAL_PATH)
       {
           Crashlytics.Log(" As it stands, this log should not appear in your records because it will never be called.");
       }
       else
       {
           Crashlytics.Log(" A log that will simply inform you which path of logic was taken. Akin to print debugging.");
       }
       Crashlytics.Log($"This is the second of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       TestCrash();
   }
   

2. Bangun aplikasi Anda.
3. (Khusus Android) Upload simbol Anda dengan menjalankan perintah Firebase CLI berikut:

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

4. Ketuk tombol Log Strings and Crash Now, lalu mulai ulang aplikasi Anda.
5. Kembali ke dasbor Crashlytics, lalu klik masalah terbaru yang tercantum dalam tabel Masalah. Sekali lagi, Anda akan melihat sesuatu yang mirip dengan masalah sebelumnya.
   
6. Namun, jika Anda mengklik tab Log dalam Ringkasan peristiwa, Anda akan mendapatkan tampilan seperti ini:
   

Catatan: Log ini berguna tidak hanya untuk pesannya, tetapi juga untuk stempel waktunya, yang membantu Anda memahami urutan pembuatannya.

Penting: Untuk menghindari perlambatan aplikasi, Crashlytics membatasi log hingga 64 KB dan menghapus entri log lama jika log sesi melewati batas tersebut.

10. Menulis dan mengganti kunci kustom

Misalnya, Anda ingin lebih memahami error yang sesuai dengan variabel yang ditetapkan ke sejumlah kecil nilai atau konfigurasi. Mungkin akan lebih baik jika Anda dapat memfilter berdasarkan kombinasi variabel dan kemungkinan nilai yang Anda lihat, kapan saja.

Selain mencatat string arbitrer, Crashlytics menawarkan bentuk penelusuran bug lain jika bermanfaat untuk mengetahui status persis program Anda saat terjadi error: kunci kustom.

Ini adalah key-value pair yang dapat Anda tetapkan untuk sesi. Tidak seperti log yang terakumulasi dan murni bersifat aditif, kunci dapat ditimpa untuk hanya mencerminkan status variabel atau kondisi terbaru.

Selain menjadi catatan status terakhir yang direkam dari program Anda, kunci ini kemudian dapat digunakan sebagai filter yang efektif untuk masalah Crashlytics.

1. Di Assets/Hamster/Scripts/States/DebugMenu.cs, ganti SetAndOverwriteCustomKeyThenCrash() sebagai berikut:

   void SetAndOverwriteCustomKeyThenCrash()
   {
       const string CURRENT_TIME_KEY = "Current Time";
       System.TimeSpan currentTime = System.DateTime.Now.TimeOfDay;
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString() // Values must be strings
           );
   
       // Time Passes
       currentTime += DayDivision.DURATION_THAT_ENSURES_PHASE_CHANGE;
   
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString()
           );
       TestCrash();
   }
   

2. Bangun aplikasi Anda.
3. (Khusus Android) Upload simbol Anda dengan menjalankan perintah Firebase CLI berikut:

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

4. Ketuk tombol Set Custom Key and Crash, lalu mulai ulang aplikasi Anda.
5. Kembali ke dasbor Crashlytics, lalu klik masalah terbaru yang tercantum dalam tabel Masalah. Sekali lagi, Anda akan melihat sesuatu yang mirip dengan masalah sebelumnya.
6. Namun, kali ini, klik tab Kunci di Ringkasan peristiwa agar Anda dapat melihat nilai kunci termasuk Current Time:
   

   Penting: Kunci crash_info_entry_0 hanya diisi secara otomatis oleh Crashlytics saat aplikasi Anda dijalankan oleh simulator iOS.

Mengapa Anda ingin menggunakan kunci kustom, bukan log kustom?

• Log cocok untuk menyimpan data berurutan, tetapi kunci kustom lebih baik jika Anda hanya menginginkan nilai terbaru.
• Di Firebase console, Anda dapat dengan mudah memfilter masalah menurut nilai kunci di kotak penelusuran tabel Masalah.

Namun, seperti log, kunci kustom memiliki batas. Crashlytics mendukung maksimum 64 key-value pair. Setelah Anda mencapai ambang batas ini, nilai tambahan tidak akan disimpan. Setiap key-value pair dapat berukuran maksimal 1 KB.

11. (Khusus Android) Menggunakan kunci dan log kustom untuk memahami dan mendiagnosis ANR

Penting: Masalah berikut terutama terkait dengan Android 11 dan yang lebih tinggi. Jika hal ini tidak sesuai dengan kasus penggunaan pengembangan Anda, lewati bagian ini.

Salah satu masalah yang paling sulit di-debug bagi developer Android adalah error Aplikasi Tidak Merespons (ANR). ANR terjadi saat aplikasi gagal merespons input selama lebih dari 5 detik. Jika hal ini terjadi, berarti aplikasi berhenti berfungsi, atau berjalan sangat lambat. Dialog ditampilkan kepada pengguna, dan mereka dapat memilih apakah akan "Menunggu" atau "Tutup Aplikasi".

ANR adalah pengalaman pengguna yang buruk dan (seperti yang disebutkan dalam link ANR di atas) dapat memengaruhi visibilitas aplikasi Anda di Google Play Store. Karena kompleksitasnya, dan karena sering disebabkan oleh kode multithread dengan perilaku yang sangat berbeda pada model ponsel yang berbeda, mereproduksi ANR saat men-debug sering kali sangat sulit, bahkan hampir mustahil. Oleh karena itu, pendekatan analitis dan deduktif biasanya merupakan pendekatan terbaik.

Dalam metode ini, kita akan menggunakan kombinasi Crashlytics.LogException, Crashlytics.Log, dan Crashlytics.SetCustomKey untuk melengkapi pencatatan masalah otomatis dan memberi kita lebih banyak informasi.

Penting: Perhatikan bahwa kode pemblokiran dijalankan di thread UI UnityPlayerActivity. Hal ini agak tidak wajar di Unity, karena thread tidak sama dengan Thread Utama Unity yang merupakan tempat default kode game dijalankan. ANR bisa sangat sulit di-debug karena dapat disebabkan oleh plugin atau kode lain yang berjalan secara non-idiomatik di thread UI.

1. Di Assets/Hamster/Scripts/States/DebugMenu.cs, ganti SetLogsAndKeysBeforeANR() sebagai berikut:

   void SetLogsAndKeysBeforeANR()
   {
       System.Action<string,long> WaitAndRecord =
       (string methodName, long targetCallLength)=>
       {
           System.Diagnostics.Stopwatch stopWatch = new System.Diagnostics.Stopwatch();
           const string CURRENT_FUNCTION = "Current Async Function";
   
           // Initialize key and start timing
           Crashlytics.SetCustomKey(CURRENT_FUNCTION, methodName);
           stopWatch.Start();
   
           // The actual (simulated) work being timed.
           BusyWaitSimulator.WaitOnSimulatedBlockingWork(targetCallLength);
   
           // Stop timing
           stopWatch.Stop();
   
           if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.EXTREME_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough to cause an ANR.");
           }
           else if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.SEVERE_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough it may cause an ANR");
           }
       };
   
       WaitAndRecord("DoSafeWork",1000L);
       WaitAndRecord("DoSevereWork",BusyWaitSimulator.SEVERE_DURATION_MILLIS);
       WaitAndRecord("DoExtremeWork",2*BusyWaitSimulator.EXTREME_DURATION_MILLIS);
   }
   

2. Bangun aplikasi Anda.
3. Upload simbol Anda dengan menjalankan perintah Firebase CLI berikut:

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

4. Ketuk tombol berlabel Set Logs And Keys → ANR, lalu mulai ulang aplikasi Anda.
5. Kembali ke dasbor Crashlytics, lalu klik masalah baru di tabel Masalah untuk melihat Ringkasan peristiwa. Jika panggilan berhasil dilakukan, Anda akan melihat sesuatu seperti ini:
   
   
   Seperti yang Anda lihat, Firebase menunjukkan bahwa menunggu yang sibuk di thread adalah alasan utama aplikasi Anda memicu ANR.
   
6. Jika melihat log di tab Log pada Ringkasan peristiwa, Anda akan melihat bahwa metode terakhir yang tercatat sebagai selesai adalah DoSevereWork.
   
   
   Sebaliknya, metode terakhir yang tercantum sebagai dimulai adalah DoExtremeWork, yang menunjukkan bahwa ANR terjadi selama metode ini, dan game ditutup sebelum dapat mencatat DoExtremeWork.
   
   

Penting: Jika Anda tidak melihat ANR di Android, tetapi melihat error yang menyebutkan InvalidOperationException, baca log. Error kustom ini disertakan sebagai bagian dari codelab ini. Ikuti petunjuk—yang dicatat oleh pengecualian—untuk mengatasinya. Bangun ulang, deploy, dan lakukan iterasi, dan Anda akhirnya akan mendapatkan error yang dimaksud.

Apa manfaatnya?

• Mereproduksi ANR sangat sulit, jadi kemampuan untuk mendapatkan informasi lengkap tentang area kode dan metrik sangat penting untuk mengetahuinya secara deduktif.
• Dengan informasi yang disimpan di kunci kustom, Anda kini mengetahui thread asinkron mana yang paling lama berjalan, dan mana yang berisiko memicu ANR. Data logis dan numerik terkait semacam ini akan menunjukkan bagian kode yang paling perlu dioptimalkan.

12. Menyisipkan peristiwa Analytics untuk memperkaya laporan lebih lanjut

Metode berikut juga dapat dipanggil dari Menu Debug, tetapi alih-alih menimbulkan masalah, metode ini menggunakan Google Analytics sebagai sumber informasi lain untuk lebih memahami cara kerja game Anda.

Tidak seperti metode lain yang telah Anda tulis dalam codelab ini, Anda harus menggunakan metode ini bersama dengan metode lainnya. Panggil metode ini (dengan menekan tombol yang sesuai di Menu Debug) dalam urutan arbitrer apa pun yang Anda inginkan sebelum menjalankan salah satu metode lainnya. Kemudian, saat memeriksa informasi dalam masalah Crashlytics tertentu, Anda akan melihat log peristiwa Analytics yang diurutkan. Data ini dapat digunakan dalam game untuk lebih memahami kombinasi alur program atau input pengguna, bergantung pada cara Anda menginstrumentasi aplikasi.

Catatan: Berikut adalah kasus penggunaan Analytics yang cukup sederhana. Kedalaman Analytics berada di luar cakupan codelab ini. Jika Anda ingin mempelajari lebih lanjut, memahami dengan lebih baik apa yang direkam secara tepat olehnya, atau mengetahui cara men-debug proses pelaporan, lihat Mulai menggunakan Google Analytics untuk Unity.

1. Di Assets/Hamster/Scripts/States/DebugMenu.cs, ganti implementasi yang ada untuk metode berikut:

   public void LogProgressEventWithStringLiterals()
   {
         Firebase.Analytics.FirebaseAnalytics.LogEvent("progress", "percent", 0.4f);
   }
   

   public void LogIntScoreWithBuiltInEventAndParams()
   {
         Firebase.Analytics.FirebaseAnalytics
           .LogEvent(
             Firebase.Analytics.FirebaseAnalytics.EventPostScore,
             Firebase.Analytics.FirebaseAnalytics.ParameterScore,
             42
           );
   }
   

2. Bangun dan deploy game Anda, lalu buka Debug Menu.
3. (Khusus Android) Upload simbol Anda dengan menjalankan perintah Firebase CLI berikut:

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

4. Tekan setidaknya salah satu tombol berikut satu kali atau lebih untuk memanggil fungsi di atas:
   • Log String Event
   • Log Int Event
5. Tekan tombol Crash Now.
6. Mulai ulang game Anda agar game tersebut mengupload peristiwa error ke Firebase.
7. Saat Anda mencatat berbagai urutan peristiwa Analytics arbitrer, lalu game Anda menghasilkan peristiwa yang dibuat laporan Crashlytics (seperti yang baru saja Anda lakukan), peristiwa tersebut akan ditambahkan ke tab Log di Ringkasan Peristiwa Crashlytics seperti ini:
   

Penting: Peristiwa kustom mungkin memerlukan waktu lebih lama untuk muncul di dasbor Analytics di Firebase console daripada waktu yang diperlukan untuk muncul di log error dalam dasbor Crashlytics. Selain itu, peristiwa Analytics mungkin tidak langsung muncul di kedua tempat setelah Anda mencatatnya.

13. Selanjutnya

Dengan demikian, Anda akan memiliki dasar teoretis yang lebih baik untuk melengkapi laporan error yang dibuat secara otomatis. Informasi baru ini memungkinkan Anda menggunakan status saat ini, catatan peristiwa sebelumnya, dan peristiwa Google Analytics yang ada untuk mengelompokkan urutan peristiwa dan logika yang menghasilkan hasil tersebut dengan lebih baik.

Jika aplikasi Anda menargetkan Android 11 (level API 30) atau yang lebih tinggi, pertimbangkan untuk menyertakan GWP-ASan, fitur pengalokasi memori native yang berguna untuk men-debug error yang disebabkan oleh error memori native seperti bug use-after-free dan heap-buffer-overflow. Untuk memanfaatkan fitur proses debug ini, aktifkan GWP-ASan secara eksplisit.

Langkah Berikutnya

Lanjutkan ke codelab Melengkapi game Unity Anda dengan Remote Config, tempat Anda akan mempelajari cara menggunakan Remote Config dan Pengujian A/B di Unity.