เริ่มต้นใช้งาน Crashlytics สำหรับ Unity

เลือกแพลตฟอร์ม: iOS+ Android Android NDK Flutter Unity


คู่มือนี้อธิบายวิธีเริ่มต้นใช้งาน Firebase Crashlytics ใน โปรเจ็กต์ Unity

หลังจากตั้งค่า Firebase Crashlytics SDK ในแอปแล้ว คุณจะดู รายงานข้อขัดข้องที่ครอบคลุมได้ในคอนโซล Firebase

การตั้งค่า Crashlytics ต้องทำทั้งในคอนโซล Firebase และ IDE (เช่น การเพิ่มไฟล์การกำหนดค่า Firebase และ Crashlytics SDK) คุณจะต้องบังคับให้เกิดข้อขัดข้องในการทดสอบเพื่อส่งรายงานข้อขัดข้องแรกไปยัง Firebase จึงจะตั้งค่าให้เสร็จสมบูรณ์ได้

ก่อนเริ่มต้น

  1. หากยังไม่ได้เพิ่ม เพิ่ม Firebase ลงในโปรเจ็กต์ Unity หากไม่มีโปรเจ็กต์ Unity คุณสามารถดาวน์โหลด แอปตัวอย่างได้

  2. แนะนำ: หากต้องการรับ บันทึก Breadcrumb โดยอัตโนมัติเพื่อทำความเข้าใจการกระทำของผู้ใช้ที่นำไปสู่ข้อขัดข้อง เหตุการณ์ที่ไม่ร้ายแรง หรือเหตุการณ์ ANR คุณต้องเปิดใช้ Google Analytics ในโปรเจ็กต์ Firebase

    • หากจะสร้างโปรเจ็กต์ Firebase ใหม่ ให้เปิดใช้ Google Analytics ในระหว่างขั้นตอนการสร้างโปรเจ็กต์

    • หากใช้โปรเจ็กต์ Firebase เดิมที่ไม่ได้เปิดใช้ Google Analytics คุณสามารถเปิดใช้ได้ในหน้า Settings > Integrations ของ Firebase คอนโซล

ขั้นตอนที่ 1: เพิ่ม Crashlytics SDK ลงในแอป

โปรดทราบว่าเมื่อลงทะเบียนโปรเจ็กต์ Unity กับโปรเจ็กต์ Firebase คุณ อาจดาวน์โหลด Firebase Unity SDK และเพิ่มแพ็กเกจ ตามที่อธิบายไว้ในขั้นตอนต่อไปนี้แล้ว

  1. ดาวน์โหลด Firebase Unity SDK แล้วแยกไฟล์ SDK ไว้ในตำแหน่งที่สะดวก Firebase Unity SDK ไม่ได้เจาะจงแพลตฟอร์ม

  2. ในโปรเจ็กต์ Unity แบบเปิด ให้ไปที่เนื้อหา > นำเข้าแพ็กเกจ > แพ็กเกจที่กำหนดเอง

  3. เลือกตำแหน่งเพื่อนำเข้า Crashlytics SDK (FirebaseCrashlytics.unitypackage) จาก SDK ที่แยกไฟล์แล้ว

    หากต้องการใช้ประโยชน์จาก บันทึก Breadcrumb ให้เพิ่ม Firebase SDK สำหรับ Google Analytics ลงในแอป (FirebaseAnalytics.unitypackage) ด้วย และตรวจสอบว่าได้ เปิดใช้ Google Analytics ในโปรเจ็กต์ Firebase แล้ว

  4. คลิกนำเข้า ในหน้าต่าง นำเข้าแพ็กเกจ Unity

ขั้นตอนที่ 2: เริ่มต้น Crashlytics

  1. สร้างสคริปต์ C# ใหม่ แล้วเพิ่มลงใน GameObject ในฉาก

    1. เปิดฉากแรก แล้วสร้าง GameObject ว่างเปล่าชื่อ CrashlyticsInitializer

    2. คลิกเพิ่มคอมโพเนนต์ ในตัวตรวจสอบ สำหรับออบเจ็กต์ใหม่

    3. เลือกสคริปต์ CrashlyticsInit เพื่อเพิ่มลงในออบเจ็กต์ CrashlyticsInitializer

  2. เริ่มต้น Crashlytics ในเมธอด Start ของสคริปต์โดยใช้โค้ดต่อไปนี้

    using System.Collections;
using System.Collections.Generic;
using UnityEngine;

// Import Firebase and Crashlytics
using Firebase;
using Firebase.Crashlytics;

public class CrashlyticsInit : MonoBehaviour {
    // Use this for initialization
    void Start () {
        // Initialize Firebase
        Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => {
            var dependencyStatus = task.Result;
            if (dependencyStatus == Firebase.DependencyStatus.Available)
            {
                // Create and hold a reference to your FirebaseApp,
                // where app is a Firebase.FirebaseApp property of your application class.
                // Crashlytics will use the DefaultInstance, as well;
                // this ensures that Crashlytics is initialized.
                Firebase.FirebaseApp app = Firebase.FirebaseApp.DefaultInstance;

                // When this property is set to true, Crashlytics will report all
                // uncaught exceptions as fatal events. This is the recommended behavior.
                Crashlytics.ReportUncaughtExceptionsAsFatal = true;

                // Set a flag here for indicating that your project is ready to use Firebase.
            }
            else
            {
                UnityEngine.Debug.LogError(System.String.Format(
                  "Could not resolve all Firebase dependencies: {0}",dependencyStatus));
                // Firebase Unity SDK is not safe to use here.
            }
        });
    }

  // Update is called once per frame
  void Update()
    // ...
}

ขั้นตอนที่ 3: (Android เท่านั้น) ตั้งค่าสำหรับการอัปโหลดสัญลักษณ์

ขั้นตอนนี้จำเป็นสำหรับแอป Android ที่ใช้ IL2CPP เท่านั้น

  • แอป Android ที่ใช้แบ็กเอนด์การเขียนสคริปต์ Mono ของ Unity ไม่จำเป็นต้องทำตามขั้นตอนเหล่านี้

  • แอปแพลตฟอร์ม Apple ไม่จำเป็นต้องทำตามขั้นตอนเหล่านี้ เนื่องจากปลั๊กอิน Firebase Unity Editor จะกำหนดค่าโปรเจ็กต์ Xcode โดยอัตโนมัติเพื่ออัปโหลดสัญลักษณ์

Crashlytics SDK สำหรับ Unity (v8.6.1 ขึ้นไป) มีการรายงานข้อขัดข้องของ NDK โดยอัตโนมัติ ซึ่งช่วยให้ Crashlytics รายงานข้อขัดข้องของ Unity IL2CPP ใน Android ได้โดยอัตโนมัติ อย่างไรก็ตาม หากต้องการดู Stack Trace ที่มีการแทนที่ด้วยสัญลักษณ์สำหรับไลบรารีแบบเนทีฟข้อขัดข้องในแดชบอร์ด Crashlytics คุณต้องอัปโหลดข้อมูลสัญลักษณ์ในเวลาบิลด์โดยใช้ CLI Firebase

หากต้องการตั้งค่าสำหรับการอัปโหลดสัญลักษณ์ ให้ทำตามวิธีการติดตั้ง CLIFirebase

หากติดตั้ง CLI ไว้แล้ว ให้ตรวจสอบว่าได้ อัปเดตเป็นเวอร์ชันล่าสุด

Cloud Shell

ขั้นตอนที่ 4: สร้างโปรเจ็กต์และอัปโหลดสัญลักษณ์

iOS+ (แพลตฟอร์ม Apple)

  1. จากกล่องโต้ตอบ Build Settings ให้ส่งออกโปรเจ็กต์ไปยังพื้นที่ทำงาน Xcode

  2. สร้างแอป

    สำหรับแพลตฟอร์ม Apple ปลั๊กอิน Firebase Unity Editor จะกำหนดค่าโปรเจ็กต์ Xcode โดยอัตโนมัติ เพื่อสร้างและอัปโหลดไฟล์สัญลักษณ์ที่เข้ากันได้กับ Crashlyticsไปยังเซิร์ฟเวอร์ Firebase สำหรับแต่ละบิลด์

Android

  1. จากกล่องโต้ตอบ Build Settings ให้ทำอย่างใดอย่างหนึ่งต่อไปนี้

    • ส่งออกไปยังโปรเจ็กต์ Android Studio เพื่อสร้างโปรเจ็กต์ หรือ

    • สร้าง APK จาก Unity Editor โดยตรง
      ก่อนสร้าง ให้ตรวจสอบว่าได้เลือกช่องทำเครื่องหมายสร้าง symbols.zip ในกล่องโต้ตอบ Build Settings แล้ว

  2. เมื่อบิลด์เสร็จแล้ว ให้สร้างไฟล์สัญลักษณ์ที่เข้ากันได้กับ Crashlytics และอัปโหลดไปยังเซิร์ฟเวอร์ Firebase โดยเรียกใช้คำสั่ง Firebase CLI ต่อไปนี้

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

    • FIREBASE_APP_ID: รหัสแอป Firebase Android (ไม่ใช่ ชื่อแพ็กเกจ)
      ตัวอย่างรหัสแอป Firebase Android: 1:567383003300:android:17104a2ced0c9b9b

    • PATH/TO/SYMBOLS: เส้นทางไปยังไฟล์สัญลักษณ์ที่สร้างโดย CLI

      • ส่งออกไปยังโปรเจ็กต์ Android Studio แล้ว - PATH/TO/SYMBOLS คือไดเรกทอรี unityLibrary/symbols ซึ่งสร้างขึ้นในรูทของโปรเจ็กต์ที่ส่งออกหลังจากที่คุณสร้างแอปผ่าน Gradle หรือ Android Studio

      • สร้าง APK จากภายใน Unity โดยตรง — PATH/TO/SYMBOLS คือเส้นทางของไฟล์สัญลักษณ์ที่บีบอัด ซึ่งสร้างขึ้นในไดเรกทอรีรากของโปรเจ็กต์เมื่อบิลด์เสร็จแล้ว (เช่น: myproject/myapp-1.0-v100.symbols.zip)

    ดูตัวเลือกขั้นสูงสำหรับการใช้ Firebase คำสั่ง CLI เพื่อสร้างและอัปโหลดไฟล์สัญลักษณ์

    แฟล็ก คำอธิบาย
    --generator=csym

    ใช้ตัวสร้างไฟล์สัญลักษณ์ cSYM แบบเดิมแทนตัวสร้าง Breakpad เริ่มต้น

    ไม่แนะนำให้ใช้ เราขอแนะนำให้ใช้ตัวสร้างไฟล์สัญลักษณ์ Breakpad เริ่มต้น

    --generator=breakpad

    ใช้ตัวสร้างไฟล์สัญลักษณ์ Breakpad

    โปรดทราบว่าค่าเริ่มต้นสำหรับการสร้างไฟล์สัญลักษณ์คือ Breakpad ใช้แฟล็กนี้เฉพาะในกรณีที่คุณเพิ่ม symbolGenerator { csym() } ในการกำหนดค่าบิลด์และต้องการลบล้างเพื่อใช้ Breakpad แทน

    --dry-run

    สร้างไฟล์สัญลักษณ์แต่ไม่อัปโหลด

    แฟล็กนี้มีประโยชน์หากคุณต้องการตรวจสอบเนื้อหาของ ไฟล์ที่จะส่ง

    --debug ให้ข้อมูลการแก้ไขข้อบกพร่องเพิ่มเติม

ขั้นตอนที่ 5: บังคับให้เกิดข้อขัดข้องในการทดสอบเพื่อตั้งค่าให้เสร็จสมบูรณ์

หากต้องการตั้งค่า Crashlytics ให้เสร็จสมบูรณ์และดูข้อมูลเริ่มต้นใน Crashlytics แดชบอร์ดของ Firebase คอนโซล คุณต้องบังคับให้เกิด ข้อขัดข้องในการทดสอบ

  1. ค้นหา GameObject ที่มีอยู่ แล้วเพิ่มสคริปต์ต่อไปนี้ลงใน GameObject ดังกล่าว สคริปต์นี้จะทำให้เกิดข้อขัดข้องในการทดสอบหลังจากที่คุณเรียกใช้แอปไม่กี่วินาที

    using System;
using UnityEngine;

public class CrashlyticsTester : MonoBehaviour {

    int updatesBeforeException;

    // Use this for initialization
    void Start () {
      updatesBeforeException = 0;
    }

    // Update is called once per frame
    void Update()
    {
        // Call the exception-throwing method here so that it's run
        // every frame update
        throwExceptionEvery60Updates();
    }

    // A method that tests your Crashlytics implementation by throwing an
    // exception every 60 frame updates. You should see reports in the
    // Firebase console a few minutes after running your app with this method.
    void throwExceptionEvery60Updates()
    {
        if (updatesBeforeException > 0)
        {
            updatesBeforeException--;
        }
        else
        {
            // Set the counter to 60 updates
            updatesBeforeException = 60;

            // Throw an exception to test your Crashlytics implementation
            throw new System.Exception("test exception please ignore");
        }
    }
}

  2. สร้างแอปและอัปโหลดข้อมูลสัญลักษณ์หลังจากสร้างเสร็จแล้ว

    • iOS+: ปลั๊กอิน Firebase Unity Editor จะกำหนดค่าโปรเจ็กต์ Xcode โดยอัตโนมัติเพื่ออัปโหลดไฟล์สัญลักษณ์

    • Android: สำหรับแอป Android ที่ใช้ IL2CPP ให้เรียกใช้คำสั่ง Firebase CLI crashlytics:symbols:upload เพื่ออัปโหลดไฟล์สัญลักษณ์

  3. เรียกใช้แอป เมื่อแอปทำงานแล้ว ให้ดูบันทึกอุปกรณ์และรอให้ระบบทริกเกอร์ข้อยกเว้นจาก CrashlyticsTester

    • iOS+: ดูบันทึกในบานหน้าต่างด้านล่างของ Xcode

    • Android: ดูบันทึกโดยเรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัล: adb logcat

  4. ในคอนโซล Firebase ให้ไปที่แดชบอร์ด DevOps & Engagement > Crashlytics เพื่อตรวจสอบรายงานข้อขัดข้องในการทดสอบ

    หากรีเฟรชคอนโซลแล้วแต่ยังไม่เห็นข้อขัดข้องในการทดสอบ หลังจากผ่านไป 5 นาที ให้เปิดใช้การบันทึกการแก้ไขข้อบกพร่อง เพื่อดูว่าแอปส่งรายงานข้อขัดข้องหรือไม่


เพียงเท่านี้ก็เรียบร้อย Crashlytics จะตรวจสอบข้อขัดข้องในแอปของคุณแล้ว ไปที่แดชบอร์ด Crashlytics เพื่อดูและตรวจสอบ รายงานและสถิติทั้งหมด

ขั้นตอนถัดไป

  • (แนะนำ) สำหรับแอป Android ที่ใช้ IL2CPP รับความช่วยเหลือในการแก้ไขข้อบกพร่องของข้อขัดข้องที่เกิดจากข้อผิดพลาดด้านหน่วยความจำเนทีฟโดย การรวบรวม รายงาน GWP-ASan ข้อผิดพลาดที่เกี่ยวข้องกับหน่วยความจำเหล่านี้อาจเชื่อมโยงกับการเสียหายของหน่วยความจำภายใน แอป ซึ่งเป็นสาเหตุหลักของช่องโหว่ด้านความปลอดภัยของแอป หากต้องการใช้ประโยชน์จากฟีเจอร์การแก้ไขข้อบกพร่องนี้ ให้ตรวจสอบว่าแอป ใช้ Crashlytics SDK สำหรับ Unity เวอร์ชันล่าสุด (v10.7.0 ขึ้นไป) และเปิดใช้ GWP-ASan อย่างชัดเจน (คุณต้อง แก้ไขไฟล์ Manifest ของแอป Android)

  • ปรับแต่งการตั้งค่ารายงานข้อขัดข้อง โดยเพิ่มการรายงานแบบเลือกใช้ บันทึก คีย์ และการติดตามข้อผิดพลาดที่ไม่ร้ายแรง

  • ส่งออกข้อมูลไปยัง BigQuery หรือ Cloud Logging เพื่อการวิเคราะห์ขั้นสูงและฟีเจอร์ต่างๆ เช่น การค้นหาข้อมูล การสร้างแดชบอร์ดที่กำหนดเอง และการตั้งค่าการแจ้งเตือนที่กำหนดเอง