@artim-industries/stacktrace-sdk-react-native

React Native SDK for Artim Stacktrace.

Installation

npm install @artim-industries/stacktrace-sdk-react-native

(npm install react-native-svg)

Usage

import { ArtimStacktrace } from '@artim-industries/stacktrace-sdk-react-native'

ArtimStacktrace.init({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  environment: 'production',
  release: '1.0.0',
})

ArtimStacktrace.captureMessage('Hello from React Native')

API

• init(config)
• captureException(error, level)
• captureNativeException(payload, level)
• captureMessage(message, level)
• setUser(user)
• identify(fn)
• ArtimErrorBoundary

Native error tracking

Für native Fehler brauchst du eine zusätzliche native Brücke in iOS/Android:

• init(config) startet den JS-ErrorHandler und installiert automatisch den nativen Handler, sofern das native Modul vorhanden ist
• captureNativeException(payload) kann von einem nativen Modul aufgerufen werden, wenn ein Crash oder eine native Ausnahme auftritt

Die Payload sollte mindestens enthalten:

{
  message: string
  stacktrace: string[]
  level: 'error' | 'warning' | 'fatal'
  native: true
  exceptionType?: string
  osName?: string
  osVersion?: string
  threadName?: string
  extra?: Record<string, any>
}

ArtimStacktrace schickt diese Daten dann wie normale Fehler an den Backend-Endpunkt.

Native Auto-Capture

Die Bibliothek liefert native Auto-Capture-Unterstützung für iOS und Android. Dabei werden native Crash-Handler installiert und native Ausnahmen automatisch an den Artim Stacktrace-Endpunkt gesendet.

JS Initialisierung

ArtimStacktrace.init({ enableNativeErrors: true }) startet den JS-Error-Handler und ruft zusätzlich das native Modul ArtimStacktraceNative.installNativeHandler(config) auf.

Das ist ausreichend für native Errors, die nach dem Laden der React Native-Engine passieren.

iOS (früher Install-Pfad)

Für echte Startup-Crash-Abdeckung unter iOS sollte der native Handler so früh wie möglich installiert werden, also im App-Startcode, bevor die React Native-UI geladen wird.

1. Füge den nativen Header zur Bridging Header-Datei hinzu:

#import <ArtimStacktraceSdkReactNative/ArtimStacktraceNative.h>

2. Installiere den Handler in AppDelegate.swift vor factory.startReactNative(...):

private func installArtimStacktraceNativeHandler() {
  let config: [String: Any] = [
    "apiKey": "your-api-key",
    "endpoint": "https://stacktrace-backend.artim-industries.com/api/events",
    "environment": "production",
    "release": "1.0.0",
    "platform": "react-native",
  ]

  let module = ArtimStacktraceNative()
  module.installNativeHandler(config)
}

3. Rufe installArtimStacktraceNativeHandler() in application(_:didFinishLaunchingWithOptions:) auf.

Das sorgt dafür, dass native Abstürze wie fatalError oder frühzeitige Objective-C-Ausnahmen ebenfalls erfasst werden.

Android

Unter Android wird der native Handler durch das native Modul installiert, wenn ArtimStacktrace.init(...) ausgeführt wird und das native Modul geladen wurde.

Das ist häufig ausreichend für native Fehler nach dem Start der React Native-Engine.

Für einen noch früheren Schutz, z. B. vor JS-Bundle-Initialisierung, solltest du den Handler direkt in MainApplication.java oder in der Android-Application.onCreate()-Methode installieren, bevor die React Native-Instanz erstellt wird.

In diesem Fall muss der Handler ähnlich wie im SDK konfiguriert werden:

• Thread.setDefaultUncaughtExceptionHandler(...)
• Erstelle und sende das Payload an denselben Backend-Endpunkt

Manuelle native Übergabe

Falls du zusätzliche native Fehler manuell erfassen möchtest, kannst du das native Modul ebenfalls direkt verwenden:

import { ArtimStacktrace } from '@artim-industries/stacktrace-sdk-react-native'

ArtimStacktrace.captureNativeException({
  message: 'Native error from Android/iOS',
  stacktrace: ['line 1', 'line 2'],
  level: 'fatal',
  native: true,
  exceptionType: 'NullPointerException',
  osName: 'Android',
  osVersion: '14',
  threadName: 'main',
})

Error boundary

// providers/ErrorProvider.tsx

"use client";

import { useRef } from "react";
import { ArtimErrorBoundary } from "@artim-industries/stacktrace-sdk-react-native";
import { ArtimStacktrace } from "@artim-industries/stacktrace-sdk-react-native";
import { router } from "expo-router";
import { Linking } from "react-native";
import AsyncStorage from "@react-native-async-storage/async-storage";

export default function ErrorProvider({
  children,
  pathname,
}: {
  children: React.ReactNode;
  pathname?: string;
}) {
  const initialized = useRef(false);

  if (typeof window !== "undefined" && !initialized.current) {
    ArtimStacktrace.init({
      apiKey: "your_api_key",
      environment: "production",
      release: "1.0.0",
    });
    initialized.current = true;
  }

  const onContactSupport = () => {
    // for example

    Linking.openURL("https://support.artim-industries.com");
  };

  const onClearCache = async () => {
    // for example

    await AsyncStorage.clear();
    router.reload();
  };

  const onSignOut = async () => {
    // for example

    await AsyncStorage.clear();
    router.push("/splash");
  };

  return (
    <ArtimErrorBoundary
      pathname={pathname}
      onContactSupport={onContactSupport}
      onClearCache={onClearCache}
      onSignOut={onSignOut}
      errorComponent={<h1> Hello from Custom Error Component </h1>}
    >
      {children}
    </ArtimErrorBoundary>
  );
}

ArtimErrorBoundary fängt Rendering- und Lifecycle-Fehler in React Native-Komponenten ab und meldet sie an Artim Stacktrace. Du kannst per errorComponent ein eigenes Error-Page-Design übergeben.