sentry-react-native-sdk

すべてのスキル > SDK のセットアップ > React Native SDK

Sentry React Native SDK

React Native または Expo プロジェクトをスキャンし、エラー監視、トレーシング、プロファイリング、セッションリプレイ、ロギングなど、Sentry のセットアップをすべて案内する、独自の方針を持つウィザードです。

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

• ユーザーが「React Native に Sentry を追加して」や、RN または Expo アプリで「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：検出

推奨事項を提示する前に、次のコマンドを実行してプロジェクトを把握してください。

# Detect project type and existing Sentry
cat package.json | grep -E '"(react-native|expo|@expo|@sentry/react-native|sentry-expo)"'

# Distinguish Expo managed vs bare 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

# Check Expo SDK version (important: Expo SDK 50+ required for @sentry/react-native)
cat package.json | grep '"expo"'

# Detect navigation library
grep -E '"(@react-navigation/native|react-native-navigation)"' package.json

# Detect state management (Redux → breadcrumb integration available)
grep -E '"(redux|@reduxjs/toolkit|zustand|mobx)"' package.json

# Check for existing Sentry initialization
grep -r "Sentry.init" src/ app/ App.tsx App.js _layout.tsx 2>/dev/null | head -5

# Detect Hermes (affects source map handling)
cat android/app/build.gradle 2>/dev/null | grep -i hermes
cat ios/Podfile 2>/dev/null | grep -i hermes

# Detect Expo Router
ls app/_layout.tsx app/_layout.js 2>/dev/null

# Detect backend for cross-link
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 の方法（設定プラグイン＋getSentryExpoConfig）か、ベア／標準 RN の方法か
Expo SDK が ≥50 か？	@sentry/react-native を直接使用。古い場合は sentry-expo（レガシーのため使用しない）
app.json に "expo" キーがあるか？	Managed Expo — ウィザードが最も簡単です。設定プラグインがネイティブ設定をすべて処理します
app/_layout.tsx があるか？	Expo Router プロジェクト — 初期化を _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 Managed／ベア RN] アプリには、エラー監視＋トレーシング＋セッションリプレイのセットアップをおすすめします。プロファイリングとロギングも追加しますか？」

---

フェーズ 3：ガイド

セットアップ方法を選択する

プロジェクトの種類	推奨されるセットアップ	複雑さ
Expo マネージド（SDK 50 以降）	ウィザード CLI、または設定プラグインを使った手動セットアップ	低 — ウィザードがすべて実行します
Expo bare（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 Managed（SDK 50+）

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

npx expo install @sentry/react-native

ステップ 2 — metro.config.js

const { getSentryExpoConfig } = require("@sentry/react-native/metro");
const config = getSentryExpoConfig(__dirname, {
  // Auto-wrap Expo Router ErrorBoundary exports at build time (SDK ≥8.17.0)
  autoWrapExpoRouterErrorBoundary: true,
});
module.exports = config;

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

npx expo customize metro.config.js
# Then replace contents with the above

Metro 設定オプション：

オプション	型	デフォルト	目的
autoWrapExpoRouterErrorBoundary	boolean	false	ビルド時に export { ErrorBoundary } from 'expo-router' を Sentry で自動的にラップします（SDK ≥8.17.0）。手動でラップせずに、ルートごとの ErrorBoundary に到達したエラーをキャプチャします
annotateReactComponents	boolean	false	エラーのコンテキストをより適切に把握できるよう、コンポーネント名を挿入します
includeWebReplay	boolean	true	Web リプレイバンドルを含めます（ネイティブ専用アプリでは false に設定します）
includeWebFeedback	boolean	true	Web フィードバックバンドルを含めます（ネイティブ専用アプリでは false に設定します）
enableSourceContextInDevelopment	boolean	true	開発ビルドでソースコンテキストを有効にします

ステップ 3 — app.json — Expo 設定プラグインを追加する

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

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

プラグインオプション：

オプション	型	デフォルト	目的
url	string	"https://sentry.io/"	Sentry インスタンスの URL
project	string	—	プロジェクトのスラッグ
organization	string	—	組織のスラッグ
disableAutoUpload	boolean	false	ローカルビルド中のソースマップと dSYM のアップロードをスキップします（SDK ≥8.13.0）

ステップ 4 — Sentry を初期化する

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

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

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

  // Tracing
  tracesSampleRate: 1.0, // lower to 0.1–0.2 in production

  // Profiling
  profilesSampleRate: 1.0,

  // Session Replay
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,

  // Logging (SDK ≥7.0.0)
  enableLogs: true,

  // Session Replay
  integrations: [
    Sentry.mobileReplayIntegration(),
  ],

  enableNativeFramesTracking: !isRunningInExpoGo(), // slow/frozen frames

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

function RootLayout() {
  return <Stack />;
}

export default Sentry.wrap(RootLayout);

注記： Expo Router はナビゲーショントラッキングを自動的に処理します。Expo Router プロジェクトでは Sentry.NavigationContainer のラッパーは不要です。ナビゲーションのスパンは自動的にキャプチャされます。

Expo Router の ErrorBoundary 設定（SDK ≥8.16.0）

Expo Router のルートごとの ErrorBoundary は、デフォルトでレンダリングエラーを握りつぶします。明示的にキャプチャしない限り、Sentry はエラーを認識できません。方法は 2 つあります。

1. 自動ラップ（推奨、SDK ≥8.17.0） — metro.config.js で autoWrapExpoRouterErrorBoundary: true を有効にします（上記参照）。Babel プラグインがすべてのルートファイル内の export { ErrorBoundary } from 'expo-router' を自動的に書き換えます。

2. 手動ラップ — 各ルートファイルで自分で境界をラップします。

   // app/_layout.tsx (or any route file)
   import { ErrorBoundary as ExpoErrorBoundary } from 'expo-router';
   import * as Sentry from '@sentry/react-native';
   
   export const ErrorBoundary = Sentry.wrapExpoRouterErrorBoundary(ExpoErrorBoundary);
   

どちらの方法でも、境界に到達したエラーをルートコンテキスト（route.name、route.path、route.params）とともにキャプチャし、アクティブなナビゲーションスパンにエラーのタグを付け、ブレッドクラムを出力します。具体的なパスとパラメーターには sendDefaultPii が適用されます。

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

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

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: [
    Sentry.mobileReplayIntegration(),
  ],
  enableNativeFramesTracking: !isRunningInExpoGo(),
  environment: __DEV__ ? "development" : "production",
});

function App() {
  return (
    <Sentry.NavigationContainer>
      {/* your navigation here */}
    </Sentry.NavigationContainer>
  );
}

export default Sentry.wrap(App);

---

パス C：手動 — Bare 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, {
  // Set to false to exclude @sentry-internal/replay from the native bundle (web only).
  // includeWebReplay: true,
  // Set to false to exclude @sentry-internal/feedback from the native bundle (web only).
  // includeWebFeedback: true,
  // Auto-wrap Expo Router ErrorBoundary exports at build time (SDK ≥8.17.0, Expo Router only)
  // autoWrapExpoRouterErrorBoundary: true,
});

ステップ 3 — iOS：Xcode のビルドフェーズを変更する

Xcode で ios/[AppName].xcodeproj を開きます。**「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.kts"

注記： SDK ≥8.13.0 では sentry.gradle.kts（Kotlin DSL）を使用します。古い SDK では sentry.gradle（Groovy）を使用してください。どちらも後方互換性があります。

ステップ 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 * as Sentry from "@sentry/react-native";

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

function App() {
  return (
    <Sentry.NavigationContainer>
      {/* your navigation here */}
    </Sentry.NavigationContainer>
  );
}

export default Sentry.wrap(App);

---

クイックリファレンス：フル機能の Sentry.init()

すべての機能を有効にした、推奨される初期設定です。

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

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

  // Tracing — lower to 0.1–0.2 in high-traffic production
  tracesSampleRate: 1.0,

  // Profiling — runs on a subset of traced transactions
  profilesSampleRate: 1.0,

  // Session Replay — always capture on error, sample 10% of all sessions
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,

  // Logging — enable Sentry.logger.* API
  enableLogs: true,

  // Integrations — mobile replay is opt-in
  integrations: [
    Sentry.mobileReplayIntegration({
      maskAllText: true,   // masks text by default for privacy
      maskAllImages: true,
    }),
  ],

  // Native frames tracking (disable in Expo Go)
  enableNativeFramesTracking: true,

  // Environment
  environment: __DEV__ ? "development" : "production",

  // Release — set from CI or build system
  // release: "[email protected]+1",
  // dist: "1",
});

// REQUIRED: Wrap root component to capture React render errors
export default Sentry.wrap(App);

アプリ起動の正確性 — Sentry.appLoaded()（SDK ≥8.x）

ルートコンポーネントのマウント後にアプリが重要な非同期処理を行う場合（設定の取得や認証の完了待ちなど）は、その処理が完了した時点で Sentry.appLoaded() を呼び出してください。これにより、Sentry にアプリ起動の実際の終了を通知し、アプリ起動時間をより正確に測定できます。

// Call after async initialization is complete, e.g., in a useEffect or after a loading screen:
useEffect(() => {
  fetchConfig().then(() => {
    Sentry.appLoaded();  // marks the end of the app startup phase
  });
}, []);

Sentry.appLoaded() を呼び出さない場合、SDK がアプリ起動の終了を自動で推定します。

---

ナビゲーションのセットアップ — React Navigation（v5+）

推奨：Sentry.NavigationContainer ラッパーを使用（SDK ≥8.13.0）

NavigationContainer のドロップイン置換で、ナビゲーションのトラッキングを自動的に設定します。

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

// Replace NavigationContainer with Sentry.NavigationContainer
<Sentry.NavigationContainer>
  <Stack.Navigator>
    {/* your screens */}
  </Stack.Navigator>
</Sentry.NavigationContainer>

これだけで完了です。ラッパーは次の処理を自動で行います。

• reactNavigationIntegration を作成します
• ナビゲーションコンテナーの参照を登録します
• ナビゲーションイベントのパンくずリストを記録します（SDK ≥8.13.0）
• 画面ごとの初回表示までの時間（TTID）をトラッキングします

別の方法：手動でセットアップ（SDK <8.13.0 またはカスタム設定の場合）

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

const navigationIntegration = reactNavigationIntegration({
  enableTimeToInitialDisplay: true,   // track TTID per screen
  routeChangeTimeoutMs: 1_000,        // max wait for route change to settle
  ignoreEmptyBackNavigationTransactions: true,
});

// Add to Sentry.init integrations array
Sentry.init({
  integrations: [navigationIntegration],
  // ...
});

// In your component:
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);

---

合意した機能ごとの手順

機能を一つずつ確認します。それぞれのリファレンスファイルを読み込み、手順に従ってから、次に進む前に検証してください。

機能	リファレンス	読み込むタイミング
エラー監視	${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	ユーザーからのレポートの収集
Expo Config Plugin	${SKILL_ROOT}/references/expo-config-plugin.md	@sentry/react-native/expo プラグインの設定

機能ごとに、Read ${SKILL_ROOT}/references/<feature>.md を読み、手順に正確に従って、動作を検証してください。

---

設定リファレンス

Sentry.init() の主なオプション

オプション	型	デフォルト	用途
dsn	string	—	必須です。 プロジェクトの DSN です。空の場合、SDK は無効になります。環境変数：SENTRY_DSN
environment	string	—	例："production"、"staging"。環境変数：SENTRY_ENVIRONMENT
release	string	—	アプリのバージョンです。例："[email protected]+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,       // default: true — mask all text nodes
    maskAllImages: true,     // default: true — mask all images
    maskedViewClasses: ['com.mapbox.maps.MapView'],    // always mask these native view classes
    unmaskedViewClasses: ['com.example.SafeView'],     // always show these native view classes
  },
});

サブオプション	型	デフォルト	用途
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 のみ（ネイティブ SDK なし）にするには false に設定します
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	ネイティブ SDK を手動で初期化するには false に設定します
onReady	function	—	ネイティブ SDK の初期化後に実行するコールバック
enableTurboModuleTracking	boolean	false	実験的機能。 クラッシュの帰属特定とモジュールごとのスパン計測のために、ネイティブの TurboModule パフォーマンスロガーをインストールします。RN 0.75 以降の新アーキテクチャのみ対応。旧アーキテクチャでは何も行いません（SDK ≥8.17.0）

セッションとリリースの健全性に関するオプション

オプション	型	デフォルト	目的
autoSessionTracking	boolean	true	セッションを追跡します（クラッシュのないユーザー／セッション）
sessionTrackingIntervalMillis	number	30000	セッション終了までのバックグラウンド時間（ミリ秒）

リプレイのオプション

オプション	型	デフォルト	目的
replaysSessionSampleRate	number	0	記録する全セッションの割合
replaysOnErrorSampleRate	number	0	記録するエラー発生セッションの割合

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

オプション	型	目的
enableLogs	boolean	Sentry.logger.* API を有効にします
enableAutoConsoleLogs	boolean	enableLogs: true の場合に console.* の呼び出しを自動で捕捉します。手動の Sentry.logger.* のみを使用するには false に設定します（SDK ≥8.14.0、デフォルト：true）
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	組織のスラッグ	ウィザードとビルドプラグインで使用されます
SENTRY_PROJECT	プロジェクトのスラッグ	ウィザードとビルドプラグインで使用されます
SENTRY_RELEASE	リリース識別子	release オプションからフォールバックします
SENTRY_DIST	ディストリビューション識別子	dist オプションからフォールバックします
SENTRY_ENVIRONMENT	環境名	environment オプションからフォールバックします
SENTRY_DISABLE_AUTO_UPLOAD	ソースマップのアップロードをスキップ	ローカルビルド中は true に設定します
EXPO_PUBLIC_SENTRY_DSN	DSN 用の Expo パブリック環境変数	クライアントバンドルに埋め込んでも安全です
SENTRY_EAS_BUILD_CAPTURE_SUCCESS	EAS ビルドフック：ビルド成功をキャプチャ	EAS シークレットで true に設定します
SENTRY_EAS_BUILD_TAGS	EAS ビルドフック：追加タグの JSON	例：{"team":"mobile"}

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

以下のインテグレーションは自動的に有効化されます。設定は不要です。

インテグレーション	機能
ReactNativeErrorHandlers	未処理の JS 例外と Promise の拒否を捕捉します
Release	すべてのイベントにリリース／dist を付加します
Breadcrumbs	コンソールログ、HTTP リクエスト、ユーザー操作をパンくずとして記録します
HttpClient	HTTP リクエスト／レスポンスのパンくずを追加します
DeviceContext	デバイス／OS／バッテリー情報をイベントに付加します
AppContext	アプリのバージョン、バンドル ID、メモリ情報を付加します
CultureContext	ロケールとタイムゾーンを付加します
Screenshot	エラー発生時にスクリーンショットをキャプチャします（attachScreenshot: true の場合）
ViewHierarchy	ビュー階層を付加します（attachViewHierarchy: true の場合）
NativeLinkedErrors	JS エラーを対応するネイティブクラッシュに関連付けます
TurboModuleContext	クラッシュ時のコンテキストで TurboModule の呼び出しを追跡します。ネイティブクラッシュの原因を高レベルの RN モジュールとメソッド（例：RNSentry.captureEnvelope）に関連付けます

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

インテグレーション	有効化方法
mobileReplayIntegration()	integrations 配列に追加します
reactNavigationIntegration()	integrations 配列に追加します
reactNativeNavigationIntegration()	integrations 配列に追加します（Wix 専用）
feedbackIntegration()	integrations 配列に追加します（ユーザーフィードバックウィジェット。ネイティブの振動検出に対応する enableShakeToReport をサポートします）
deeplinkIntegration()	integrations 配列に追加します（ディープリンク URL をパンくずとして自動的にキャプチャします。オプトイン）
turboModuleContextIntegration()	デフォルト — RNSentry TurboModule を自動的に追跡します。必要に応じて { modules: [...] } で設定し、カスタム TurboModule を追跡できます

カスタム TurboModule の追跡

TurboModuleContext インテグレーションはデフォルトで有効になっており、組み込みの RNSentry TurboModule を自動的に追跡します。独自のカスタム TurboModule を追跡するには、インテグレーションを明示的に設定します。

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

Sentry.init({
  dsn: "YOUR_DSN",
  integrations: [
    Sentry.turboModuleContextIntegration({
      modules: [
        {
          name: "MyCustomModule",
          module: NativeModules.MyCustomModule,
          // Optional: skip specific methods to avoid tracking overhead
          skipMethods: ["addListener", "removeListeners"],
        },
      ],
    }),
  ],
});

追跡対象の TurboModule メソッド呼び出し内でネイティブクラッシュが発生すると、クラッシュレポートにモジュール名とメソッド名を含む contexts.turbo_module が記録されるため、クラッシュの原因となった RN API 呼び出しを正確に特定しやすくなります。

連打の検出（TouchEventBoundary）

TouchEventBoundary（アプリのルートをラップします）には、連打を検出する機能が組み込まれています。ユーザーが 1 秒以内に同じ要素を 3 回以上タップすると、ui.multiClick パンくずが出力され、リプレイのタイムラインに表示されます。props で設定できます。

<Sentry.TouchEventBoundary
  enableRageTapDetection={true}   // default: true — set false to disable
  rageTapThreshold={3}            // taps required to trigger (default: 3)
  rageTapTimeWindow={1000}        // detection window in ms (default: 1000)
>
  <App />
</Sentry.TouchEventBoundary>

本番環境の設定

本番環境にリリースする前に、サンプルレートを下げ、設定を強化してください。

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

  // Trace 10–20% of transactions in high-traffic production
  tracesSampleRate: __DEV__ ? 1.0 : 0.1,

  // Profile 100% of traced transactions (profiling is always a subset of tracing)
  profilesSampleRate: 1.0,

  // Replay all error sessions, sample 5% of normal sessions
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: __DEV__ ? 1.0 : 0.05,

  // Set release and dist for accurate source map lookup
  release: "my-app@" + Application.nativeApplicationVersion,
  dist: String(Application.nativeBuildVersion),

  // Disable debug logging in production
  debug: __DEV__,
});

---

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

ソースマップとデバッグシンボルを使うと、難読化されたスタックトレースを読みやすくできます。正しく設定すると、Sentry でエラーが発生したソースコードの正確な行を確認できます。認証トークンと CI の一般的な設定については、sentry-source-maps を参照してください。React Native 固有のアップロード方法は以下のとおりです。

アップロードの仕組み

プラットフォーム	アップロードするもの	タイミング
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

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

ソースマップを手動でアップロードする必要がある場合は、次のようにします。

npx sentry-cli sourcemaps upload \
  --org YOUR_ORG \
  --project YOUR_PROJECT \
  --release "[email protected]+1" \
  ./dist

---

EAS ビルドフック

Expo Application Services（EAS）のビルドを Sentry で監視します。SDK には sentry-eas-build-on-complete、sentry-eas-build-on-error、sentry-eas-build-on-success の 3 つのバイナリフックが付属しており、ビルドイベントを 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://[email protected]/..."

フックはビルド環境から 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 ライフサイクルフックです。EAS はビルドプロセスの最後に、eas-build-on-* に一致する package.json スクリプトを呼び出します。スクリプトは @expo/env、.env、または .env.sentry-build-plugin から環境変数を読み込みます。環境内にすでに設定されている EAS シークレットは上書きしません。

---

検証

セットアップ後、Sentry がイベントを受信していることを確認します。

// Quick test — throws and Sentry.wrap(App) catches it
<Button
  title="Test Sentry Error"
  onPress={() => {
    throw new Error("My first Sentry error!");
  }}
/>

// Or capture manually
<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 のカバレッジが不足しているバックエンドまたは Web フロントエンドがないか確認します。

# Adjacent backend directories
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

# Web frontend in same or sibling repo
ls ../web ../frontend ../dashboard 2>/dev/null
cat ../web/package.json ../frontend/package.json 2>/dev/null | grep -E '"react"|"svelte"|"next"'

# Check for OpenTelemetry (for distributed tracing interop)
grep -r "opentelemetry" ../backend/go.mod ../server/requirements.txt 2>/dev/null

Sentry が導入されていないバックエンドまたは Web フロントエンドがある場合、対応するスキルを提案します。

検出対象	提案するスキル
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 Web	sentry-react-sdk
Svelte / SvelteKit Web	sentry-svelte-sdk

分散トレーシングのセットアップ — バックエンドのスキルを追加する場合は、React Native で tracePropagationTargets を設定して、トレースコンテキストを API に伝播させます。

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

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

---

トラブルシューティング

問題	解決策
Sentry にイベントが表示されない	debug: true を設定し、Metro/Xcode コンソールで SDK のエラーを確認します。DSN が正しいことを確認してください
pod install が失敗する	cd ios && pod install --repo-update を実行します。CocoaPods のバージョンを確認してください
Sentry スクリプト追加後に iOS ビルドが失敗する	「Bundle React Native code and images」スクリプトが追加ではなく置き換えられていることを確認してください
sentry.gradle.kts 追加後に Android ビルドが失敗する	build.gradle の android {} ブロックより前に apply from の行があることを確認します。SDK <8.13.0 では sentry.gradle を使用してください
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 では不可）。integrations に mobileReplayIntegration() があることを確認してください
リプレイに空白または黒い画面が表示される	maskAllText / maskAllImages の設定がプライバシー要件に合っていることを確認してください
遅いフレームやフリーズしたフレームが追跡されない	enableNativeFramesTracking: true を設定し、ネイティブビルドを使用していることを確認してください（Expo Go では不可）
TTID / TTFD が表示されない	ネイティブビルドで reactNavigationIntegration() に enableTimeToInitialDisplay: true を設定する必要があります
Sentry 追加後にアプリの起動時にクラッシュする	ネイティブの初期化エラーが原因と考えられます。Xcode / Logcat のログを確認してください。切り分けるには enableNative: false を試してください
Expo SDK 49 以前	sentry-expo（旧パッケージ）を使用してください。@sentry/react-native には Expo SDK 50 以降が必要です
isRunningInExpoGo のインポートエラー	expo パッケージからインポートしてください：import { isRunningInExpoGo } from "expo"
Xcode ビルド中に Node が見つからない	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