Web için Crashlytics'i kullanmaya başlama

Platform seçin:

iOS+ Android Android NDK Web Flutter Unity

Önizleme: Web uygulamaları için Crashlytics, bir önizleme sürümüdür. Önizleme sürümü, herhangi bir HDS'ye veya kullanımdan kaldırma politikasına tabi değildir ve geriye dönük uyumsuzluk gösterecek şekilde değiştirilebilir.

Bu kılavuzda, web uygulamanızda Firebase Crashlytics kullanmaya nasıl başlayacağınız açıklanmaktadır.

Uygulamanızda Firebase Crashlytics SDK'sını ayarladıktan sonra Firebase Console'da kapsamlı kilitlenme raporları alabilirsiniz. Web uygulamaları için Crashlytics ile hatalarla ilgili raporlar alırsınız.

Önemli: Web uygulamaları için Crashlytics desteği önümüzdeki birkaç gün içinde kullanıma sunulacak. Deneyimi Firebase konsolunda henüz görmüyorsanız kısa süre sonra tekrar kontrol edin.

Başlamadan önce

Crashlytics kurulumu için hem Firebase konsolunda hem de IDE'nizde görevler (ör. uygulamanızın Firebase yapılandırmasını ve Crashlytics SDK'sını ekleme) yapmanız gerekir. Kurulumu tamamlamak için test amaçlı bir kilitlenme oluşturarak ilk kilitlenme raporunuzu Firebase'e göndermeniz gerekir.

Web uygulamanızda Crashlytics özelliğini manuel olarak ayarlamak için aşağıdaki ön koşulları tamamladığınızdan emin olun:

• Henüz yoksa bir Firebase projesi ve Firebase uygulaması oluşturun. Henüz yapmadıysanız Firebase'i JavaScript projenize ekleyin.

• Hesabınızın projenizde Sahip izinlerine sahip olduğundan emin olun. Gerekli API'leri ve IAM rollerini etkinleştirmek için bu gereklidir.

• Firebase projenizin kullandıkça öde Blaze fiyatlandırma planında olduğundan emin olun. Web için Crashlytics, telemetri depolama alanı için Cloud Logging ve kaynak eşleme depolama alanı için Cloud Storage kullanır. Bunlar, ücretsiz katmanı olan ücretli ürünlerdir. Logging fiyatlandırması ve Cloud Storage fiyatlandırması hakkında daha fazla bilgi edinin.

1. adım: Web uygulamanız için Crashlytics özelliğini etkinleştirin.

Web için Crashlytics; Cloud Logging, Error Reporting ve Cloud Storage'yi kullandığından bu API'leri etkinleştirmeniz ve projeniz için izinleri yapılandırmanız gerekir. Firebase konsolunu veya Firebase KSA'yı kullanarak web uygulamanız için Crashlytics özelliğini etkinleştirebilirsiniz.

Firebase konsolunu kullanma

1. Firebase konsolunda DevOps & Engagement (DevOps ve Etkileşim) > Crashlytics dashboard (kontrol paneli) bölümüne gidin.

2. Sayfanın üst kısmındaki açılır seçiciden web uygulamanızı seçin.

3. Crashlytics ayarla'yı tıklayın ve ekrandaki talimatları uygulayın.

Firebase CLI'yı kullanma

Önemli: Web uygulamaları için Crashlytics desteği önümüzdeki birkaç gün içinde kullanıma sunulacak olsa da kurulum için Firebase konsolunu kullanmanızı öneririz. Crashlytics uygulamasını ayarlamak için şu anda Firebase CLI'yı kullanıyorsanız kilitlenmelerinizi bu haftanın ilerleyen günlerine kadar Crashlytics kontrol panelinde göremeyebilirsiniz.

Projenizi terminalden yapılandırmayı veya yapay zeka kodlama aracısı kullanmayı tercih ediyorsanız Firebase CLI'yı kullanabilirsiniz:

1. Firebase CLI v15.35.0 veya sonraki bir sürümün yüklü olduğundan ve kimliğinizin doğrulandığından (firebase login) emin olun. Firebase CLI'yı nasıl yükleyeceğinizi veya güncelleyeceğinizi öğrenin.

2. Web uygulamanız için Crashlytics kurulumu yapmak üzere aşağıdaki komutu çalıştırın:

   firebase crashlytics:setup \
     --app FIREBASE_APP_ID \
     --project PROJECT_ID
   

   Bu komut aşağıdaki kurulum adımlarını gerçekleştirir:

   • Projenizin kullandıkça öde Blaze fiyatlandırma planında olduğunu doğrular ve gerekirse yükseltme yapmanızı ister.

   • Gerekli Crashlytics ve telemetri API'lerini etkinleştirir (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com ve clienttelemetry.googleapis.com).

   • Web uygulamanızın API anahtarında API kısıtlamaları varsa izin verilen API'lerine clienttelemetry.googleapis.com ekler.

   • Web uygulamanız için Crashlytics telemetri ayarlarını yapılandırır.

   • Etkileşimli olarak çalıştırıldığında, yeni ve gerilemiş sorunlar için e-posta uyarılarını etkinleştirmenizi ister.

2. adım: SDK'yı uygulamanıza ekleyin ve ilk kullanıma hazırlayın

1. Crashlytics SDK'sını yükleyin:

   npm install firebase
   

2. FirebaseApp örneğinizi başlatın:

   Tekil başlatmayı kullanmak için merkezi bir yapılandırma yardımcı programı dosyası oluşturun. Firebase uygulama yapılandırma değerlerinizi bulmak için Firebase konsolunda Proje ayarları > Genel sayfasına gidin, Uygulamalarınız kartına gidin ve web uygulamanızı seçin.

   // src/lib/firebase.ts
   import { initializeApp, getApps, getApp } from '@firebase/app';
   
   const firebaseConfig = {
     apiKey: "API_KEY",
     authDomain: "AUTH_DOMAIN",
     projectId: "PROJECT_ID",
     storageBucket: "STORAGE_BUCKET",
     messagingSenderId: "MESSAGING_SENDER_ID",
     appId: "FIREBASE_APP_ID"
   };
   
   // Guarantee singleton initialization across renders or module refreshes
   export const app = getApps().length === 0
     ? initializeApp(firebaseConfig)
     : getApp();
   

3. adım: Çerçeveniz için otomatik hata yakalamayı yapılandırın

Hem otomatik çerçeve hata alıcıları hem de manuel izleyiciler paylaşılan FirebaseApp örneğinizi kullanır. Otomatik hata yakalamayı yapılandırmak için çerçevenizi seçin:

Angular

src/app/app.config.ts içinde uygulamanızın sağlayıcılarına provideCrashlytics(() => app) ekleyerek Angular global hata yakalama çalışma zamanı ve otomatik rota izleme ile entegre edin:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app)
  ]
};

Not: provideCrashlytics, yakalanmayan bölge kilitlenmelerini (Zone.js) izlemek için özel bir ErrorHandler kaydeder ve tam URL'leri günlüğe kaydetmek yerine dinamik rotalar (ör. /dashboard/user/:id) oluşturmak için dahili Router örneklerini kullanır. Böylece telemetri, kimliği tanımlayabilecek bilgilerden arındırılmış olur.

Next.js

Next.js 15.3 ve sonraki sürümler (önerilir): İstemci araçları (instrumentation-client.ts)

Next.js 15.3 ve sonraki sürümler, instrumentation-client.ts (veya instrumentation-client.js) aracılığıyla yerel istemci tarafı araçları içerir. Next.js, React hidrasyonu başlamadan önce bu dosyayı tarayıcıda yürütür.

src/instrumentation-client.ts (veya src/ dizini kullanmıyorsanız proje kökünüzde instrumentation-client.ts) oluşturun ve Crashlytics'yi başlatın:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app);

Bu tek dosya, React hidrasyonundan önce Crashlytics başlatır ve src/app/layout.tsx veya herhangi bir React bileşeninde değişiklik yapmadan global hata dinleyicilerini (error ve unhandledrejection) otomatik olarak kaydeder.

Next.js < 15.3: İstemci tarafı (App Router düzeni)

15.3'ten önceki Next.js sürümlerinde layout.tsx varsayılan olarak bir sunucu bileşenidir. FirebaseApp serileştirilemediğinden <FirebaseCrashlytics> (Crashlytics öğesini ilk kullanıma hazırlamak ve yakalanmayan hataları yakalamak için @firebase/crashlytics/react öğesinden) öğesini 'use client' yönergesiyle işaretlenmiş bir istemci bileşenine (ör. src/components/CrashlyticsProvider.tsx) sarmalayın:

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics firebaseApp={app} />
      {children}
    </>
  );
}

Ardından kök düzeninizi <CrashlyticsProvider> ile sarmalayın:

// src/app/layout.tsx
import React from 'react';
import { CrashlyticsProvider } from '../components/CrashlyticsProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CrashlyticsProvider>
          {children}
        </CrashlyticsProvider>
      </body>
    </html>
  );
}

React (React Router olmadan)

Kök uygulama bileşeninizi (genellikle src/App.tsx veya src/main.tsx) <FirebaseCrashlytics> hata sınırı bileşeniyle sarmalayın. Bu, tarayıcıdan ve React kullanıcı arayüzünden gelen işlenmemiş retleri ve istisnaları işleyen global alıcı görevi görür. Tüm alt bileşen hiyerarşilerini sarmalar ve yakalanmayan istisnaları veya yönlendirme hatalarını otomatik olarak yakalar:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

export default function App({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics firebaseApp={app}>
      {children}
    </FirebaseCrashlytics>
  );
}

React Router (v6+)

React Router v6+ kullanıyorsanız React Router'ın <Routes> kapsayıcısını <CrashlyticsRoutes> ile değiştirin. Bu sayede, rotalar genelindeki hata sınırları otomatik olarak eşlenir ve hatalar, /profile/:userId gibi şablonlu yol adları kullanılarak izlenir:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes firebaseApp={app}>
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

Uygulamanız TanStack Router kullanıyorsa Crashlytics'i getCrashlytics(app) ile ilk kullanıma hazırlayın ve varsayılan hata kaydını doğrudan yönlendirici örneği yapılandırmanıza (defaultOnCatch) ekleyin:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app);

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

Not: getCrashlytics(app) çağrısı, yakalanmayan pencere hataları ve işlenmeyen promise retleri için global dinleyicileri otomatik olarak kaydeder. defaultOnCatch ise TanStack Router'da yönlendirme ve bileşen oluşturma sırasında yakalanan hataları yakalar.

(İsteğe bağlı) 4. adım: Uygulama sürümü oluşturmayı ayarlayın

Gerilemeleri belirli dağıtımlara ayırabilmeniz için web uygulaması derlemelerinize net bir sürüm dizesi eklemeniz önemle tavsiye edilir. Çerçeveniz için Crashlytics SDK'sını başlatırken appVersion değerini CrashlyticsOptions içinde iletin (sürüm dizesi veya derleme zamanı ortam değişkeni kullanarak, örneğin process.env.NEXT_PUBLIC_APP_VERSION ya da import.meta.env.VITE_APP_VERSION):

Angular

src/app/app.config.ts içindeki provideCrashlytics yöntemine ikinci bağımsız değişken olarak appVersion değerine sahip bir CrashlyticsOptions nesnesi iletin:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app, {
      appVersion: 'APP_VERSION'
    })
  ]
};

Next.js

Next.js 15.3 ve sonraki sürümler (önerilir): İstemci araçları (instrumentation-client.ts)

src/instrumentation-client.ts içindeki getCrashlytics yöntemine ikinci bağımsız değişken olarak appVersion değerine sahip bir CrashlyticsOptions nesnesi iletin:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

Next.js < 15.3: İstemci tarafı (App Router düzeni)

src/components/CrashlyticsProvider.tsx içinde <FirebaseCrashlytics> için appVersion ile crashlyticsOptions kartı:

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      />
      {children}
    </>
  );
}

React (React Router olmadan)

src/App.tsx içinde <FirebaseCrashlytics> için appVersion ile crashlyticsOptions kartı:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics
      firebaseApp={app}
      crashlyticsOptions={crashlyticsOptions}
    >
      {children}
    </FirebaseCrashlytics>
  );
}

React Router (v6+)

src/App.tsx içinde <CrashlyticsRoutes> için appVersion ile crashlyticsOptions kartı:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      >
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

getCrashlytics işlevine ikinci bağımsız değişken olarak appVersion içeren bir CrashlyticsOptions nesnesi iletin:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

5. adım: Test amaçlı kilitlenme oluşturun

Crashlytics kurulumunu tamamlamak ve Firebase konsolunun Crashlytics kontrol panelinde ilk verileri görmek için test amaçlı bir kilitlenme zorlamanız gerekir.

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

   React, Next.js veya Angular uygulamanıza tıklandığında çalışma zamanı hatası veren bir test düğmesi ya da rota tetikleyicisi ekleyin:

   // Trigger an unhandled exception on button click or route load
   function handleTestCrash() {
     throw new Error("Crashlytics Web SDK Test Unhandled Error!");
   }
   

   <FirebaseCrashlytics> (React veya Next.js), provideCrashlytics (Angular) ya da <CrashlyticsRoutes> (React Router) ile otomatik hata yakalamayı yapılandırdıysanız bu hatanın oluşturulması, istisnayı otomatik olarak yakalar ve yüklenmek üzere planlar.

2. Uygulamanızı derleyip çalıştırın, ardından test hatasını tetikleyerek uygulamanızın ilk kilitlenme raporunu Firebase'e göndermesini sağlayın.

3. Test kilitlenme raporunuzu kontrol etmek için Firebase konsolunda DevOps & Engagement > Crashlytics dashboard (DevOps ve Etkileşim > kontrol paneli) bölümüne gidin:

   1. Sayfanın üst kısmındaki açılır seçiciden web uygulamanızı seçin.

   2. Sayfayı yenileyin. Test istisnanız birkaç dakika içinde Sorunlar tablosunda görünür.

Konsolu yenilediyseniz ve beş ila on dakika sonra test kilitlenmesini hâlâ görmüyorsanız Kurulumunuzla ilgili sorunları giderme başlıklı makaleyi inceleyin.

Crashlytics artık web uygulamanızı hatalara karşı izliyor. Tüm raporlarınızı ve istatistiklerinizi görüntüleyip incelemek için Crashlytics kontrol panelini ziyaret edin.

Sonraki adımlar

• Okunabilir kilitlenme raporları alın: Üretim yığın izlemelerinizin orijinal dosya adlarını ve satır numaralarını göstermesi için otomatik kaynak haritası (.js.map) yüklemeyi ayarlayın.
• Kilitlenme raporlarını özelleştirme: İşlenen istisnaları bildirme, özel anahtarlar ekleme, telemetri kayıtlarını zorla temizleme ve örneklemeyi yapılandırma hakkında bilgi edinin.