All Skills > SDK Setup > React Native SDK

Sentry React Native SDK

React Native または Expo プロジェクトをスキャンし、完全な Sentry セットアップ（エラーモニタリング、トレーシング、プロファイリング、セッションリプレイ、ログなど）をガイドする独創的なウィザード。

このスキルを呼び出すタイミング

• ユーザーが RN または Expo アプリで「Sentry を React Native に追加」または「Sentry をセットアップ」するよう要求する
• ユーザーが React Native でエラーモニタリング、トレーシング、プロファイリング、セッションリプレイ、またはログを希望する
• ユーザーが @sentry/react-native、モバイルエラートラッキング、または Expo の Sentry に言及する
• ユーザーが iOS/Android でのネイティブクラッシュ、ANR、またはアプリハングをモニタリングしたい

注記: 以下の SDK バージョンと API は、執筆時の現在の Sentry ドキュメント（@sentry/react-native ≥6.0.0、推奨最小 ≥8.0.0）を反映しています。 実装する前に、常に docs.sentry.io/platforms/react-native/ を確認してください。

---

フェーズ 1: 検出

推奨事項を提示する前に、これらのコマンドを実行してプロジェクトを理解してください：

# プロジェクトタイプと既存の Sentry を検出
cat package.json | grep -E '"(react-native|expo|@expo|@sentry/react-native|sentry-expo)"'

# Expo マネージド vs ベア vs Vanilla RN を区別
ls app.json app.config.js app.config.ts 2>/dev/null
cat app.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('Expo managed' if 'expo' in d else 'Bare/Vanilla')" 2>/dev/null

# Expo SDK バージョンを確認（重要：@sentry/react-native 用に Expo SDK 50+ が必須）
cat package.json | grep '"expo"'

# ナビゲーション ライブラリを検出
grep -E '"(@react-navigation/native|react-native-navigation)"' package.json

# 状態管理を検出（Redux → ブレッドクラム統合を利用可能）
grep -E '"(redux|@reduxjs/toolkit|zustand|mobx)"' package.json

# 既存の Sentry 初期化を確認
grep -r "Sentry.init" src/ app/ App.tsx App.js _layout.tsx 2>/dev/null | head -5

# Hermes を検出（ソースマップ処理に影響）
cat android/app/build.gradle 2>/dev/null | grep -i hermes
cat ios/Podfile 2>/dev/null | grep -i hermes

# Expo Router を検出
ls app/_layout.tsx app/_layout.js 2>/dev/null

# バックエンドをクロスリンク用に検出
ls backend/ server/ api/ 2>/dev/null
find . -maxdepth 3 \( -name "go.mod" -o -name "requirements.txt" -o -name "Gemfile" -o -name "package.json" \) 2>/dev/null | grep -v node_modules | head -10

何を確認するか：

質問	影響
package.json に expo があるか？	Expo パス（config プラグイン + getSentryExpoConfig）vs ベア/Vanilla RN パス
Expo SDK ≥50？	@sentry/react-native を直接使用；古い場合は sentry-expo（レガシー、使用しないこと）
app.json に "expo" キーがあるか？	マネージド Expo — ウィザードが最もシンプル；config プラグインがすべてのネイティブ設定を処理
app/_layout.tsx が存在するか？	Expo Router プロジェクト — init は _layout.tsx に配置
package.json に @sentry/react-native が既にあるか？	インストールをスキップして、機能設定に進む
@react-navigation/native が存在するか？	reactNavigationIntegration を推奨してスクリーントラッキング用
react-native-navigation が存在するか？	reactNativeNavigationIntegration（Wix）を推奨
バックエンドディレクトリが検出されるか？	フェーズ 4 のクロスリンクをトリガー

---

フェーズ 2: 推奨

見つけたものに基づいて具体的な推奨を提示します。オープンエンドな質問はしないでください — 提案を先導してください：

推奨（コアカバレッジ — 常にセットアップ）：

• ✅ エラーモニタリング — JS 例外、ネイティブクラッシュ（iOS + Android）、ANR、アプリハングをキャプチャ
• ✅ トレーシング — モバイルパフォーマンスは重要です；ナビゲーション、アプリ開始、ネットワークリクエストを自動計測
• ✅ セッションリプレイ — モバイルリプレイはスクリーンショットとタッチイベントをキャプチャしてユーザー問題をデバッグ

オプション（強化された可観測性）：

• ⚡ プロファイリング — iOS 上の CPU プロファイリング（JS プロファイリングはクロスプラットフォーム）；本番環境での低オーバーヘッド
• ⚡ ログ — Sentry.logger.* 経由の構造化ログ；トレースへのリンクで完全なコンテキストを得られる
• ⚡ ユーザーフィードバック — アプリから直接ユーザーが送信したバグレポートを収集

推奨ロジック：

機能	推奨対象
エラーモニタリング	常に — モバイルアプリの交渉不可能なベースライン
トレーシング	モバイルに対して常に — アプリ開始、ナビゲーション、ネットワークレイテンシが重要
セッションリプレイ	ユーザー向けの本番環境アプリ；ユーザーが報告した問題を視覚的にデバッグ
プロファイリング	パフォーマンス上重要なスクリーン、起動時間の懸念、または本番環境のパフォーマンス調査
ログ	アプリが構造化ログを使用するか、Sentry でログからトレースへの相関を望む
ユーザーフィードバック	ベータ版またはカスタマー向けのアプリで、ユーザーが送信したバグレポートを希望

提案：「[Expo マネージド / ベア RN] アプリの場合、エラーモニタリング + トレーシング + セッションリプレイのセットアップをお勧めします。プロファイリングとログも追加したいですか？」

---

フェーズ 3: ガイド

セットアップパスを決定

プロジェクトタイプ	推奨セットアップ	複雑性
Expo マネージド（SDK 50+）	ウィザード CLI またはコンフィグプラグイン手動設定	低 — ウィザードがすべてを実行
Expo ベア（SDK 50+）	ウィザード CLI を推奨	中 — iOS/Android 設定を処理
Vanilla React Native（0.69+）	ウィザード CLI を推奨	中 — Xcode + Gradle を処理
Expo SDK <50	sentry-expo（レガシー）を使用	レガシードキュメントを参照

---

パス A: ウィザード CLI（すべてのプロジェクトタイプに推奨）

これは自分で実行する必要があります — ウィザードはログイン用にブラウザを開き、エージェントが処理できない対話的入力が必要です。ターミナルにコピー & ペーストしてください：

npx @sentry/wizard@latest -i reactNative

これはログイン、組織/プロジェクト選択、SDK インストール、ネイティブ設定、ソースマップアップロード、および Sentry.init() を処理します。ここに何を作成/変更するかを示します：

ファイル	アクション	目的
package.json	@sentry/react-native をインストール	コア SDK
metro.config.js	@sentry/react-native/metro シリアライザを追加	ソースマップ生成
app.json	@sentry/react-native/expo プラグインを追加（Expo のみ）	ネイティブビルド用の設定プラグイン
App.tsx / _layout.tsx	Sentry.init() と Sentry.wrap() を追加	SDK 初期化
ios/sentry.properties	組織/プロジェクト/トークンを保存	iOS ソースマップ + dSYM アップロード
android/sentry.properties	組織/プロジェクト/トークンを保存	Android ソースマップアップロード
android/app/build.gradle	Sentry Gradle プラグインを追加	Android ソースマップ + proguard
ios/[AppName].xcodeproj	"Bundle RN" ビルドフェーズをラップ + dSYM アップロードを追加	iOS シンボルアップロード
.env.local	SENTRY_AUTH_TOKEN	認証トークン（.gitignore に追加）

完了後、戻って 検証 にスキップしてください。

ユーザーがウィザードをスキップした場合、以下の下部のパス B または C（手動セットアップ）をプロジェクトタイプに基づいて進めます。

---

パス B: 手動 — Expo マネージド（SDK 50+）

ステップ 1 — インストール

npx expo install @sentry/react-native

ステップ 2 — metro.config.js

const { getSentryExpoConfig } = require("@sentry/react-native/metro");
const config = getSentryExpoConfig(__dirname);
module.exports = config;

metro.config.js がまだ存在しない場合：

npx expo customize metro.config.js
# その後、上記で内容を置き換える

ステップ 3 — app.json — Expo コンフィグプラグインを追加

{
  "expo": {
    "plugins": [
      [
        "@sentry/react-native/expo",
        {
          "url": "https://sentry.io/",
          "project": "YOUR_PROJECT_SLUG",
          "organization": "YOUR_ORG_SLUG"
        }
      ]
    ]
  }
}

注記: ネイティブビルド用に SENTRY_AUTH_TOKEN を環境変数として設定してください — バージョン管理にコミットしないでください。

ステップ 4 — Sentry を初期化

Expo Router の場合（app/_layout.tsx）：

import { Stack, useNavigationContainerRef } from "expo-router";
import { isRunningInExpoGo } from "expo";
import * as Sentry from "@sentry/react-native";
import React from "react";

const navigationIntegration = Sentry.reactNavigationIntegration({
  enableTimeToInitialDisplay: !isRunningInExpoGo(), // Expo Go では無効
});

Sentry.init({
  dsn: process.env.EXPO_PUBLIC_SENTRY_DSN ?? "YOUR_SENTRY_DSN",
  sendDefaultPii: true,

  // トレーシング
  tracesSampleRate: 1.0, // 本番環境では 0.1–0.2 に下げる

  // プロファイリング
  profilesSampleRate: 1.0,

  // セッションリプレイ
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,

  // ログ（SDK ≥7.0.0）
  enableLogs: true,

  // ナビゲーション
  integrations: [
    navigationIntegration,
    Sentry.mobileReplayIntegration(),
  ],

  enableNativeFramesTracking: !isRunningInExpoGo(), // 遅い/フリーズフレーム

  environment: __DEV__ ? "development" : "production",
});

function RootLayout() {
  const ref = useNavigationContainerRef();

  React.useEffect(() => {
    if (ref) {
      navigationIntegration.registerNavigationContainer(ref);
    }
  }, [ref]);

  return <Stack />;
}

export default Sentry.wrap(RootLayout);

標準 Expo の場合（App.tsx）：

import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import { isRunningInExpoGo } from "expo";
import * as Sentry from "@sentry/react-native";

const navigationIntegration = Sentry.reactNavigationIntegration({
  enableTimeToInitialDisplay: !isRunningInExpoGo(),
});

Sentry.init({
  dsn: process.env.EXPO_PUBLIC_SENTRY_DSN ?? "YOUR_SENTRY_DSN",
  sendDefaultPii: true,
  tracesSampleRate: 1.0,
  profilesSampleRate: 1.0,
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  enableLogs: true,
  integrations: [
    navigationIntegration,
    Sentry.mobileReplayIntegration(),
  ],
  enableNativeFramesTracking: !isRunningInExpoGo(),
  environment: __DEV__ ? "development" : "production",
});

const navigationRef = createNavigationContainerRef();

function App() {
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        navigationIntegration.registerNavigationContainer(navigationRef);
      }}
    >
      {/* ナビゲーションはここに */}
    </NavigationContainer>
  );
}

export default Sentry.wrap(App);

---

パス C: 手動 — ベア React Native（0.69+）

ステップ 1 — インストール

npm install @sentry/react-native --save
cd ios && pod install

ステップ 2 — metro.config.js

const { getDefaultConfig } = require("@react-native/metro-config");
const { withSentryConfig } = require("@sentry/react-native/metro");

const config = getDefaultConfig(__dirname);
module.exports = withSentryConfig(config, {
  // @sentry-internal/replay をネイティブバンドルから除外するには false に設定（ウェブのみ）。
  // includeWebReplay: true,
  // @sentry-internal/feedback をネイティブバンドルから除外するには false に設定（ウェブのみ）。
  // includeWebFeedback: true,
});

ステップ 3 — iOS: Xcode ビルドフェーズを変更

ios/[AppName].xcodeproj を Xcode で開きます。"Bundle React Native code and images" ビルドフェーズを探して、スクリプトコンテンツを以下に置き換えます：

# RN 0.81.1+
set -e
WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
SENTRY_XCODE="../node_modules/@sentry/react-native/scripts/sentry-xcode.sh"
/bin/sh -c "$WITH_ENVIRONMENT $SENTRY_XCODE"

ステップ 4 — iOS: "Upload Debug Symbols to Sentry" ビルドフェーズを追加

Xcode で新しい Run Script ビルドフェーズを追加します（バンドルフェーズの後）：

/bin/sh ../node_modules/@sentry/react-native/scripts/sentry-xcode-debug-files.sh

ステップ 5 — iOS: ios/sentry.properties

defaults.url=https://sentry.io/
defaults.org=YOUR_ORG_SLUG
defaults.project=YOUR_PROJECT_SLUG
auth.token=YOUR_ORG_AUTH_TOKEN

ステップ 6 — Android: android/app/build.gradle

android {} ブロックの前に追加：

apply from: "../../node_modules/@sentry/react-native/sentry.gradle"

ステップ 7 — Android: android/sentry.properties

defaults.url=https://sentry.io/
defaults.org=YOUR_ORG_SLUG
defaults.project=YOUR_PROJECT_SLUG
auth.token=YOUR_ORG_AUTH_TOKEN

ステップ 8 — Sentry を初期化（App.tsx またはエントリーポイント）

import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import * as Sentry from "@sentry/react-native";

const navigationIntegration = Sentry.reactNavigationIntegration({
  enableTimeToInitialDisplay: true,
});

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  sendDefaultPii: true,
  tracesSampleRate: 1.0,
  profilesSampleRate: 1.0,
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  enableLogs: true,
  integrations: [
    navigationIntegration,
    Sentry.mobileReplayIntegration(),
  ],
  enableNativeFramesTracking: true,
  environment: __DEV__ ? "development" : "production",
});

const navigationRef = createNavigationContainerRef();

function App() {
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        navigationIntegration.registerNavigationContainer(navigationRef);
      }}
    >
      {/* ナビゲーションはここに */}
    </NavigationContainer>
  );
}

export default Sentry.wrap(App);

---

クイックリファレンス: 完全な機能の Sentry.init()

これはすべての機能が有効な推奨開始設定です：

import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  sendDefaultPii: true,

  // トレーシング — 高トラフィック本番環境では 0.1–0.2 に下げる
  tracesSampleRate: 1.0,

  // プロファイリング — トレースされたトランザクションのサブセットで実行
  profilesSampleRate: 1.0,

  // セッションリプレイ — 常にエラーでキャプチャ、全セッションの 10% をサンプル
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,

  // ログ — Sentry.logger.* API を有効化
  enableLogs: true,

  // インテグレーション — モバイルリプレイはオプトイン
  integrations: [
    Sentry.mobileReplayIntegration({
      maskAllText: true,   // デフォルト: true — プライバシー上、デフォルトでテキストをマスク
      maskAllImages: true,
    }),
  ],

  // ネイティブフレームトラッキング（Expo Go では無効）
  enableNativeFramesTracking: true,

  // 環境
  environment: __DEV__ ? "development" : "production",

  // リリース — CI またはビルドシステムから設定
  // release: "my-app@1.0.0+1",
  // dist: "1",
});

// 必須: React レンダリングエラーをキャプチャするためにルートコンポーネントをラップ
export default Sentry.wrap(App);

アプリ開始精度 — Sentry.appLoaded()（SDK ≥8.x）

アプリが root コンポーネントのマウント後に重大な非同期作業を行う場合（例：設定の取得、認証待機）、その作業が完了した後に Sentry.appLoaded() を呼び出します。これはアプリ開始の真の終了を Sentry に通知し、より正確なアプリ開始期間測定を生成します。

// 非同期初期化が完了した後、例えば useEffect またはローディング画面の後に呼び出す：
useEffect(() => {
  fetchConfig().then(() => {
    Sentry.appLoaded();  // アプリ起動フェーズの終了を標記
  });
}, []);

Sentry.appLoaded() を呼び出さない場合、SDK はアプリ開始の終了を自動的に推定します。

---

ナビゲーション設定 — React Navigation（v5+）

import { reactNavigationIntegration } from "@sentry/react-native";
import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";

const navigationIntegration = reactNavigationIntegration({
  enableTimeToInitialDisplay: true,   // 画面ごとに TTID をトラッキング
  routeChangeTimeoutMs: 1_000,        // ルート変更が落ち着くまでの最大待機時間
  ignoreEmptyBackNavigationTransactions: true,
});

// Sentry.init インテグレーション配列に追加
Sentry.init({
  integrations: [navigationIntegration],
  // ...
});

// コンポーネント内：
const navigationRef = createNavigationContainerRef();

<NavigationContainer
  ref={navigationRef}
  onReady={() => {
    navigationIntegration.registerNavigationContainer(navigationRef);
  }}
>

ナビゲーション設定 — Wix React Native Navigation

import * as Sentry from "@sentry/react-native";
import { Navigation } from "react-native-navigation";

Sentry.init({
  integrations: [Sentry.reactNativeNavigationIntegration({ navigation: Navigation })],
  // ...
});

---

ルートコンポーネントをラップ

常にルートコンポーネントをラップしてください — これは React エラー境界を有効にしてコンポーネントツリーレベルでのクラッシュがキャプチャされることを確認します：

export default Sentry.wrap(App);

---

合意された各機能について

一度に 1 つの機能をウォークスルーしてください。各機能の参照ファイルを読み込み、その手順に従ってから、次に進む前に検証します：

機能	リファレンス	読み込むタイミング
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常に（ベースライン）
トレーシングとパフォーマンス	${SKILL_ROOT}/references/tracing.md	モバイルに対して常に（アプリ開始、ナビゲーション、ネットワーク）
プロファイリング	${SKILL_ROOT}/references/profiling.md	パフォーマンス上重要な本番環境アプリ
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	ユーザー向けのアプリ
ログ	${SKILL_ROOT}/references/logging.md	構造化ログ / ログからトレースへの相関
ユーザーフィードバック	${SKILL_ROOT}/references/user-feedback.md	ユーザーが送信したレポートを収集する場合

各機能について：${SKILL_ROOT}/references/<feature>.md を読み、手順に正確に従い、検証します。

---

設定リファレンス

コア Sentry.init() オプション

オプション	タイプ	デフォルト	目的
dsn	string	—	必須。 プロジェクト DSN；空の場合は SDK が無効化されます。環境変数：SENTRY_DSN
environment	string	—	例："production"、"staging"。環境変数：SENTRY_ENVIRONMENT
release	string	—	アプリバージョン、例："my-app@1.0.0+42"。環境変数：SENTRY_RELEASE
dist	string	—	ビルド番号/バリアント識別子（最大 64 文字）。環境変数：SENTRY_DIST
sendDefaultPii	boolean	false	PII を含める：IP アドレス、cookie、ユーザーデータ
sampleRate	number	1.0	エラーイベントサンプリング（0.0–1.0）
maxBreadcrumbs	number	100	イベントごとの最大ブレッドクラム
attachStacktrace	boolean	true	メッセージに自動でスタックトレースを付加
attachScreenshot	boolean	false	エラーでスクリーンショットをキャプチャ（SDK ≥4.11.0）
screenshot	object	—	細粒度のスクリーンショットマスキング；attachScreenshot: true の場合のみ有効。下の スクリーンショットマスキングオプション を参照
attachViewHierarchy	boolean	false	JSON ビュー階層を添付として付加
debug	boolean	false	詳細な SDK 出力。本番環境では使用しないこと
enabled	boolean	true	SDK 全体を無効化（例：テスト用）
ignoreErrors	string[] | RegExp[]	—	これらのパターンに一致するエラーをドロップ
ignoreTransactions	string[] | RegExp[]	—	これらのパターンに一致するトランザクションをドロップ
maxCacheItems	number	30	オフラインでキャッシュされる最大エンベロープ数
defaultIntegrations	boolean	true	すべてのデフォルトインテグレーションを無効化するには false に設定
integrations	array | function	—	インテグレーションを追加またはフィルタリング

スクリーンショットマスキングオプション

attachScreenshot: true の場合、Sentry.init() 内の screenshot キーとして渡される：

Sentry.init({
  attachScreenshot: true,
  screenshot: {
    maskAllText: true,       // デフォルト: true — すべてのテキストノードをマスク
    maskAllImages: true,     // デフォルト: true — すべての画像をマスク
    maskedViewClasses: ['com.mapbox.maps.MapView'],    // 常にこれらのネイティブビュークラスをマスク
    unmaskedViewClasses: ['com.example.SafeView'],     // 常にこれらのネイティブビュークラスを表示
  },
});

サブオプション	タイプ	デフォルト	目的
maskAllText	boolean	true	スクリーンショット内のすべてのテキストノードをマスク
maskAllImages	boolean	true	スクリーンショット内のすべての画像をマスク
maskedViewClasses	string[]	[]	常にマスクするネイティブビュークラス名（Android/iOS）
unmaskedViewClasses	string[]	[]	常に表示するネイティブビュークラス名（Android/iOS）

トレーシングオプション

オプション	タイプ	デフォルト	目的
tracesSampleRate	number	0	トランザクションサンプルレート（0–1）。開発環境では 1.0 を使用
tracesSampler	function	—	トランザクションごとのサンプリング；tracesSampleRate をオーバーライド
tracePropagationTargets	(string | RegExp)[]	[/.*/]	分散トレーシングヘッダーを受け取る API URL
profilesSampleRate	number	0	プロファイリングサンプルレート（トレースされたトランザクションに適用）

ネイティブ / モバイルオプション

オプション	タイプ	デフォルト	目的
enableNative	boolean	true	JS のみの場合は false に設定（ネイティブ SDK なし）
enableNativeCrashHandling	boolean	true	ネイティブハードクラッシュをキャプチャ（iOS/Android）
enableNativeFramesTracking	boolean	—	遅い/フリーズフレームのトラッキング。Expo Go では無効化
enableWatchdogTerminationTracking	boolean	true	OOM キル検出（iOS）
enableAppHangTracking	boolean	true	アプリハング検出（iOS、tvOS、macOS）
appHangTimeoutInterval	number	2	アプリハングとして分類するまでの秒数（iOS）
enableAutoPerformanceTracing	boolean	true	自動パフォーマンス計測
enableNdkScopeSync	boolean	true	Java→NDK スコープ同期（Android）
attachThreads	boolean	false	クラッシュ時にすべてのスレッドを自動付加（Android）
attachAllThreads	boolean	false	すべてのキャプチャイベントにすべてのスレッドの完全スタックトレースを付加（iOS のみ、Cocoa SDK ≥9.9.0 が必須）
autoInitializeNativeSdk	boolean	true	手動ネイティブ初期化の場合は false に設定
onReady	function	—	ネイティブ SDK 初期化後のコールバック

セッションとリリースヘルスオプション

オプション	タイプ	デフォルト	目的
autoSessionTracking	boolean	true	セッショントラッキング（クラッシュなしユーザー/セッション）
sessionTrackingIntervalMillis	number	30000	バックグラウンドの前にセッションが終了するまでの ms

リプレイオプション

オプション	タイプ	デフォルト	目的
replaysSessionSampleRate	number	0	すべてのセッションの記録分数
replaysOnErrorSampleRate	number	0	エラーセッションの記録分数

ログオプション（SDK ≥7.0.0）

オプション	タイプ	目的
enableLogs	boolean	Sentry.logger.* API を有効化
beforeSendLog	function	送信前にログをフィルタリング/変更
logsOrigin	'native' | 'js' | 'all'	ログソースをフィルタリング（SDK ≥7.7.0）

フックオプション

オプション	タイプ	目的
beforeSend	(event, hint) => event | null	JS エラーイベントを変更/ドロップ。⚠️ ネイティブクラッシュに適用されません
beforeSendTransaction	(event) => event | null	トランザクションイベントを変更/ドロップ
beforeBreadcrumb	(breadcrumb, hint) => breadcrumb | null	保存前にブレッドクラムを処理
onNativeLog	(log: { level, component, message }) => void	ネイティブ SDK ログメッセージをインターセプトして JS コンソールに転送。debug: true の場合のみ実行

---

環境変数

変数	目的	注記
SENTRY_DSN	データソース名	dsn オプションからフォールバック
SENTRY_AUTH_TOKEN	ソースマップと dSYM をアップロード	コミットしないこと — CI シークレットを使用
SENTRY_ORG	組織スラッグ	ウィザードと build プラグインで使用
SENTRY_PROJECT	プロジェクトスラッグ	ウィザードと build プラグインで使用
SENTRY_RELEASE	リリース識別子	release オプションからフォールバック
SENTRY_DIST	配布識別子	dist オプションからフォールバック
SENTRY_ENVIRONMENT	環境名	environment オプションからフォールバック
SENTRY_DISABLE_AUTO_UPLOAD	ソースマップアップロードをスキップ	ローカルビルド中は true に設定
EXPO_PUBLIC_SENTRY_DSN	Expo パブリック環境変数（DSN 用）	クライアントバンドルに埋め込み可能
SENTRY_EAS_BUILD_CAPTURE_SUCCESS	EAS build hook：成功ビルドをキャプチャ	EAS シークレットで true に設定
SENTRY_EAS_BUILD_TAGS	EAS build hook：追加タグ JSON	例：{"team":"mobile"}

---

ソースマップとデバッグシンボル

ソースマップとデバッグシンボルは、圧縮されたスタックトレースを読み取り可能なものに変換するものです。正しくセットアップされると、Sentry はスローを投げた正確なソースコード行を表示します。

アップロードの仕組み

プラットフォーム	アップロード内容	タイミング
iOS（JS）	ソースマップ（.map ファイル）	Xcode ビルド中
iOS（ネイティブ）	dSYM バンドル	Xcode アーカイブ / Xcode Cloud 中
Android（JS）	ソースマップ + Hermes .hbc.map	Gradle ビルド中
Android（ネイティブ）	Proguard マッピング + NDK .so ファイル	Gradle ビルド中

Expo: 自動アップロード

@sentry/react-native/expo コンフィグプラグインはネイティブビルド用のアップロードフックを自動設定します。ソースマップは eas build および expo run:ios/android（リリース）中にアップロードされます。

SENTRY_AUTH_TOKEN=sntrys_... npx expo run:ios --configuration Release

手動アップロード（ベア RN）

ソースマップを手動でアップロードする必要がある場合：

npx sentry-cli sourcemaps upload \
  --org YOUR_ORG \
  --project YOUR_PROJECT \
  --release "my-app@1.0.0+1" \
  ./dist

---

デフォルトインテグレーション（自動有効化）

これらのインテグレーションは自動的に有効化されます — 設定は不要です：

インテグレーション	機能
ReactNativeErrorHandlers	ハンドルされない JS 例外と promise 拒否をキャッチ
Release	すべてのイベントにリリース/dist を付加
Breadcrumbs	コンソールログ、HTTP リクエスト、ユーザージェスチャーをブレッドクラムとして記録
HttpClient	HTTP リクエスト/レスポンスのブレッドクラムを追加
DeviceContext	イベントにデバイス/OS/バッテリー情報を付加
AppContext	アプリバージョン、バンドル ID、メモリ情報を付加
CultureContext	ロケールとタイムゾーンを付加
Screenshot	エラーでスクリーンショットをキャプチャ（attachScreenshot: true の場合）
ViewHierarchy	ビュー階層を付加（attachViewHierarchy: true の場合）
NativeLinkedErrors	JS エラーをネイティブクラッシュの対応物にリンク

オプトインインテグレーション

インテグレーション	有効化方法
mobileReplayIntegration()	integrations 配列に追加
reactNavigationIntegration()	integrations 配列に追加
reactNativeNavigationIntegration()	integrations 配列に追加（Wix のみ）
feedbackIntegration()	integrations 配列に追加（ユーザーフィードバックウィジェット；enableShakeToReport でネイティブシェイク検出をサポート）
deeplinkIntegration()	integrations 配列に追加（ディープリンク URL をブレッドクラムとして自動キャプチャ；オプトイン）

Rage タップ検出（TouchEventBoundary）

TouchEventBoundary（アプリルートをラップ）には built-in の rage タップ検出が含まれます。ユーザーが 1 秒以内に同じ要素を 3 回以上タップすると、ui.multiClick ブレッドクラムが放出されてリプレイタイムラインに表示されます。props で設定：

<Sentry.TouchEventBoundary
  enableRageTapDetection={true}   // デフォルト: true — 無効化するには false に設定
  rageTapThreshold={3}            // トリガーに必要なタップ数（デフォルト: 3）
  rageTapTimeWindow={1000}        // 検出ウィンドウ（ms）（デフォルト: 1000）
>
  <App />
</Sentry.TouchEventBoundary>

---

Expo コンフィグプラグインリファレンス

app.json または app.config.js でプラグインを設定：

{
  "expo": {
    "plugins": [
      [
        "@sentry/react-native/expo",
        {
          "url": "https://sentry.io/",
          "project": "my-project",
          "organization": "my-org",
          "note": "ネイティブビルド用に SENTRY_AUTH_TOKEN env 変数を設定"
        }
      ]
    ]
  }
}

または app.config.js（環境変数の内挿を許可）：

export default {
  expo: {
    plugins: [
      [
        "@sentry/react-native/expo",
        {
          url: "https://sentry.io/",
          project: process.env.SENTRY_PROJECT,
          organization: process.env.SENTRY_ORG,
        },
      ],
    ],
  },
};

---

EAS Build Hooks

Expo Application Services（EAS）ビルドを Sentry でモニタリング。SDK は 3 つのバイナリフック — sentry-eas-build-on-complete、sentry-eas-build-on-error、sentry-eas-build-on-success — を備えており、ビルドイベントを Sentry エラーまたはメッセージとしてキャプチャします。

ステップ 1 — package.json でフックを登録

{
  "scripts": {
    "eas-build-on-complete": "sentry-eas-build-on-complete"
  }
}

eas-build-on-complete を使用して、失敗と（オプション）成功の両方を 1 つのフックでキャプチャします。または、独立した制御を望む場合は eas-build-on-error または eas-build-on-success を個別に使用します。

ステップ 2 — EAS シークレットで SENTRY_DSN を設定

eas secret:create --name SENTRY_DSN --value "https://...@sentry.io/..."

フックはビルド環境から SENTRY_DSN を読み取ります — アプリの .env と同じではありません。

オプションの環境変数：

変数	目的
SENTRY_EAS_BUILD_CAPTURE_SUCCESS	成功ビルドもキャプチャするには true に設定（デフォルト：エラーのみ）
SENTRY_EAS_BUILD_TAGS	追加タグ JSON、例：{"team":"mobile","channel":"production"}
SENTRY_EAS_BUILD_ERROR_MESSAGE	失敗ビルド用のカスタムエラーメッセージ
SENTRY_EAS_BUILD_SUCCESS_MESSAGE	成功ビルド用のカスタムメッセージ

仕組み： フックスクリプトは EAS npm lifecycle hook です。EAS はビルドプロセスの終了時に package.json スクリプト（eas-build-on-* にマッチ）を呼び出します。スクリプトは @expo/env、.env、または .env.sentry-build-plugin から env を読み込みます — EAS シークレットが既に環境にある場合はオーバーライトしません。

---

本番環境設定

本番環境に出荷する前に、サンプルレートを下げて設定を強化：

Sentry.init({
  dsn: process.env.EXPO_PUBLIC_SENTRY_DSN,
  environment: __DEV__ ? "development" : "production",

  // 高トラフィック本番環境でトランザクションの 10–20% をトレース
  tracesSampleRate: __DEV__ ? 1.0 : 0.1,

  // トレースされたトランザクションの 100% をプロファイル（プロファイリングは常にトレーシングのサブセット）
  profilesSampleRate: 1.0,

  // すべてのエラーセッションをリプレイ、通常セッションの 5% をサンプル
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: __DEV__ ? 1.0 : 0.05,

  // 正確なソースマップ検索用にリリースと dist を設定
  release: "my-app@" + Application.nativeApplicationVersion,
  dist: String(Application.nativeBuildVersion),

  // 本番環境ではデバッグログを無効化
  debug: __DEV__,
});

---

検証

セットアップ後、Sentry がイベントを受け取っていることをテスト：

// クイックテスト — スロー、Sentry.wrap(App) がキャッチ
<Button
  title="Test Sentry Error"
  onPress={() => {
    throw new Error("My first Sentry error!");
  }}
/>

// または手動でキャプチャ
<Button
  title="Test Sentry Message"
  onPress={() => {
    Sentry.captureMessage("Sentry test message", "info");
  }}
/>

Sentry ダッシュボードを確認：

• Issues → テストエラーが数秒以内に表示されるはず
• Traces → 子スパンを含む "main" トランザクションを探す
• Replays → ネイティブビルド後（Expo Go ではない）のアプリインタラクション後にセッション記録を表示
• Logs → enableLogs: true の場合、構造化ログエントリ

⚠️ Expo Go の制限： ネイティブクラッシュ、セッションリプレイ、遅い/フリーズフレーム、TTID、TTFD はネイティブビルド（eas build または expo run）でのみ動作します。Expo Go は JS のみモードで実行されます。enableNativeFramesTracking: !isRunningInExpoGo() を設定して警告を避けてください。

何も表示されない場合：

1. debug: true を設定 — SDK が Metro コンソールにログ
2. DSN が正しく、Sentry プロジェクトが存在することを確認
3. Sentry.wrap(App) がルートコンポーネントに適用されていることを確認
4. ネイティブクラッシュの場合、リリースビルドを構築（デバッグモードでのクラッシュは転送されない可能性）

---

フェーズ 4: クロスリンク

React Native セットアップ完了後、Sentry カバレッジが不足しているバックエンドまたはウェブフロントエンドを確認：

# 隣接するバックエンドディレクトリ
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
ls ../backend/package.json ../server/package.json 2>/dev/null

# 同じまたは兄弟リポジトリのウェブフロントエンド
ls ../web ../frontend ../dashboard 2>/dev/null
cat ../web/package.json ../frontend/package.json 2>/dev/null | grep -E '"react"|"svelte"|"next"'

# OpenTelemetry を確認（分散トレーシング相互運用用）
grep -r "opentelemetry" ../backend/go.mod ../server/requirements.txt 2>/dev/null

Sentry なしのバックエンドまたはウェブフロントエンドが存在する場合、一致するスキルを提案：

検出内容	提案スキル
Go バックエンド（go.mod）	sentry-go-sdk
Python バックエンド（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby バックエンド（Gemfile）	sentry-ruby-sdk
Node.js バックエンド（Express、Fastify など）	@sentry/node — docs.sentry.io/platforms/javascript/guides/express/ を参照
React / Next.js ウェブ	sentry-react-sdk
Svelte / SvelteKit ウェブ	sentry-svelte-sdk

分散トレーシング設定 — バックエンドスキルが追加される場合、React Native の tracePropagationTargets を設定して API にトレースコンテキストを伝播：

Sentry.init({
  tracePropagationTargets: [
    "localhost",
    /^https:\/\/api\.yourapp\.com/,
  ],
  // ...
});

これにより、モバイルトランザクションが Sentry ウォーターフォールビューのバックエンドトレースにリンクされます。

---

トラブルシューティング

問題	解決策
Sentry にイベントが表示されない	debug: true を設定、Metro/Xcode コンソール for SDK エラーを確認；DSN が正しいことを確認
pod install が失敗	cd ios && pod install --repo-update を実行；CocoaPods バージョンを確認
iOS ビルドが Sentry スクリプトで失敗	"Bundle React Native code and images" スクリプトが置き換えられた（追加されたのではなく）ことを確認
Android ビルドが sentry.gradle 追加後に失敗	apply from 行が build.gradle の android {} ブロックの前にあることを確認
Android Gradle 8+ 互換性の問題	sentry-android-gradle-plugin ≥4.0.0 を使用；SDK の sentry.gradle バージョンを確認
ソースマップがアップロードされない	sentry.properties に有効な auth.token があることを確認；ビルドログで sentry-cli 出力を確認
Sentry でソースマップが解決されない	Sentry.init() の release と dist がアップロードされたバンドルメタデータと一致することを確認
Hermes ソースマップが動作しない	Hermes は .hbc.map を放出 — Gradle プラグインがこれを自動処理；sentry.gradle が適用されていることを確認
セッションリプレイが記録されない	ネイティブビルドを使用する必要があります（Expo Go ではない）；mobileReplayIntegration() が integrations にあることを確認
リプレイが空白/黒いスクリーンを表示	maskAllText/maskAllImages 設定がプライバシー要件と一致することを確認
遅い/フリーズフレームがトラッキングされない	enableNativeFramesTracking: true を設定、ネイティブビルド（Expo Go ではない）を確認
TTID / TTFD が表示されない	reactNavigationIntegration() で enableTimeToInitialDisplay: true が必須、ネイティブビルド上
セットアップ後アプリが起動時にクラッシュ	おそらくネイティブ初期化エラー — Xcode/Logcat ログを確認；enableNative: false を試して分離
Expo SDK 49 またはそれ以前	sentry-expo（レガシーパッケージ）を使用；@sentry/react-native は Expo SDK 50+ が必須
isRunningInExpoGo インポートエラー	expo パッケージからインポート：import { isRunningInExpoGo } from "expo"
Xcode ビルド中にノードが見つからない	Xcode ビルドフェーズに export NODE_BINARY=$(which node) を追加、またはシンボリンク：ln -s $(which node) /usr/local/bin/node
Expo Go ネイティブ機能について警告	isRunningInExpoGo() ガードを使用：enableNativeFramesTracking: !isRunningInExpoGo()
beforeSend がネイティブクラッシュで発火しない	予想動作 — beforeSend は JS レイヤーエラーのみをインターセプト；ネイティブクラッシュはバイパス
Android 15+（16KB ページサイズ）クラッシュ	@sentry/react-native ≥6.3.0 にアップグレード
ダッシュボードにトランザクションが多すぎる	tracesSampleRate を 0.1 に下げる、または tracesSampler でヘルスチェックをドロップ
SENTRY_AUTH_TOKEN がアプリバンドルに露出	SENTRY_AUTH_TOKEN はビルド時アップロードのみ — Sentry.init() に渡さないこと
EAS Build: Sentry 認証トークンが不足	SENTRY_AUTH_TOKEN を EAS シークレットとして設定：eas secret:create --name SENTRY_AUTH_TOKEN