Sentry React Native: 2026 との統合ガイド

ローカルでReact Nativeアプリが動作している場合、QAが承認し、生産が近づいている場合、明らかな質問が訪れる:ユーザーのデバイスで破損したときに何が起こるか?

Sentryがなければ、通常は悪い答えが返されます。サポートチケット、曖昧なスクリーンショット、開発ビルドからコンソールログが表示されるかもしれませんが、生産環境とは一致しません。Sentry React Nativeが適切に設定されている場合、エラー、スタック、リリースが送信したもの、そしてそれを修正するのに十分なコンテキストを取得します。ただし、 基本的なインストールは簡単な部分. しかし、実際の問題は後でやってくる:ネイティブ統合、シンボリック化、ソースマップ、リリースの名前付け、そして、ライブアップデートを含む配信モデルで、すべてのものを揃えること

ほとんどのガイドは早すぎる。実際のセットアップはCI、App Storeのビルド、Androidのリリース、JavaScriptのバンドルが元のバイナリから来ない場合に、常に生じること

SentryのSDKのインストールのための基本的な設定
- インストールする前に必要なもの
- ワイザードの実行と結果の確認
ネイティブiOSとAndroidのプロジェクトの設定
リリースとソースマップの自動化
パフォーマンスデータとカスタムイベントのキャプチャ
- 遅い画面のトレースではなく、推測せずに
- エラーに役立つコンテキストの追加
インテグレーションを検証し、トラブルシューティング
ライブアップデートワークフローと統合するCapgo
- リリース識別子をライブバンドルと照合する

Sentry SDK

Sentry React Nativeを新しいアプリに導入する最速の方法は依然としてインストールウィザードです。ウィザードはほとんどの繰り返し設定を処理し、早期に機能する基準を達成します。

インストールする前に必要なもの

通常のReact Native開発環境が必要です。Node、パッケージマネージャー、iOSとAndroidのプラットフォームツール、macOSの場合、Watchmanが既にワークフローの一部である場合など。SentryアカウントとReact Native用のプロジェクトも必要です。

まだチームの運用上の選択肢としてReact Nativeが適しているかどうかを評価中の場合はビジネス向けのReact Nativeガイドプラットフォームのトレードオフ、人件費、メンテナンスの期待値について、有益な非マーケティングコンテキストを提供します。コミットするモニタリングとリリースプロセスを共有コードベースにすると、読む価値があります。

プロジェクトルートからウィザードでSDKをインストールします:

npx @sentry/wizard@latest -i reactNative

ウィザードは開発者がよくスピードでクリックするものをいくつか尋ねます:

プロジェクトの選択実際に生産環境で使用する予定のSentryプロジェクトを選択してください。後で忘れて更新しないようにするための仮想サンドボックスではありません。
ネイティブの変更. JavaScript-only エラーのキャプチャは、モバイルアプリ用では十分ではありません。
オプション機能. 必要な機能だけを有効にし、チームが結果のデータを確認しない場合に、すべての機能を無条件に有効にするのを避けましょう。

ワイザードを実行し、結果を確認する

ワイザードが完了したら、変更を信頼するのではなく、レビューすること。 Sentry パッケージが見つかります。 package.json, ios native変更 androidunder

and

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

Sentry.init({
  dsn: 'YOUR_DSN',
});

, アプリのエントリファイルに初期化ブロックが見つかります。 tells the SDK where to send events. Treat it as configuration, not as a secret vault item that must never be visible. It isn’t the same as an auth token. Still, keep your environment setup clean and consistent so your app points to the right Sentry project in each environment.

環境依存の設定からDSNをロードし、Sentryをアプリケーション木の残りの部分がマウントされる前に初期化する実践的なパターンはあります。起動のポリッシュを通して作業している場合、この React Nativeの起動画面設定ガイドは便利です。起動のcode順序は、チームがSentryの初期化を置く場所と交差することがよくあります。

実践的なルール: アプリケーション起動の早い段階でSentryを初期化すること。ナビゲーション、認証の水増し、リモート設定の後まで待つと、起動時のエラーを逃すことになります。

この段階では、完璧さを追求する必要はありません。即座の目標は単純です: アプリケーションを起動し、後述する記事の後半でJavaScript例外をトリガーし、イベントがSentryに到達していることを確認すること。一旦それが動作するようになれば、ネイティブとリリース層はより簡単に推論できます。

ネイティブiOSとAndroidプロジェクトの設定

この段階では、多くのReact Nativeチームが誤った完了感を得ています。JavaScriptSDKはインストールされ、イベントが表示され、クラッシュレポートが完了したとみなされますが、実際にはそうではありません。ネイティブの統合がオフの場合、最も気になるクラッシュはSentryに利用可能な形で到達することなく永遠に失われます。

iOSで何が変更されたか

iOSプロジェクトを開き、ウィザードが変更したことを確認してください。バーレスReact Nativeアプリケーションでは、通常、アプリケーション起動とビルドフェーズの周りで更新が行われます。Sentryの初期化ハンドルとアップロードステップをビルドプロセスにバインドしていることを探しています。

Xcodeで確認する場所は次のとおりです:

アプリケーションデリゲートの起動code. アプリが正常に起動した際に、Sentryのネイティブ初期化が必要です。
Build Phases. デバッグシンボルやソースマップの処理に関連するSentryのアップロードスクリプトを探してください。
Build settings and archive behavior. アーカイブビルドの際にシンボルファイルが生成され、利用可能であることを確認してください。

アプリが AppDelegate.mmを使用している場合、初期化は通常React Native ブリッジのブートストラップに近い位置にあります。

React Nativeのバージョン、テンプレート、および新しいアーキテクチャを使用しているかどうかに関係なく、ファイルの内容はプロジェクトの形状に応じて異なります。

スニペットをランダムなリポジトリからコピーしないでください。

重要なのは、意図です。iOSネイティブクラッシュでは、シンボルデータが必要であり、アプリはクラッシュが観測できるようにSentryを開始する必要があります。

iOSクラッシュがSentryで読み取れないネイティブフレームで表示される場合、問題は通常「Sentryが壊れた」ではありません。シンボルアップロードまたはリリースマッチングの問題です。 android/build.gradle, android/app/build.gradleAndroidで何が変更されたか

確認すること:

Sentry Gradle プラグインが適用されている リリースアーティファクトがビルド時点で処理できるようにする
バリアントの扱いは正常 製品フラバーまたは複数のビルドタイプを使用する場合
ProGuardまたはR8の出力が__CAPGO_KEEP_0__を縮小または混乱するリリースビルドにカウントされている if your release builds shrink or obfuscate code.

モバイルビルドタイプの分類は、各ビルドバリアントの監視動作を揃えるのに役立つ参考資料です。後で時間を節約するためのネイティブ設定のチェック

「ウィザードがファイルを変更した」だけでは止まってはいけません。直接動作を確認してください。

mobile build types

このチェックリストを使用します:

iOS ビルドをローカルに保存し、シンボル処理中にビルドが失敗しないことを確認します。 リリース用 Android ビルドを作成し、センチュリー関連タスクの CI ログを確認します。
センチュリーで管理するアプリが複数ある場合、パッケージ名とバンドル識別子マッピングをセンチュリーで確認します。 リリース名の規約を今すぐ確認します。
CI が不一致の名前でアーティファクトをアップロードする前に。 よく機能しないのは次のとおりです:
アプローチ何が間違っているのか

Capacitor

Capgo	API
信頼できるマジシャンを確認せずに	React Native またはビルドツールの変更により、ネイティブ設定がずれます
テストはデバッグモードのみで行われます	デバッグの成功は、リリース時におけるシンボリケーション問題を隠します
手動と自動アップロードのステップを組み合わせると	アーティファクトは異なるリリース下に配置され、イベントと一致しません

最良の設定は、面白くありません。ネイティブの起動ハンドルは設定され、ビルドスクリプトは毎回実行され、iOS、Android、JavaScript バンドルのリリース名は決定論的です。

リリースとソースマップの自動化

Sentry React Native の設定が崩壊するのはここです。チームは SDK をインストールし、イベントを確認し、リリースの自動化を延期します。次に、最初の本格的なプロダクション問題が発生すると、スタックトレースはミニファイズされ、リリースが欠落したり、ソースマップのアップロードが異なるバンドルに属していたりします。

ソースマップの手動アップロードは、まれに発行する場合に受け入れられるように思われます。実際には、人間は繰り返しリリースの管理に不十分です。

実践で手動アップロードが失敗する理由

失敗のモードは予測可能です:

誰かがマップをアップロードするのを忘れています 深夜のホットフィックスの後。
アップロードされたファイルは異なるコミットに属します 実行中のバイナリまたはOTAバンドルとは異なります。
リリース名はiOS、Android、CIステップの間でわずかに異なります。 マップのアップロード後、再構築が発生し、Sentryが一致させるべきものが無効化されます。
そのため、「Notionでステップをドキュメント化する」アプローチはお勧めしません。急なリリースがプレッシャーの中で出るまで機能します。 React Native用のSentryリリースとソースマップの自動管理プロセスの7ステップのフローチャート

実際に機能するリリースプロセス

信頼できるセットアップにはいくつかの特性があります

__CAPGO_KEEP_0__

リリースIDは一度生成され 全ての場所で再利用されます。
ビルド、バンドル、アップロードのステップは同じパイプラインで実行されます。.
ソースマップはCIからアップロードされます開発者用のノートパソコンではなくCIからアップロードされます。
アプリはCIがアップロード時に使用したリリース文字列でSentryを初期化します。 最後の点はよく考えられていません。ソースマップがSentryに必要だけではありません。

正しいソースマップがアプリが実行時に発行した精確なリリース識別子と紐付けされている必要があります。 あなたのチームがすでにモバイル自動化を標準化している場合、このガイド.

__CAPGO_KEEP_0__ Actionsで自動ビルドとリリースワークフローを実行する GitHub Actionsの操作モデルと同じに合致します。 fits well with the same operational model.

A practical CI script pattern

CI スクリプトのパターン

#!/usr/bin/env bash
set -euo pipefail

export SENTRY_AUTH_TOKEN="$SENTRY_AUTH_TOKEN"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"

RELEASE_NAME="${APP_VERSION}+${GIT_SHA}"

npx sentry-cli releases new "$RELEASE_NAME"

npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./dist/main.jsbundle \
  --sourcemap-output ./dist/main.jsbundle.map

npx sentry-cli releases files "$RELEASE_NAME" upload-sourcemaps ./dist \
  --rewrite \
  --strip-prefix "$(pwd)"

npx sentry-cli releases finalize "$RELEASE_NAME"

Use a script like this in CI and feed values from your pipeline environment:

CI でこのようなスクリプトを使用し、パイプライン環境から値を取得します: You’ll need to adapt the bundle command for Android, and many teams split platform-specific jobs instead of forcing one script to do both. That’s fine. What matters is consistency.

Android 用の bundle コマンドを適応する必要があります。多くのチームはプラットフォーム固有のジョブを分割するのではなく、1 つのスクリプトを両方のジョブを実行するように強制するのではなく、どちらかを選択します。どちらも問題ありません。重要なのは一貫性です。 Sentry.init():

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: Config.SENTRY_RELEASE,
  dist: Config.SENTRY_DIST,
});

The payoff is simple. When an event arrives, Sentry can map the minified frame back to the code you shipped, not the code you think you shipped.

リリースの規律は、巧妙なスクリプトよりも優れています。

Pick one naming convention, inject it into the app at build time, and never let local ad hoc uploads compete with CI.

1 つの命名規則を選択し、ビルド時にアプリに挿入し、CI と競合しないように、ローカルなアドホックのアップロードを許可しないようにします。

For React Native, I prefer storing the release string in one build-generated config location and reading it during

React Native の場合、リリース文字列を 1 つのビルド生成された設定場所に格納し、読み込むことを好みます。

環境と容量耐容性に応じて、パフォーマンスのトレースを有効にすることで始めましょう。具体的なサンプリング戦略は環境によって異なりますが、構造は以下のようになります。

Sentry.init({
  dsn: Config.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

React Navigationを使用している場合、画面のトランジションがトレースデータを生成するように統合を設定してください。その後、実機で、シミュレータでは実行しないで、不具合を再現してください。シミュレータでは、ユーザーが感じるような遅延が隠されるからです。

実用的なダッシュボードの例:

ログイン後、ユーザーはメインダッシュボードを開きます。
ナビゲーションが完了しますが、コンテンツは遅れて表示されます。
画面のトランザクションが長いことを示すトレースが表示されます。
子要素は、1つのAPIリクエストと1つの高コストのレンダリングパスを表示します。
レンダリングパスの最適化を行い、再度配布し、新しいトレースの形状を比較します。

直感に頼ることなく議論することはより良い方法です。

チームがウェブビューまたはハイブリッドアプリの監視パターンについて幅広く考える場合、この} performance monitoring in Capacitor projects システムの構造は異なるが、作業の考え方は似ているため、確認する価値がある。

エラーに役立つコンテキストを追加する

エラーの直前、影響を受けたユーザーがどの画面にいたのか、そして何が失敗したのかを把握するには、イベントにビジネス上のコンテキストを含める必要があります。ただし、ユーザーが実際に実行したアクションや、失敗した直前の状況など、重要な情報だけを含めましょう。

これらのツールを意図的に使用してください：

ユーザーコンテキスト これにより、サポートチームは、影響を受けたアカウントを特定するために、推測や疑問の余地のない情報を確認する必要がなくなります。 Sentry.setUser() ブレッドクラム
タップして送信、モーダルを開く、またはシンクを開始するなどのアクションのトレース カスタムタグ
プランの種類、機能フラグの状態、または__CAPGO_KEEP_0__地域などの要素を表します。 for dimensions like plan type, feature flag state, or API region.
エラーをキャッチして再スローしたり、制御された失敗を表面化したりする場合に使用します。 キャプチャされた例外と追加のコンテキスト

例:

Sentry.setUser({
  id: user.id,
  email: user.email,
});

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Opened dashboard screen',
  level: 'info',
});

try {
  await loadDashboard();
} catch (error) {
  Sentry.captureException(error, {
    tags: { screen: 'dashboard' },
    extra: { widget: 'balance-summary' },
  });
}

アプリがフリーズしたとユーザーが言っているのと、ダッシュボードを開き、同期を開始し、古いリクエストを再試行した後、アプリが失敗したと言っているのとの差は、しばしばパンくずリストによって決まる。

カスタムのインストルメンテーションが間違って行われる場合、通常は、ボタンを押すたびに永遠にキャプチャすることによって過度にノイズが生じる。デバッグの際に重要な境界、状態の移行、オペレーションをキャプチャし、イベントを説明するのに十分なコンテキストを提供する。イベントを説明するのに十分なコンテキストを提供することによって、ノイズを生じさせない。

統合の検証とトラブルシューティング

送信する前に、ビルドパイプラインの変更後、SDKのアップグレード後、Sentryを検証する必要がある。 “何ヶ月も前は動いていた”というのは意味のあるテストではない。

最もきれいな方法は、JavaScriptとネイティブの両方のパスで制御されたエラーをトリガーし、Sentryに到着する方法を調べることである。

codeでソフトウェア開発者がコンピューターモニターにcodeを書きながら、作業台にテスト統合チェックリストを置いている男性。

テストイベントを安全にトリガーする

JavaScriptエラーの場合、非生産環境の画面に一時的なボタンを追加する:

<Button
  title="Trigger JS Error"
  onPress={() => {
    throw new Error('Test JavaScript Sentry error');
  }}
/>

キャプチャされたエラーがアプリをクラッシュさせない場合:

<Button
  title="Capture Exception"
  onPress={() => {
    Sentry.captureException(new Error('Handled Sentry test error'));
  }}
/>

ネイティブのクラッシュテストは、開発または制御されたQAビルドでしか行うべきであり、SDKのバージョンとプラットフォームのワイヤリングによって利用可能なヘルパーメソッドが異なる可能性があるため、SDKのドキュメントされたネイティブクラッシュテストユーティリティを使用することを推奨する。

Sentry UIで確認する必要があるもの

イベントが表示されたときは、タイトルだけではなくて詳細を確認してください。

以下のフィールドを確認してください：

プラットフォームとメカニズム. JS例外とネイティブクラッシュを区別するのに役立ちます。
リリースとdist. 正しくない場合は、ソースマップとシンボリケーションがずれます。
スタックフレーム. 正しくアップロードされたJavaScriptマップの場合、読みやすいソースロケーションが表示されます。
ブレッドクラムとタグ. カスタムコンテキストが正常に到着したことを確認してください。
環境. 開発と本番のイベントが混在して流れないようにしてください。

If a native event arrives but has poor symbolication, don’t keep tweaking app code. That’s usually a build artifact problem.

React Native の Sentry の一般的なトラブルシューティング

症状	原因	解決策
JavaScript エラーが到着するが、スタックトレースは最適化されています	ソースマップがアップロードされていない	CI がバンドル後にマップをアップロードし、 `release` アップロードされたリリースと完全に一致するように `Sentry.init()` ネイティブクラッシュが表示されない
ネイティブ __CAPGO_KEEP_0__ のハックが欠落しているか、早すぎて初期化されていません	Native SDK hooks are missing or not initialized early enough.	iOSおよびAndroidのネイティブ設定を再確認し、コントロールされたネイティブクラッシュパスでQAビルドでテストする
iOSネイティブフレームが読み取れない	デバッグシymbolがアップロードされていなかったり、正しいビルドにリンクされていなかったり	アーカイブビルドがシymbolを生成し、CIまたはXcodeアーカイブフロー中にアップロードステップが実行されることを確認する
Androidのリリースビューはデバッグビューと異なる	リリースアーティファクトパスが変更された場合、縮小またはオブフューションが発生する	リリースGradleタスクを確認し、リリースバリアントのSentry処理が実行されることを確認する
イベントが間違った環境下で表示される	環境間でビルド時設定がリークしている	ビルドターゲットごとにDSN、環境、リリース、distの値を分離する
クレームブレッドまたはユーザーデータが欠落している	アプリの状態変更中にコンテキストが遅れて設定されたり、クリアされたり	ユーザーとタグを即座に認証状態が解決した後に入力し、重要なフロー周辺にパンくずを追加する

リリースプロセスで小さな「監視スモークテスト」チェックリストを維持することは最終的な習慣として報われます。ステージングで1つのJSイベントをトリガーし、リリース値を確認し、ソースの場所を検証し、ビルドをプロモートする前に

Capgo

ライブアップデートワークフローと統合する

ライブアップデートはリリースモデルを変える。ストア内のバイナリは同じままになるかもしれないが、下のJavaScriptバンドルは変化する。Sentryはまだ元のアプリバージョンだけを考えており、スタックトレースはすぐに誤解を招くようになる 修正はSentryのリリースIDはライブバンドルに従う

ライブバンドルと一致するリリースID

ライブアップデートワークフローの場合、 release and dist をライブ配信されたJavaScriptパッケージに紐付いたランタイムIDとして扱う。ネイティブアプリバージョンはまだ重要ですが、単独では十分ではない。バンドルが独立して変化できるようになったら

実践的なパターンは次のようになる

nativeアプリ版をベースリリース名の一部として使用します。
ライブアップデートバージョンまたはパッケージIDを付加します。
使用 dist チャネルまたはビルド固有の区別に適合する場合、モデルに合わせて。
各ライブバンドルの下で、厳密にリリースIDと同じソースマップをアップロードします。

例えば、アプリが起動時にアップデートメタデータを読み込む場合、現在アクティブなバンドルの値からのみではなく、静的ビルド構成からのみ Sentry を初期化します。

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: activeBundle.releaseName,
  dist: activeBundle.channel,
});

そうすると、ユーザーがホットフィックスされたバンドルでエラーを発生させた場合、Sentry はソースマップをホットフィックスのものではなく、古いストアバンドルのものに対してフレームを解決します。

これは、OTAスタイルのワークフローに関係なく、問題です。もし、OTAスタイルのワークフローの背後にある動作の詳細についての良い理解を得たい場合は、__CAPGO_KEEP_0__ アプリでライブアップデートがどのように機能するかについてのこの説明は、良いリファレンスです。 how live updates work in Capacitor apps https://__CAPGO_KEEP_0__.app からスクリーンショット

__CAPGO_KEEP_0__

capgo

The main mistake to avoid is reusing one static release string for every post-store update. If multiple bundles share the same Sentry release, debugging turns into guesswork again.

If your team ships fixes outside app store review cycles, Capgo is worth evaluating. It gives Capacitor teams a structured way to deliver live updates, target channels, control rollouts, and recover from bad releases quickly. Pair that with disciplined Sentry release naming and source map uploads, and you get a workflow where errors still point to the exact code users are running.

Sentry React Native: 2026年統合ガイド

目次

Sentry SDK

インストールする前に必要なもの

ワイザードを実行し、結果を確認する

ネイティブiOSとAndroidプロジェクトの設定

iOSで何が変更されたか

重要なのは、意図です。iOSネイティブクラッシュでは、シンボルデータが必要であり、アプリはクラッシュが観測できるようにSentryを開始する必要があります。

「ウィザードがファイルを変更した」だけでは止まってはいけません。直接動作を確認してください。

リリースとソースマップの自動化

実践で手動アップロードが失敗する理由

__CAPGO_KEEP_0__

A practical CI script pattern

リリースの規律は、巧妙なスクリプトよりも優れています。

React Native の場合、リリース文字列を 1 つのビルド生成された設定場所に格納し、読み込むことを好みます。

エラーに役立つコンテキストを追加する

統合の検証とトラブルシューティング

テストイベントを安全にトリガーする

Sentry UIで確認する必要があるもの

React Native の Sentry の一般的なトラブルシューティング

Capgo

ライブバンドルと一致するリリースID