عیب یابی Crashlytics و سوالات متداول

این صفحه، راهنمایی برای عیب‌یابی و پاسخ به سوالات متداول در مورد استفاده از Crashlytics را ارائه می‌دهد. اگر نمی‌توانید آنچه را که به دنبالش هستید پیدا کنید یا به کمک بیشتری نیاز دارید، با پشتیبانی Firebase تماس بگیرید.

در این صفحه می‌توانید اطلاعاتی در مورد انواع موضوعات زیر پیدا کنید:

• عیب‌یابی عمومی ، شامل سوالاتی در مورد نمایش داده‌ها یا کار با داده‌ها در کنسول Firebase و سوالاتی در مورد مشکلات رگرسیون.

• پشتیبانی مختص پلتفرم ، شامل سوالات مختص پلتفرم‌های اپل ، اندروید و یونیتی .

• پشتیبانی از یکپارچه‌سازی‌ها ، از جمله سوالات مربوط به BigQuery .

عیب‌یابی عمومی/سوالات متداول

مشاهده‌ی قالب‌های مختلف (و گاهی اوقات «انواع») برای برخی از مسائل در جدول مسائل

ممکن است متوجه دو فرمت مختلف برای مشکلات ذکر شده در جدول مشکلات خود در کنسول Firebase شوید. و همچنین ممکن است متوجه ویژگی‌ای به نام "انواع" در برخی از مشکلات خود شوید. دلیل آن این است!

In early 2023, we rolled out an improved analysis engine for grouping events as well as an updated design and some advanced features for new issues (like variants!). Check out our recent blog post for all the details, but you can read below for the highlights.

Crashlytics تمام رویدادهای برنامه شما (مانند خرابی‌ها، خطاهای غیرفاجعه‌آمیز و ANRها) را تجزیه و تحلیل می‌کند و گروه‌هایی از رویدادها به نام مشکلات (issues ) ایجاد می‌کند - همه رویدادهای یک مشکل (issue) یک نقطه شکست مشترک دارند.

برای گروه‌بندی رویدادها در این مسائل، موتور تحلیل بهبود یافته اکنون جنبه‌های زیادی از رویداد، از جمله فریم‌های موجود در ردیابی پشته، پیام استثنا، کد خطا و سایر ویژگی‌های پلتفرم یا نوع خطا را بررسی می‌کند.

با این حال، در این گروه از رویدادها، ممکن است ردپاهای پشته منجر به خرابی متفاوت باشند. یک ردپای پشته متفاوت می‌تواند به معنای علت ریشه‌ای متفاوت باشد. برای نمایش این تفاوت احتمالی در یک مسئله، اکنون انواعی را در مسائل ایجاد می‌کنیم - هر نوع، زیرگروهی از رویدادها در یک مسئله است که نقطه خرابی یکسانی دارند و یک ردپای پشته مشابه. با انواع، می‌توانید رایج‌ترین ردپاهای پشته را در یک مسئله اشکال‌زدایی کنید و تعیین کنید که آیا علل ریشه‌ای متفاوتی منجر به خرابی می‌شوند یا خیر.

در اینجا چیزی است که با این پیشرفت‌ها تجربه خواهید کرد:

• فراداده‌های اصلاح‌شده در ردیف مشکل نمایش داده می‌شوند
  اکنون درک و اولویت‌بندی مشکلات در برنامه شما آسان‌تر است.

• مسائل تکراری کمتر
  تغییر شماره خط منجر به مشکل جدیدی نمی‌شود.

• اشکال‌زدایی آسان‌تر مسائل پیچیده با علل ریشه‌ای مختلف
  از انواع مختلف برای اشکال‌زدایی رایج‌ترین ردپاهای پشته در یک مسئله استفاده کنید.

• هشدارها و سیگنال‌های معنادارتر
  یک مشکل جدید در واقع نشان دهنده یک باگ جدید است.

• جستجوی قدرتمندتر
  هر شماره شامل فراداده‌های قابل جستجوی بیشتری مانند نوع استثنا و نام بسته است.

نحوه‌ی اعمال این بهبودها به شرح زیر است:

• وقتی رویدادهای جدیدی از برنامه شما دریافت می‌کنیم، بررسی می‌کنیم که آیا با مشکل موجود مطابقت دارند یا خیر.

• اگر هیچ تطابقی وجود نداشته باشد، ما به طور خودکار الگوریتم گروه‌بندی رویداد هوشمندتر خود را برای رویداد اعمال می‌کنیم و یک issue جدید با طراحی فراداده اصلاح‌شده ایجاد می‌کنیم.

این اولین به‌روزرسانی بزرگی است که ما در گروه‌بندی رویدادهای خود انجام می‌دهیم. اگر بازخوردی دارید یا با مشکلی مواجه شده‌اید، با ثبت گزارش به ما اطلاع دهید.

عدم مشاهده لاگ‌های breadcrumb

اگر گزارش‌های breadcrumb را مشاهده نمی‌کنید ( iOS+ | Android | Flutter | Unity )، توصیه می‌کنیم پیکربندی برنامه خود را برای Google Analytics بررسی کنید. مطمئن شوید که شرایط زیر را برآورده می‌کنید:

• شما Google Analytics در پروژه فایربیس خود فعال کرده‌اید .

• شما اشتراک‌گذاری داده‌ها را برای Google Analytics فعال کرده‌اید. برای اطلاعات بیشتر در مورد این تنظیم، به مدیریت تنظیمات اشتراک‌گذاری داده‌های آنالیتیکس خود مراجعه کنید.

• شما کیت توسعه نرم‌افزار Firebase برای Google Analytics را به برنامه خود اضافه کرده‌اید: iOS+ | اندروید | فلاتر | یونیتی .
  این SDK باید علاوه بر Crashlytics SDK اضافه شود.

• شما از آخرین نسخه‌های Firebase SDK برای تمام محصولاتی که در برنامه خود استفاده می‌کنید ( iOS+ | Android | Flutter | Unity ) استفاده می‌کنید.

  برای پلتفرم‌های اپل و برنامه‌های اندروید، به خصوص بررسی کنید که حداقل از نسخه زیر از Firebase SDK برای Google Analytics استفاده می‌کنید: iOS+ — نسخه ۶.۳.۱+ (نسخه ۸.۹.۰+ برای macOS و tvOS) | اندروید — نسخه 17.2.3+ ( BoM v24.7.1+).

عدم مشاهده هشدارهای سرعت

اگر هشدارهای سرعت را نمی‌بینید، مطمئن شوید که از ... استفاده می‌کنید.

عدم مشاهده معیارهای بدون خرابی (یا مشاهده معیارهای غیرقابل اعتماد)

اگر معیارهای بدون خرابی (مانند کاربران و جلسات بدون خرابی) را نمی‌بینید یا معیارهای غیرقابل اعتمادی را می‌بینید، موارد زیر را بررسی کنید:

• مطمئن شوید که از ... استفاده می‌کنید

• مطمئن شوید که تنظیمات جمع‌آوری داده‌های شما بر کیفیت معیارهای بدون خرابی شما تأثیر نمی‌گذارد:

  • If you enable opt-in reporting by disabling automatic crash reporting, crash information can only be sent to Crashlytics from users who have explicitly opted into data collection. Thus, the accuracy of crash-free metrics will be affected since Crashlytics only has crash information from these opted-in users (rather than all your users). This means that your crash-free metrics may be less reliable and less reflective of the overall stability of your app.

  • If you have automatic data collection disabled, you can use sendUnsentReports to send on-device cached reports to Crashlytics . Using this method will send crash data to Crashlytics , but not sessions data which causes the console charts to show low or zero values for crash-free metrics.

کاربران بدون خرابی چگونه محاسبه می‌شوند؟

به بخش «معیارهای بدون خرابی را درک کنید» مراجعه کنید.

چه کسی می‌تواند یادداشت‌های مربوط به یک مسئله را مشاهده، بنویسد و حذف کند؟

یادداشت‌ها به اعضای پروژه اجازه می‌دهند تا در مورد مسائل خاص با سوالات، به‌روزرسانی وضعیت و غیره اظهار نظر کنند.

وقتی یکی از اعضای پروژه یادداشتی ارسال می‌کند، ایمیل حساب گوگل او روی آن یادداشت برچسب‌گذاری می‌شود. این آدرس ایمیل، به همراه یادداشت، برای همه اعضای پروژه که دسترسی مشاهده یادداشت را دارند، قابل مشاهده است.

در ادامه، دسترسی‌های لازم برای مشاهده، نوشتن و حذف یادداشت‌ها شرح داده شده است:

• اعضای پروژه با هر یک از نقش‌های زیر می‌توانند یادداشت‌های موجود را مشاهده و حذف کنند و یادداشت‌های جدیدی در مورد یک مسئله بنویسند.

  • مالک یا ویرایشگر پروژه، مدیر Firebase ، مدیر Quality یا مدیر Crashlytics

• اعضای پروژه با هر یک از نقش‌های زیر می‌توانند یادداشت‌های ارسال شده در مورد یک مسئله را مشاهده کنند، اما نمی‌توانند یادداشتی را حذف یا بنویسند.

  • نمایشگر پروژه، نمایشگر فایربیس ، نمایشگر کیفیت یا نمایشگر Crashlytics

مسئله‌ی پس‌رفته چیست؟

زمانی که قبلاً یک مشکل را بسته‌اید، اما Crashlytics گزارش جدیدی مبنی بر وقوع مجدد آن مشکل دریافت می‌کند، یک مشکل پسرفت داشته است. Crashlytics به‌طور خودکار این مشکلات پسرفت‌شده را دوباره باز می‌کند تا بتوانید آن‌ها را متناسب با برنامه خود برطرف کنید.

در اینجا یک سناریوی مثالی آورده شده است که توضیح می‌دهد چگونه Crashlytics یک مسئله را به عنوان یک رگرسیون طبقه‌بندی می‌کند:

1. برای اولین بار، Crashlytics گزارشی از خرابی مربوط به خرابی "A" دریافت می‌کند. Crashlytics یک شماره مربوطه برای آن خرابی (شماره "A") ایجاد می‌کند.
2. شما این اشکال را سریع برطرف می‌کنید، مشکل «الف» را می‌بندید و سپس نسخه جدیدی از برنامه خود را منتشر می‌کنید.
3. Crashlytics پس از اینکه مشکل را بستید، گزارش دیگری در مورد مشکل «الف» دریافت می‌کند.
   • اگر گزارش از نسخه‌ای از برنامه باشد که Crashlytics هنگام بستن مشکل از آن مطلع بوده است (به این معنی که آن نسخه برای هرگونه خرابی، گزارش خرابی ارسال کرده است)، Crashlytics مشکل را به عنوان مشکل رفع‌شده در نظر نمی‌گیرد. مشکل بسته باقی خواهد ماند.
   • اگر گزارش از نسخه‌ای از برنامه باشد که Crashlytics هنگام بستن مشکل از آن اطلاعی نداشته است (به این معنی که آن نسخه هرگز هیچ گزارش خرابی برای هیچ خرابی ارسال نکرده است)، Crashlytics مشکل را رفع شده در نظر می‌گیرد و دوباره آن را باز می‌کند.

Note: Prior to February 2022, Crashlytics categorized an issue as a regression when that issue re-occurred in any app version, even for app versions that we knew about when you closed the issue. This resulted in Crashlytics sometimes inaccurately identifying regressions. We now use the convention described above.

وقتی یک مشکل دوباره حل می‌شود، ما یک هشدار تشخیص حل مشکل ارسال می‌کنیم و یک سیگنال حل مشکل به مشکل اضافه می‌کنیم تا به شما اطلاع دهیم که Crashlytics مشکل را دوباره باز کرده است. اگر نمی‌خواهید مشکلی به دلیل الگوریتم حل مشکل ما دوباره باز شود، به جای بستن آن، آن را «بی‌صدا» کنید.

چرا مشکلات مربوط به نسخه‌های قدیمی‌تر برنامه را می‌بینم؟

اگر گزارشی از نسخه قدیمی برنامه باشد که هنگام بستن مشکل، هیچ گزارش خرابی ارسال نکرده باشد، Crashlytics مشکل را برطرف شده در نظر می‌گیرد و آن را دوباره باز می‌کند.

این وضعیت می‌تواند در شرایط زیر اتفاق بیفتد: شما یک اشکال را برطرف کرده‌اید و نسخه جدیدی از برنامه خود را منتشر کرده‌اید، اما هنوز کاربرانی در نسخه‌های قبلی بدون رفع اشکال دارید. اگر به طور اتفاقی، یکی از آن نسخه‌های قبلی هنگام بستن مشکل، هیچ گزارش خرابی ارسال نکرده باشد و آن کاربران با اشکال مواجه شوند، آن گزارش‌های خرابی باعث ایجاد یک مشکل رگرسیون می‌شوند.

اگر نمی‌خواهید به دلیل الگوریتم رگرسیون ما، مسئله دوباره باز شود، به جای بستن آن، آن را «بی‌صدا» کنید.

توجه: قبل از فوریه ۲۰۲۲، Crashlytics یک مشکل را به عنوان یک رگرسیون طبقه‌بندی می‌کرد، زمانی که آن مشکل در هر نسخه‌ای از برنامه دوباره رخ می‌داد، حتی برای نسخه‌هایی از برنامه که هنگام بستن مشکل از وجود آنها مطلع بودیم. این امر منجر به این می‌شد که Crashlytics گاهی اوقات رگرسیون‌ها را به طور نادرست شناسایی کند. اکنون از قراردادی که در بالا توضیح داده شد استفاده می‌کنیم.

اگر تعداد زیادی رگرسیون اشتباه شناسایی شده از قبل از فوریه 2022 مشاهده کردید، می‌توانید آنها را دوباره ببندید تا از باز شدن مجدد آنها جلوگیری شود.

---

پشتیبانی ویژه پلتفرم

بخش‌های زیر پشتیبانی از عیب‌یابی و سوالات متداول مختص پلتفرم را ارائه می‌دهند: iOS+ | اندروید | یونیتی .

پشتیبانی از پلتفرم‌های اپل

dSYM ها گم شده اند/آپلود نمی شوند

برای آپلود dSYM های پروژه خود و دریافت خروجی واضح، موارد زیر را بررسی کنید:

1. مطمئن شوید که مرحله ساخت پروژه شما شامل اسکریپت اجرای Crashlytics است، که به Xcode اجازه می‌دهد dSYM های پروژه شما را در زمان ساخت آپلود کند (برای دستورالعمل‌های افزودن اسکریپت، بخش «راهنمای اولیه Crashlytics » را مطالعه کنید). پس از به‌روزرسانی پروژه، یک کرش اجباری ایجاد کنید و تأیید کنید که کرش در داشبورد Crashlytics ظاهر می‌شود.

2. اگر در کنسول Firebase هشدار "Missing dSYM" را مشاهده کردید، Xcode را بررسی کنید تا مطمئن شوید که dSYM های لازم برای ساخت را به درستی تولید می‌کند .

3. اگر Xcode به درستی dSYM ها را تولید می‌کند، و شما هنوز dSYM های از دست رفته را می‌بینید، احتمالاً ابزار اجرای اسکریپت هنگام آپلود dSYM ها گیر کرده است. در این حالت، هر یک از موارد زیر را امتحان کنید:

   • مطمئن شوید که از آخرین نسخه Crashlytics استفاده می‌کنید.

   • فایل‌های dSYM مفقود شده را به صورت دستی آپلود کنید:

     • گزینه ۱: از گزینه «کشیدن و رها کردن» مبتنی بر کنسول در تب dSYMs برای آپلود یک آرشیو زیپ حاوی فایل‌های dSYM مفقود شده استفاده کنید.
     • گزینه ۲: از اسکریپت upload-symbols برای آپلود فایل‌های dSYM مفقود شده، برای UUID های ارائه شده در تب dSYMs، استفاده کنید.

4. اگر همچنان dSYM های از دست رفته را مشاهده می‌کنید، یا آپلودها هنوز ناموفق هستند، با پشتیبانی Firebase تماس بگیرید و حتماً گزارش‌های خود را وارد کنید.

تصادفات به خوبی نمادین‌سازی نشده‌اند

اگر به نظر می‌رسد که نشانه‌های پشته شما به خوبی نمادین‌سازی نشده‌اند، موارد زیر را بررسی کنید:

• اگر فریم‌های کتابخانه برنامه شما فاقد ارجاع به کد برنامه هستند، مطمئن شوید که -fomit-frame-pointer به عنوان یک پرچم کامپایل تنظیم نشده است.

• اگر چندین فریم (Missing) برای کتابخانه برنامه خود مشاهده می‌کنید، بررسی کنید که آیا dSYM های اختیاری به عنوان گم‌شده (برای نسخه برنامه آسیب‌دیده) در برگه dSYM های Crashlytics در کنسول Firebase وجود دارد یا خیر. در این صورت، مرحله عیب‌یابی "هشدار dSYM گم‌شده" را در بخش سوالات متداول dSYM های گم‌شده/ آپلود نشده در این صفحه دنبال کنید. توجه داشته باشید که آپلود این dSYM ها، خرابی‌هایی را که قبلاً رخ داده‌اند، نمادین نمی‌کند، اما این به تضمین نمادین‌سازی برای خرابی‌های آینده کمک می‌کند.

آیا می‌توانم Crashlytics برای macOS یا tvOS استفاده کنم؟

بله، می‌توانید Crashlytics در پروژه‌های macOS و tvOS پیاده‌سازی کنید. مطمئن شوید که نسخه ۸.۹.۰+ از Firebase SDK for Google Analytics را شامل می‌شود تا خرابی‌ها به معیارهای جمع‌آوری‌شده توسط Google Analytics (کاربران بدون خرابی، آخرین نسخه، هشدارهای سرعت و گزارش‌های breadcrumb) دسترسی داشته باشند.

آیا می‌توانم Crashlytics در یک پروژه Firebase با چندین برنامه در پلتفرم‌های مختلف اپل استفاده کنم؟

اکنون می‌توانید خرابی‌ها را برای چندین برنامه در یک پروژه Firebase گزارش دهید، حتی زمانی که برنامه‌ها برای پلتفرم‌های مختلف اپل (مثلاً iOS، tvOS و Mac Catalyst) ساخته شده‌اند. پیش از این، اگر برنامه‌ها دارای شناسه بسته یکسانی بودند، باید آنها را به پروژه‌های Firebase جداگانه تقسیم می‌کردید.

---

پشتیبانی از اندروید

چرا ANRها فقط برای اندروید ۱۱+ گزارش می‌شوند؟

Crashlytics از گزارش‌دهی ANR برای برنامه‌های اندروید از دستگاه‌هایی که اندروید ۱۱ و بالاتر را اجرا می‌کنند، پشتیبانی می‌کند. API زیربنایی که ما برای جمع‌آوری ANRها استفاده می‌کنیم ( getHistoricalProcessExitReasons ) نسبت به رویکردهای مبتنی بر SIGQUIT یا watchdog قابل اعتمادتر است. این API فقط در دستگاه‌های اندروید ۱۱+ در دسترس است.

چرا بعضی از ANR ها BuildId خود را ندارند؟

اگر برخی از ANR های شما BuildId های خود را ندارند، به روش زیر عیب یابی کنید:

• مطمئن شوید که از نسخه به‌روز Crashlytics Android SDK و افزونه Crashlytics Gradle استفاده می‌کنید.

  اگر BuildId های اندروید ۱۱ و برخی از ANR های اندروید ۱۲ را ندارید، احتمالاً از SDK، افزونه Gradle یا هر دوی آنها استفاده می‌کنید که قدیمی هستند. برای جمع‌آوری صحیح BuildId های این ANR ها، باید از نسخه‌های زیر استفاده کنید:

  • Crashlytics Android SDK نسخه ۱۸.۳.۵+ ( Firebase BoM نسخه ۳۱.۲.۲+)
  • افزونه Crashlytics Gradle نسخه ۲.۹.۴+

• بررسی کنید که آیا از مکان غیر استانداردی برای کتابخانه‌های اشتراکی خود استفاده می‌کنید یا خیر.

  اگر فقط BuildId های کتابخانه‌های اشتراکی برنامه‌تان را ندارید، احتمالاً از مکان استاندارد و پیش‌فرض برای کتابخانه‌های اشتراکی استفاده نمی‌کنید. در این صورت، Crashlytics ممکن است نتواند BuildId مرتبط را پیدا کند. توصیه می‌کنیم از مکان استاندارد برای کتابخانه‌های اشتراکی استفاده کنید.

• مطمئن شوید که BuildId را در طول فرآیند ساخت حذف نمی‌کنید.

  توجه داشته باشید که نکات عیب‌یابی زیر هم برای ANRها و هم برای خرابی‌های بومی (native crashes) کاربرد دارند.

  • با اجرای readelf -n روی فایل‌های باینری خود، وجود BuildId را بررسی کنید. اگر BuildId ها وجود ندارند، -Wl,--build-id را به پرچم‌های سیستم ساخت خود اضافه کنید.

  • بررسی کنید که ناخواسته برای کاهش حجم APK، BuildId ها را حذف نکنید.

  • اگر نسخه‌های ساده و بدون تغییر یک کتابخانه را نگه می‌دارید، حتماً در کد خود به نسخه صحیح اشاره کنید.

تفاوت‌های بین گزارش‌های ANR در داشبورد Crashlytics و کنسول گوگل پلی

ممکن است بین تعداد ANR های گوگل پلی و Crashlytics اختلاف وجود داشته باشد. این به دلیل تفاوت در مکانیسم جمع‌آوری و گزارش داده‌های ANR قابل پیش‌بینی است. Crashlytics داده‌های ANR را هنگام راه‌اندازی مجدد برنامه گزارش می‌دهد، در حالی که Android Vitals داده‌های ANR را پس از وقوع ANR ارسال می‌کند.

علاوه بر این، Crashlytics فقط ANRهایی را نمایش می‌دهد که در دستگاه‌های دارای اندروید ۱۱+ رخ می‌دهند، در مقایسه با Google Play که ANRهایی را از دستگاه‌هایی با سرویس‌های Google Play و رضایت جمع‌آوری داده‌ها که پذیرفته شده‌اند، نمایش می‌دهد.

چرا شاهد خرابی‌هایی از فایل‌های .kt هستم که با برچسب مشکلات .java مشخص شده‌اند؟

وقتی یک برنامه از یک مبهم‌ساز استفاده می‌کند که پسوند فایل را افشا نمی‌کند، Crashlytics به طور پیش‌فرض هر مشکل را با پسوند فایل .java تولید می‌کند.

So that Crashlytics can generate issues with the correct file extension, make sure your app uses the following setup:

• از اندروید Gradle نسخه ۴.۲.۰ یا بالاتر استفاده می‌کند
• از R8 با قابلیت مبهم‌سازی فعال استفاده می‌کند. برای به‌روزرسانی برنامه خود به R8، این مستندات را دنبال کنید.

توجه داشته باشید که پس از به‌روزرسانی به تنظیمات شرح داده شده در بالا، ممکن است با مشکلات جدید .kt مواجه شوید که تکرار مشکلات موجود .java هستند. برای کسب اطلاعات بیشتر در مورد این شرایط، به سوالات متداول مراجعه کنید.

چرا مشکلات .kt را می‌بینم که کپی مشکلات .java موجود هستند؟

از اواسط دسامبر ۲۰۲۱، Crashlytics پشتیبانی از برنامه‌هایی که از Kotlin استفاده می‌کنند را بهبود بخشید.

تا همین اواخر، ابزارهای مبهم‌سازی موجود، پسوند فایل را نمایش نمی‌دادند، بنابراین Crashlytics هر مشکل را به طور پیش‌فرض با پسوند فایل .java تولید می‌کرد. با این حال، از اندروید Gradle 4.2.0 به بعد، R8 از پسوند فایل پشتیبانی می‌کند.

با این به‌روزرسانی، Crashlytics اکنون می‌تواند تشخیص دهد که آیا هر کلاس مورد استفاده در برنامه با کاتلین نوشته شده است یا خیر و نام فایل صحیح را در امضای مشکل لحاظ کند. اگر برنامه شما تنظیمات زیر را داشته باشد، اکنون خرابی‌ها به درستی به فایل‌های .kt (به صورت مناسب) نسبت داده می‌شوند:

• برنامه شما از اندروید Gradle نسخه ۴.۲.۰ یا بالاتر استفاده می‌کند.
• برنامه شما از R8 با قابلیت مبهم‌سازی فعال استفاده می‌کند.

از آنجایی که کرش‌های جدید اکنون پسوند فایل صحیح را در امضای مشکل خود قرار می‌دهند، ممکن است مشکلات جدید .kt را ببینید که در واقع فقط کپی‌هایی از مشکلات موجود با برچسب .java هستند. در کنسول Firebase ، ما سعی می‌کنیم شناسایی کنیم و به شما اطلاع دهیم که آیا یک مشکل جدید .kt کپی احتمالی یک مشکل موجود با برچسب .java است یا خیر.

Not getting crashes with Dexguard

اگر با خطای زیر مواجه شدید، احتمالاً از نسخه‌ای از DexGuard استفاده می‌کنید که با Firebase Crashlytics SDK سازگار نیست:

java.lang.IllegalArgumentException: Transport backend 'cct' is not registered

این استثنا برنامه شما را از کار نمی‌اندازد، اما از ارسال گزارش‌های خرابی جلوگیری می‌کند. برای رفع این مشکل:

1. مطمئن شوید که از آخرین نسخه DexGuard 8.x استفاده می‌کنید. آخرین نسخه شامل قوانینی است که توسط Firebase Crashlytics SDK الزامی است.

2. اگر نمی‌خواهید نسخه DexGuard خود را تغییر دهید، خط زیر را به قوانین مبهم‌سازی (در فایل پیکربندی DexGuard) خود اضافه کنید:

   -keepresourcexmlelements manifest/application/service/meta-data@value=cct

چگونه افزونه Gradle را به نسخه ۳ Crashlytics ارتقا دهیم؟

آخرین نسخه افزونه Crashlytics Gradle یک نسخه اصلی (v3.0.0) است و با حذف پشتیبانی از نسخه‌های پایین‌تر Gradle و افزونه Android Gradle، SDK را مدرن می‌کند. علاوه بر این، تغییرات این نسخه مشکلات AGP نسخه ۸.۱+ را برطرف کرده و پشتیبانی از برنامه‌های بومی و نسخه‌های سفارشی را بهبود می‌بخشد.

حداقل الزامات

افزونه Crashlytics Gradle نسخه ۳ حداقل الزامات زیر را دارد:

• افزونه Gradle اندروید نسخه ۸.۱+
  این افزونه را با استفاده از دستیار ارتقاء افزونه Android Gradle در آخرین نسخه Android Studio ارتقا دهید.

• افزونه Gradle google-services فایربیس نسخه ۴.۴.۱+
  این افزونه را با مشخص کردن آخرین نسخه در فایل Gradle build پروژه خود، به صورت زیر ارتقا دهید:

Kotlin

plugins {
  id("com.android.application") version "8.1.4" apply false
  id("com.google.gms.google-services") version "4.4.4" apply false
  ...
}

Groovy

plugins {
  id 'com.android.application' version '8.1.4' apply false
  id 'com.google.gms.google-services' version '4.4.4' apply false
  ...
}

تغییرات در افزونه‌ی Crashlytics

با نسخه ۳ افزونه Crashlytics Gradle، افزونه Crashlytics تغییرات اساسی زیر را دارد:

• افزونه از بلوک defaultConfig android حذف شد. در عوض، شما باید هر نوع را پیکربندی کنید.

• mappingFile منسوخ‌شده‌ی فیلد حذف شد. در عوض، فایل نگاشت ادغام‌شده اکنون به‌طور خودکار ارائه می‌شود.

• فیلد منسوخ شده‌ی strippedNativeLibsDir حذف شد. در عوض، شما باید unstrippedNativeLibsDir برای همه کتابخانه‌های بومی استفاده کنید.

• فیلد unstrippedNativeLibsDir به صورت تجمعی تغییر داده شد.

  مشاهده یک مثال با چندین دایرکتوری

  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 فقط نمادهای موجود در MY/NATIVE/LIBS را آپلود می‌کند، اما uploadCrashlyticsSymbolFilesFeatureXRelease نمادها را هم در MY/NATIVE/LIBS و هم در MY/FEATURE_X/LIBS آپلود خواهد کرد.

• فیلد closure در symbolGenerator با دو فیلد سطح بالای جدید جایگزین شد:

  • symbolGeneratorType ، رشته‌ای از نوع "breakpad" (پیش‌فرض) یا "csym" .
  • breakpadBinary ، فایلی از یک فایل باینری محلیِ بازنویسی‌شده‌ی dump_syms .

مثالی برای نحوه ارتقاء افزونه

Kotlin

قبل از	buildTypes { release { configure<CrashlyticsExtension> { // ... symbolGenerator( closureOf<SymbolGenerator> { symbolGeneratorType = "breakpad" breakpadBinary = file("/PATH/TO/BREAKPAD/DUMP_SYMS") } ) } } }
اکنون در نسخه ۳	buildTypes { release { configure<CrashlyticsExtension> { // ... symbolGeneratorType = "breakpad" breakpadBinary = file("/PATH/TO/BREAKPAD/DUMP_SYMS") } } }

Groovy

قبل از	buildTypes { release { firebaseCrashlytics { // ... symbolGenerator { breakpad { binary file("/PATH/TO/BREAKPAD/DUMP_SYMS") } } } } }
اکنون در نسخه ۳	buildTypes { release { firebaseCrashlytics { // ... symbolGeneratorType "breakpad" breakpadBinary file("/PATH/TO/BREAKPAD/DUMP_SYMS") } } }

پشتیبانی ویژه از Android-NDK

تفاوت‌های بین ردپاهای پشته NDK در داشبورد Crashlytics و logcat

زنجیره ابزارهای LLVM و GNU پیش‌فرض‌ها و رویه‌های متمایزی برای بخش فقط خواندنی فایل‌های باینری برنامه شما دارند که ممکن است باعث ایجاد ردپاهای پشته‌ای متناقض در کنسول Firebase شود. برای کاهش این مشکل، پرچم‌های پیونددهنده زیر را به فرآیند ساخت خود اضافه کنید:

• اگر از لینکر lld از مجموعه ابزار LLVM استفاده می‌کنید، موارد زیر را اضافه کنید:

  -Wl,--no-rosegment

• اگر از لینکر ld.gold از مجموعه ابزار GNU استفاده می‌کنید، موارد زیر را اضافه کنید:

  -Wl,--rosegment

اگر هنوز شاهد ناسازگاری‌های ردیابی پشته هستید (یا اگر هیچ یک از پرچم‌ها به زنجیره ابزار شما مربوط نمی‌شوند)، سعی کنید موارد زیر را به فرآیند ساخت خود اضافه کنید:

-fno-omit-frame-pointer

چگونه می‌توانم از فایل باینری تولیدکننده‌ی نماد Breakpad خودم برای NDK استفاده کنم؟

افزونه‌ی Crashlytics یک مولد فایل نماد Breakpad سفارشی‌سازی‌شده را در خود جای داده است. اگر ترجیح می‌دهید از فایل باینری خودتان برای تولید فایل‌های نماد Breakpad استفاده کنید (برای مثال، اگر ترجیح می‌دهید تمام فایل‌های اجرایی بومی را در زنجیره‌ی ساخت خود از منبع بسازید)، از ویژگی افزونه‌ی اختیاری symbolGeneratorBinary برای مشخص کردن مسیر فایل اجرایی استفاده کنید.

توجه: نسخه لینوکس مولد فایل نماد Breakpad برای فایل‌های باینری اندروید مورد نیاز است.

شما می‌توانید مسیر فایل باینری تولیدکننده فایل نماد Breakpad را به یکی از دو روش زیر مشخص کنید:

• گزینه ۱ : مسیر را از طریق افزونه firebaseCrashlytics در فایل build.gradle خود مشخص کنید

  موارد زیر را به فایل build.gradle.kts در سطح برنامه خود اضافه کنید:

  افزونه Gradle نسخه ۳.۰.۰+

  android {
    buildTypes {
      release {
        configure<CrashlyticsExtension> {
          nativeSymbolUploadEnabled = true
          // Add these optional fields to specify the path to the executable
          symbolGeneratorType = "breakpad"
          breakpadBinary = file("/PATH/TO/BREAKPAD/DUMP_SYMS")
        }
      }
    }
  }

  نسخه‌های پایین‌تر افزونه

  android {
    // ...
    buildTypes {
      // ...
      release {
        // ...
        firebaseCrashlytics {
          // existing; required for either symbol file generator
          nativeSymbolUploadEnabled true
          // Add this optional new block to specify the path to the executable
          symbolGenerator {
            breakpad {
              binary file("/PATH/TO/BREAKPAD/DUMP_SYMS")
            }
          }
        }
     }
  }

• گزینه ۲ : مسیر را از طریق یک خط ویژگی در فایل ویژگی‌های Gradle خود مشخص کنید

  شما می‌توانید از ویژگی com.google.firebase.crashlytics.breakpadBinary برای مشخص کردن مسیر فایل اجرایی استفاده کنید.

  شما می‌توانید فایل ویژگی‌های Gradle خود را به صورت دستی به‌روزرسانی کنید یا فایل را از طریق خط فرمان به‌روزرسانی کنید. به عنوان مثال، برای مشخص کردن مسیر از طریق خط فرمان، از دستوری مانند زیر استفاده کنید:

  ./gradlew -Pcom.google.firebase.crashlytics.symbolGenerator=breakpad \
    -Pcom.google.firebase.crashlytics.breakpadBinary=/PATH/TO/BREAKPAD/DUMP_SYMS \
    app:assembleRelease app:uploadCrashlyticsSymbolFileRelease
  

آیا Crashlytics از armeabi پشتیبانی می‌کند؟

Firebase Crashlytics NDK از ARMv5 (armeabi) پشتیبانی نمی‌کند. پشتیبانی از این ABI از NDK r17 حذف شده است.

---

پشتیبانی از یونیتی

مشاهده‌ی ردپاهای پشته‌ای بدون نمادگذاری برای برنامه‌های اندروید در داشبورد Crashlytics

اگر از Unity IL2CPP استفاده می‌کنید و ردپاهای پشته بدون نماد را مشاهده می‌کنید، موارد زیر را امتحان کنید:

1. مطمئن شوید که از نسخه ۸.۶.۱ یا بالاتر Crashlytics Unity SDK استفاده می‌کنید.

2. مطمئن شوید که برای تولید و آپلود فایل نماد خود، دستور crashlytics:symbols:upload در Firebase CLI را تنظیم و اجرا کرده‌اید.

   شما باید هر بار که یک نسخه آزمایشی یا هر نسخه‌ای که می‌خواهید ردپاهای پشته نمادین آن را در کنسول Firebase ببینید، ایجاد می‌کنید، این دستور CLI را اجرا کنید. برای کسب اطلاعات بیشتر به بخش «گزارش‌های خرابی خوانا» مراجعه کنید.

آیا می‌توان Crashlytics با برنامه‌هایی که از IL2CPP استفاده می‌کنند، استفاده کرد؟

بله، Crashlytics می‌تواند ردیابی‌های پشته نمادین را برای برنامه‌های شما که از IL2CPP استفاده می‌کنند، نمایش دهد. این قابلیت برای برنامه‌های منتشر شده در پلتفرم‌های اندروید یا اپل در دسترس است. در اینجا کاری که باید انجام دهید آمده است:

1. مطمئن شوید که از نسخه ۸.۶.۰ یا بالاتر Crashlytics Unity SDK استفاده می‌کنید.

2. وظایف لازم برای پلتفرم خود را انجام دهید:

   • برای برنامه‌های پلتفرم اپل : هیچ اقدام خاصی لازم نیست. برای برنامه‌های پلتفرم اپل، افزونه Firebase Unity Editor به طور خودکار پروژه Xcode شما را برای آپلود نمادها پیکربندی می‌کند.

   • برای برنامه‌های اندروید : مطمئن شوید که برای ایجاد و آپلود فایل نماد خود، دستور crashlytics:symbols:upload در Firebase CLI را تنظیم و اجرا کرده‌اید.

     شما باید هر بار که یک نسخه آزمایشی یا هر نسخه‌ای که می‌خواهید ردپاهای پشته نمادین آن را در کنسول Firebase ببینید، ایجاد می‌کنید، این دستور CLI را اجرا کنید. برای کسب اطلاعات بیشتر به بخش «گزارش‌های خرابی خوانا» مراجعه کنید.

گزارش استثنائاتِ بررسی نشده به عنوان خطاهای مهلک

Crashlytics می‌تواند استثنائاتِ نادیده گرفته شده را به عنوان خطاهای مهلک گزارش دهد (از نسخه ۱۰.۴.۰ کیت توسعه نرم‌افزار Unity). سوالات متداول زیر به توضیح منطق و بهترین شیوه‌های استفاده از این ویژگی کمک می‌کند.

چرا یک برنامه باید استثنائاتِ پیش‌بینی‌نشده را به عنوان خطای مهلک گزارش کند؟

با گزارش استثنائاتِ شناسایی‌نشده به عنوان مواردِ بحرانی، شما می‌توانید نشانه‌ی واقع‌بینانه‌تری از اینکه چه استثنائاتی ممکن است منجر به غیرقابل‌بازی شدن بازی شوند، حتی اگر برنامه همچنان به اجرا ادامه دهد، داشته باشید.

توجه داشته باشید که اگر شروع به گزارش تصادفات منجر به فوت کنید، احتمالاً درصد کاربران بدون تصادف (CFU) شما کاهش می‌یابد، اما معیار CFU بیشتر نمایانگر تجربیات کاربران نهایی با برنامه شما خواهد بود.

مهم: گزارش استثنائات شناسایی نشده به عنوان موارد کشنده، تاثیری بر داده‌های حیاتی اندروید شما ندارد . موارد کشنده گزارش شده در Crashlytics فقط برای شما قابل مشاهده هستند تا بتوانید مشکلات برنامه‌ها و بازی‌های خود را کشف و برطرف کنید.

کدام موارد استثنا به عنوان فوتی گزارش خواهند شد؟

برای اینکه Crashlytics یک استثنای ناشناخته را به عنوان خطای مهلک گزارش کند، باید هر دو شرط زیر برقرار باشد:

• در طول مقداردهی اولیه برنامه، ویژگی ReportUncaughtExceptionsAsFatal باید روی true تنظیم شود .

• برنامه شما (یا یک کتابخانه شامل) یک استثنا را صادر می‌کند که دریافت نشده است. استثنایی که ایجاد شده است، اما دریافت نشده است ، به عنوان استثنای دریافت نشده در نظر گرفته نمی‌شود.

بعد از فعال کردن گزارش استثنائاتِ بررسی نشده به عنوان خطاهای مهلک، حالا خطاهای مهلک جدید زیادی دارم. چگونه می‌توانم این خطاها را به درستی مدیریت کنم؟

وقتی گزارش‌هایی از استثنائاتِ مدیریت نشده به عنوان خطاهای مهلک دریافت می‌کنید، در اینجا چند گزینه برای مدیریت این استثنائاتِ مدیریت نشده ارائه شده است:

• در نظر بگیرید که چگونه می‌توانید شروع به دریافت و مدیریت این استثنائاتِ دریافت نشده کنید.
• گزینه‌های مختلفی را برای ثبت خطاها در کنسول اشکال‌زدایی Unity و Crashlytics در نظر بگیرید.

گرفتن و مدیریت استثنائات پرتاب شده

استثنائات برای انعکاس حالت‌های غیرمنتظره یا استثنایی ایجاد و ارسال می‌شوند. حل مشکلاتی که توسط یک استثنای ارسال شده منعکس می‌شوند، شامل بازگرداندن برنامه به حالت شناخته شده است (فرآیندی که به عنوان مدیریت استثنا شناخته می‌شود).

بهترین روش این است که تمام استثنائات پیش‌بینی‌شده را دریافت و مدیریت کنید، مگر اینکه برنامه را نتوان به حالت شناخته‌شده‌ای برگرداند.

برای کنترل اینکه کدام نوع استثنائات توسط چه کدی دریافت و مدیریت می‌شوند، کدی را که ممکن است استثنا ایجاد کند، در یک بلوک try-catch قرار دهید . مطمئن شوید که شرایط موجود در دستورات catch تا حد امکان محدود هستند تا استثنائات خاص را به طور مناسب مدیریت کنند.

ثبت خطاها در Unity یا Crashlytics

روش‌های مختلفی برای ثبت استثنائات در Unity یا Crashlytics وجود دارد تا به رفع اشکال کمک کند.

هنگام استفاده از Crashlytics ، دو گزینه رایج و توصیه‌شده در اینجا آمده است:

• گزینه ۱: در کنسول Unity چاپ کنید، اما در طول توسعه یا عیب‌یابی به Crashlytics گزارش ندهید

  • با استفاده از Debug.Log(exception) ، Debug.LogWarning(exception) و Debug.LogError(exception) که محتوای استثنا را در کنسول Unity چاپ می‌کنند و استثنا را دوباره پرتاب نمی‌کنند، در کنسول Unity چاپ کنید.

• گزینه ۲: برای گزارش‌های تلفیقی در داشبورد Crashlytics برای موقعیت‌های زیر، در Crashlytics آپلود کنید:

  • اگر یک استثنا ارزش ثبت شدن برای اشکال‌زدایی یک رویداد احتمالی بعدی Crashlytics را دارد، از Crashlytics.Log(exception.ToString()) استفاده کنید.
  • اگر یک استثنا، علیرغم شناسایی و مدیریت شدن، همچنان باید به Crashlytics گزارش شود، از Crashlytics.LogException(exception) برای ثبت آن به عنوان یک رویداد غیرمهلک استفاده کنید.

However, if you want to manually report a fatal event to Unity Cloud Diagnostics, you can use Debug.LogException . This option prints the exception to the Unity console like Option 1, but it also throws the exception (whether or not it has been thrown or caught yet). It throws the error nonlocally. This means that even a surrounding Debug.LogException(exception) with try-catch blocks still results in an uncaught exception.

بنابراین، اگر و فقط اگر می‌خواهید تمام موارد زیر را انجام دهید، Debug.LogException را فراخوانی کنید:

• برای چاپ استثنا در کنسول Unity.
• برای آپلود کردن استثنا به عنوان یک رویداد مهلک در Crashlytics .
• برای ایجاد استثنا، آن را به عنوان یک استثنای کنترل نشده در نظر بگیرید و آن را به Unity Cloud Diagnostics گزارش دهید.

توجه داشته باشید که اگر می‌خواهید یک استثنای گرفته شده را در کنسول Unity چاپ کنید و آن را به عنوان یک رویداد غیرفاتال در Crashlytics آپلود کنید، به جای آن موارد زیر را انجام دهید:

try
{
    methodThatThrowsMyCustomExceptionType();
}
catch(MyCustomExceptionType exception)
{
    // Print the exception to the Unity console at the error level.
    Debug.LogError(exception);
    // Upload the exception to Crashlytics as a non-fatal event.
    Crashlytics.LogException(exception); // not Debug.LogException
    //
    // Code that handles the exception
    //
}

---

پشتیبانی از ادغام‌ها

برنامه همچنین از SDK Google Mobile Ads استفاده می‌کند اما دچار خرابی نمی‌شود

اگر پروژه شما از Crashlytics در کنار SDK Google Mobile Ads استفاده می‌کند، احتمالاً گزارش‌دهنده‌های خرابی هنگام ثبت کنترل‌کننده‌های خطا تداخل ایجاد می‌کنند. برای رفع این مشکل، با فراخوانی disableSDKCrashReporting ، گزارش خرابی را در SDK Mobile Ads غیرفعال کنید.

مجموعه داده‌های BigQuery من کجا قرار دارد؟

فایربیس داده‌ها را به محل مجموعه داده‌ای که هنگام تنظیم صادرات داده به BigQuery انتخاب کرده‌اید، صادر می‌کند.

• این مکان هم برای مجموعه داده Crashlytics و هم برای مجموعه داده Sessions در Firebase (در صورتی که داده‌های Session برای خروجی گرفتن فعال باشد) اعمال می‌شود.

• این مکان فقط برای داده‌های صادر شده به BigQuery قابل استفاده است و تاثیری بر مکان داده‌های ذخیره شده برای استفاده در داشبورد Crashlytics کنسول Firebase یا در Android Studio ندارد.

• پس از ایجاد یک مجموعه داده، مکان آن قابل تغییر نیست، اما می‌توانید مجموعه داده را در مکان دیگری کپی کنید یا به صورت دستی مجموعه داده را در مکان دیگری جابجا (بازسازی) کنید. برای کسب اطلاعات بیشتر، به تغییر مکان برای صادرات موجود مراجعه کنید.

توجه: قابلیت انتخاب و تغییر مکان برای صادرات داده‌ها فقط در صورتی در دسترس است که صادرات را بعد از اواسط اکتبر ۲۰۲۴ فعال کرده باشید یا اگر به زیرساخت صادرات جدید ارتقا دهید .

چگونه می‌توان زیرساخت صادرات جدید BigQuery را ارتقا داد؟

In mid-October 2024, Crashlytics launched a new infrastructure for batch export of Crashlytics data into BigQuery .

• اگر بعد از اکتبر ۲۰۲۴ ، قابلیت صادرات دسته‌ای را فعال کرده باشید، پروژه Firebase شما به طور خودکار از زیرساخت صادرات جدید استفاده می‌کند و نیازی به انجام هیچ کاری نیست.

• اگر قبل یا در طول اکتبر ۲۰۲۴ ، صادرات دسته‌ای را فعال کرده‌اید، اطلاعات موجود در این سوالات متداول را بررسی کنید تا مشخص شود که آیا نیاز به انجام اقدامی دارید یا خیر.

تمام پروژه‌های فایربیس از ۹ ژانویه ۲۰۲۶ به طور خودکار به زیرساخت جدید صادرات دسته‌ای ارتقا خواهند یافت. می‌توانید قبل از این تاریخ ارتقا دهید ، اما مطمئن شوید که جداول دسته‌ای BigQuery شما پیش‌نیازهای ارتقا را برآورده می‌کنند.

شما می‌توانید به زیرساخت جدید ارتقا دهید ، اما مطمئن شوید که جداول دسته‌ای BigQuery شما پیش‌نیازهای ارتقا را برآورده می‌کنند.

توجه: این ارتقاء زیرساخت فقط برای خروجی‌های دسته‌ای Crashlytics اعمال می‌شود و برای خروجی‌های جلسات (session) صدق نمی‌کند .

مشخص کنید که آیا روی زیرساخت جدید هستید یا خیر

اگر صادرات دسته‌ای را در اواسط اکتبر ۲۰۲۴ یا بعد از آن فعال کرده باشید، پروژه Firebase شما به طور خودکار از زیرساخت صادرات جدید استفاده می‌کند.

می‌توانید بررسی کنید که پروژه شما از کدام زیرساخت استفاده می‌کند: به کنسول Google Cloud بروید و اگر "پیکربندی انتقال داده" شما با عنوان Firebase Crashlytics with Multi-Region Support برچسب‌گذاری شده باشد، پروژه شما از زیرساخت صادرات جدید استفاده می‌کند.

تفاوت‌های مهم بین زیرساخت‌های صادراتی قدیمی و زیرساخت‌های صادراتی جدید

• زیرساخت جدید از مجموعه داده‌های Crashlytics در مکان‌های خارج از ایالات متحده پشتیبانی می‌کند.

  • صادرات قبل از اواسط اکتبر ۲۰۲۴ فعال شده و به زیرساخت صادرات جدید ارتقا یافته است - اکنون می‌توانید به صورت اختیاری مکان صادرات داده‌ها را تغییر دهید .

  • فعال‌سازی صادرات در اواسط اکتبر ۲۰۲۴ یا بعد از آن — در هنگام راه‌اندازی از شما خواسته شد تا مکانی را برای صادرات داده‌ها انتخاب کنید.

• زیرساخت جدید از پر کردن مجدد داده‌های مربوط به قبل از فعال کردن قابلیت خروجی گرفتن پشتیبانی نمی‌کند.

  • زیرساخت قدیمی تا 30 روز قبل از تاریخی که شما صادرات را فعال کردید، از پر کردن مجدد پشتیبانی می‌کرد.

  • زیرساخت جدید از پر کردن مجدد داده‌ها تا 30 روز گذشته یا برای جدیدترین تاریخی که امکان صادرات به BigQuery را فعال کرده‌اید (هر کدام که جدیدتر باشد) پشتیبانی می‌کند.

• این زیرساخت جدید، جداول دسته‌ای BigQuery را با استفاده از شناسه‌های تعیین‌شده برای برنامه‌های Firebase شما در پروژه Firebase نامگذاری می‌کند.

  • زیرساخت قدیمی، داده‌ها را در جداول دسته‌ای با نام‌هایی بر اساس شناسه‌های بسته یا نام‌های بسته در فایل باینری برنامه شما می‌نوشت.

  • زیرساخت جدید، داده‌ها را در جداول دسته‌ای با نام‌هایی بر اساس شناسه‌های بسته یا نام‌های بسته تنظیم‌شده برای برنامه‌های Firebase ثبت‌شده شما در پروژه Firebase می‌نویسد.

  مهم: اگر قبل از اواسط اکتبر ۲۰۲۴، قابلیت صادرات دسته‌ای را فعال کرده‌اید ، قبل از ارتقاء دستی به زیرساخت صادرات جدید یا قبل از ۹ ژانویه ۲۰۲۶ (زمانی که قرار است همه پروژه‌ها به طور خودکار ارتقا یابند)، مطمئن شوید که جداول دسته‌ای موجود شما پیش‌نیازهای مربوط به شناسه‌های بسته و نام‌های بسته را برآورده می‌کنند.

مرحله ۱ : پیش‌نیازهای ارتقاء

1. بررسی کنید که جداول دسته‌ای BigQuery موجود شما از شناسه‌های منطبق با شناسه‌های بسته یا نام‌های بسته تنظیم‌شده برای برنامه‌های Firebase ثبت‌شده شما در پروژه Firebase استفاده کنند. اگر آنها مطابقت نداشته باشند، ممکن است در داده‌های دسته‌ای صادرشده خود اختلال ایجاد کنید. اکثر پروژه‌ها در وضعیت مناسب و سازگار خواهند بود، اما بررسی این موضوع قبل از ارتقا مهم است.

   • You can find all the Firebase Apps registered in your Firebase project in the Firebase console: Go to your Project settings , then scroll to the Your apps card to see all your Firebase Apps and their information.

   • You can find all your BigQuery batch tables in the BigQuery page of the Google Cloud console.

   Note: BigQuery streaming tables that end with REALTIME aren't affected by the new export infrastructure and can be ignored.

   For example, here are ideal states where you won't have any issues upgrading:

   • You have a batch table named com_yourcompany_yourproject_IOS and a Firebase iOS+ App with the bundle ID com.yourcompany.yourproject registered in your Firebase project.

   • You have a batch table named com_yourcompany_yourproject_ANDROID and a Firebase Android App with the package name com.yourcompany.yourproject registered in your Firebase project.

2. If you have batch table names that do not match the identifiers set for your registered Firebase Apps, then follow the instructions later on this page before manually upgrading or before January 9, 2026 to avoid disruption to your batch export.

Step 2 : Manually upgrade to the new infrastructure

If you enabled batch export before mid-October 2024, then you can manually upgrade to the new infrastructure simply by toggling Crashlytics data export off and then on again in the Firebase console.

Here are the detailed steps:

1. In the Firebase console, go to the Integrations page .

2. In the BigQuery card, click Manage .

3. Toggle off the Crashlytics slider to disable export. When prompted, confirm that you want data export to stop.

4. Immediately toggle on again the Crashlytics slider to re-enable export. When prompted, confirm that you want to export data.

   Your Crashlytics data export to BigQuery is now using the new export infrastructure.

Your existing batch table name doesn't match your Firebase App identifier

If your existing batch table name does not match the bundle ID or package name set for your registered Firebase App, then expand this section and implement one of the options to avoid disruptions to your exported batch data.

If you have existing BigQuery batch tables in this state, then it means that they're not compatible with Firebase's new batch export-to- BigQuery infrastructure. Note that all Firebase projects will be automatically migrated to the new export infrastructure as early as January 9, 2026.

Follow the guidance in this section before manually upgrading or before January 9, 2026 to avoid disruption to the batch export of your Crashlytics data to BigQuery .

Jump to instructions for options to avoid disruptions

Understand how the export infrastructure uses identifiers to write data to BigQuery tables

Here's how the two export infrastructures write Crashlytics data to BigQuery batch tables:

• Legacy export infrastructure : Writes data to a table with a name that's based on the bundle ID or package name in your app's binary .

• New export infrastructure : Writes data to a table with a name that's based on the bundle ID or package name set for your registered Firebase App in your Firebase project .

Unfortunately, sometimes the bundle ID or package name in your app's binary doesn't match the bundle ID or package name set for your registered Firebase App in your Firebase project . This usually happens if someone didn't enter the actual identifier during app registration.

What happens if this isn't fixed before upgrading?

If the identifiers in these two locations don't match, then the following happens after upgrading to the new export infrastructure:

• Your Crashlytics data will start writing to a new BigQuery batch table — that is, a new table with a name based on the bundle ID or package name set for your registered Firebase App in your Firebase project .

• Any existing "legacy" table with a name based on the identifier in your app's binary will no longer have data written to it.

Example scenarios of mismatched identifiers

Note that BigQuery batch table names are automatically appended with _IOS or _ANDROID to indicate the platform of the app.

Identifier(s) in your app's binary	Identifier(s) set for your Firebase App(s)	Legacy behavior	Behavior after upgrade to new export infrastructure	راه حل
foo	bar	Writes to a single table named after the identifier in app's binary ( foo )	Creates then writes to a single table named after the identifier set for Firebase App ( bar )	Implement either Option 1 or 2 described below.
foo	bar , qux , etc.	Writes to a single table named after the identifier in app's binary ( foo )	Creates* then writes to multiple tables named after the identifiers set for Firebase Apps ( bar , qux , etc.)	Implement Option 2 described below.
foo , baz , etc.	bar	Writes to multiple tables named after the multiple identifiers in app's binary ( foo , baz , etc.)	Creates** then writes every app's data to a single table named after the identifier set for Firebase App ( bar )	None of the options can be implemented. You can still differentiate data from each app within the single table by using the app's bundle_identifier which is exported alongside the data.

^{* If the identifier in your app's binary matched one of the identifiers set for a Firebase App, then the new export infrastructure won't create a new table for that identifier. Instead, it will continue writing data for that specific app to it. All other apps will be written to new tables.}

^{** If one of the identifiers in your app's binary matched the identifier set for the Firebase App, then the new export infrastructure won't create a new table. Instead, it will maintain that table and start writing data for all apps to it.}

Options to avoid disruption

To avoid any disruptions, follow the instructions for one of the options described below before you manually upgrade or before January 9, 2026.

Important: If you have any questions or don't feel comfortable implementing one of these options, then reach out to Firebase Support .

• OPTION 1 :
  Use the new table created by the new export infrastructure. You'll copy data from your existing table to the new table.

  1. In the Firebase console, upgrade to the new export infrastructure by turning export off and then on again for the linked app.

     This action creates a new batch table with a name that's based on the bundle ID or package name set for your registered Firebase App in your Firebase project .

  2. In the Google Cloud console, copy all the data from your legacy table to the new table that was just created.

  3. If you have any downstream dependencies that depend on your batch table, change them to use the new table.

  Note: Once you upgrade, new data will not write to your legacy table. Any previously written data in the legacy table won't be deleted.

• OPTION 2 :
  Continue writing to your existing table. You'll override some defaults in a BigQuery config to achieve this.

  1. In the Firebase console, find and take note of the Firebase App ID (for example, 1:1234567890:ios:321abc456def7890 ) of the app with the mismatched batch table name and identifier:
     Go to your Project settings , then go the Your apps card to see all your Firebase Apps and their information.

  2. In the Firebase console, upgrade to the new export infrastructure by turning export off and then on again for the linked app.

     This action does two things:

     • Creates a new batch table with a name that's based on the bundle ID or package name set for your registered Firebase App in your Firebase project . (You'll eventually delete this table, but do not delete it yet.)

     • Creates a BigQuery "data transfer config" with the source Firebase Crashlytics with Multi-Region Support .

  3. In the Google Cloud console, change the new "data transfer config" so that data will continue to write to your existing table:

     1. Go to BigQuery > Data transfers to view your "data transfer config".

     2. Select the config that has the source Firebase Crashlytics with Multi-Region Support .

     3. Click Edit in the top-right corner.

     4. In the Data source details section, find a list for gmp_app_id and a list for client_namespace .

        In BigQuery , the Firebase App ID is called the gmp_app_id . By default, the client_namespace value in BigQuery is the corresponding unique bundle ID / package name of the app, but you'll be overriding this default configuration.

        BigQuery uses the client_namespace value for the name of the batch table that each linked Firebase App writes to.

     5. Find the gmp_app_id of the Firebase App for which you want to override default settings. Change its client_namespace value to the name of the table you want the Firebase App to write to instead (usually this is the name of the legacy table the app was writing to with the legacy export infrastructure).

        Note: If you were previously writing to a single table and now you have multiple tables after upgrading, then you can use the same client_namespace for each applicable gmp_app_id . BigQuery will essentially merge all the tables and write all data for all the Firebase Apps to that one table.

     6. Save the config change.

  4. Schedule a backfill for the days that your existing table is missing data.

  5. Once the backfill is done, delete the new table that was automatically created by the new export infrastructure.