Sentry React Native: 2026年統合ガイド

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

Sentryがなければ、通常の答えは悪い。サポートチケット、曖昧なスクリーンショット、開発ビルドからコンソールログが生産ビルドと一致しない場合がある。Sentry React Nativeを適切に設定すると、エラー、スタック、リリースが送信したもの、そしてそれを修正するのに十分なコンテキストを取得できる。ただし、 基本的なインストールは簡単な部分。しかし、痛みのある部分は後で来る:ネイティブ統合、シンボリック化、ソースマップ、リリースの命名、そしてそれらをすべて一致させるために、ライブアップデートを含む配信モデルを維持すること。

ほとんどのガイドは早すぎる。実際の設定はCI、App Storeビルド、Androidリリース、JavaScriptバンドルが元のバイナリから常に来ない場合に生き残らなければならない。

目次

• SentryのSDKの設定方法
  • インストールする前に必要なもの
  • ウィザードの実行と結果の確認
• ネイティブiOSとAndroidプロジェクトの設定
  • iOSの変更点
  • Androidの変更点
  • 後で時間を節約するために保存されるネイティブ設定の確認
• リリースとソースマップの自動化
  • 実践で失敗する手動アップロードの理由
  • 実際に機能するリリースプロセス
  • 実用的CIスクリプトのパターン
• パフォーマンスデータとカスタムイベントのキャプチャ
  • スロー画面のトレースではなく推測するのではなく
  • エラーに役立つコンテキストの追加
• 統合の検証とトラブルシューティング
  • 安全にテストイベントをトリガーする
  • What to check in the Sentry UI
  • Common Sentry React Native Troubleshooting
• Capgoと連携するLive Updateワークフローの統合
  • リリース識別子をライブバンドルとマッチングする

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

The wizard asks a few things that developers often click through too quickly:

• プロジェクトの選択. 本番環境で使用する Sentry プロジェクトを選択してください。 そうでない場合、後で更新することなく忘れやすいテスト用サンドボックスを選択してください。
• ネイティブの変更. 移動アプリ用の JavaScript のみのエラーのキャプチャでは十分ではありません。
• オプションの機能. 使用することがわかっている機能を有効にしますが、チームが結果のデータを確認することなく、すべての機能を一発で有効にするのではなく、最初の日は無視してください。

ワイザードの実行と結果の確認

ワイザードが完了した後、変更を信頼するのではなく、レビューすることなく、変更を確認してください。 Sentry パッケージが package.json、ネイティブの変更が ios 、 android、アプリのエントリーファイルに初期化ブロックが見つかります。

A typical initialization looks like this:

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

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

The DSN SDKにイベントを送信する場所を教えるDSNは、設定として扱うべきであり、秘密の保管庫のアイテムとしては絶対に非表示にしないようにすべきである。

環境設定をきれいに整理し、各環境でアプリが正しくSentryプロジェクトにアクセスできるようにする。 環境固有の設定からDSNを読み込み、Sentryを初期化し、アプリツリーの残りの部分がマウントされる前に初期化するパターンは実用的である。 is useful because startup code order often intersects with where teams place Sentry initialization.

が役に立つかもしれない。 実用的ルール:

アプリ起動の早い段階でSentryを初期化する。

ナビゲーション、認証の水準化、リモート設定の後に初期化すると、起動時のエラーを逃すことになる。

At this stage, many React Native teams get a false sense of completion. The JavaScript SDK is installed, events show up, and everyone assumes crash reporting is done. It isn’t. If native integration is off, some of the crashes you care about most will never reach Sentry in a usable form.

iOSで何が変わったか

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

Xcodeで、次の場所を確認してください:

• アプリデリゲートの起動codeアプリが早期に起動する必要があるため、ネイティブSentryの初期化が必要です。
• ビルドフェーズSentryのアップロードスクリプトを検索してください。デバッグシンボルやソースマップの処理に関連しています。
• ビルド設定とアーカイブ動作シンボルファイルが生成され、保存されていることを確認してください。アーカイブビルドの際には、シンボルファイルが必要です。

アプリが AppDelegate.mmを使用している場合、初期化は通常、React Nativeブリッジのブートストラッピングに近い位置にあります。 React Nativeのバージョン、テンプレート、そして新しいアーキテクチャを使用しているかどうかによって、ファイルの内容は異なる可能性があります。

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

iOSのSentryで読めないネイティブフレームが表示される場合、問題は「Sentryが壊れている」ではない。通常、シンボルアップロードまたはリリースマッチングの問題です。

Androidで何が変わったか

Androidでは、Gradleファイルの変更や、場合によってはマニフェストレベルでの設定変更が発生します。確認してください。 android/build.gradle, android/app/build.gradle確認するべき事項：

Sentry Gradle プラグインが適用されている

1. リリースアーティファクトがビルド時で処理できるようにするためです。 バリアントハンドリングが正常に機能している
2. 製品フラグメントまたは複数のビルドタイプを使用する場合です。 ProGuardまたはR8の出力が考慮されている
3. リリースビルドが縮小または混乱する場合に、__CAPGO_KEEP_0__を考慮する必要があります。 if your release builds shrink or obfuscate code.

A common Android mistake is assuming a successful local debug run proves the release setup is correct. It doesn’t. The release path is different, especially once minification and CI signing enter the picture. If your team maintains separate debug, staging, QA, and store builds, this breakdown of モバイル ビルド タイプ 各ビルド バリアントの監視動作を揃えるために、参考になるのはこのものです。

ネイティブ セットアップは、後で時間を節約するために有効です。

'ザ ウィザードがファイルを変更した' だけでは止めないでください。直接動作を確認してください。

このチェックリストを使用してください。

• iOS ビルドをローカルに保存 シンボル処理中にビルドが失敗しないことを確認してください。
• リリース用 Android ビルドを作成 Sentry関連タスクの CI ログを確認してください。
• パッケージ名とバンドル ID のマッピングを確認 Sentryで複数のアプリを 1 つの組織で管理する場合に使用します。
• リリースの命名規則を確認してくださいCIの開始前に、不一致の名前でアーティファクトをアップロードする。

よく機能しないのはこちらです。

最良の設定は面白くない。ネイティブの起動ハンドルはすべての場合に実行され、iOS、Android、JavaScript バンドルのリリース名は決定論的である。

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

If there’s one place where Sentry React Native setups fall apart, it’s here. Teams install the SDK, see events, そしてリリースの自動化を延期します。 すると、最初の本格的な生産問題が発生し、スタック トレースが最適化され、リリースが欠落している、またはソース マップのアップロードが異なるバンドルに属していることがわかります。

Manual source map uploads sound acceptable when you’re shipping rarely。実際には、人間は繰り返しリリースの帳簿管理に不十分です。

Why manual uploads fail in practice

The failure modes are predictable:

• Someone forgets to upload maps after a late-night hotfix。
• The uploaded files belong to a different commit than the binary or OTA bundle users run。
• The release name changes slightly between iOS, Android, and CI steps。
• A rebuild happens after map upload and invalidates what Sentry should be matching against。

そのため、「Notionでステップをドキュメント化する」アプローチを推奨することはない。

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

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

• リリースIDは一度生成され、どこでも使用される。 ビルド、バンドル、アップロードのステップは同じパイプラインで実行される。
• ソースマップはCIからアップロードされる、開発者用のノートパッドからアップロードされるのではない。.
• アプリは、CIがアップロード時に使用したリリース文字列と同じ文字列でSentryを初期化する。最後の点は、よく考えられていないほど重要である。Sentryにソースマップが必要だけではない。
• targetLanguage protectedTokens

texts runtimeに発行されたアプリの正確なリリース識別子に付属するソースマップ.

既存のモバイル自動化標準化チームがいる場合は、この__CAPGO_KEEP_0__アクションを使用した自動ビルドとリリースワークフローのガイド automatic build and release workflows with GitHub Actions CIスクリプトの実践的なパターン

CIでこのようなスクリプトを使用し、パイプライン環境から値を取得します。

Android用のバンドルコマンドを適応させる必要があります。多くのチームは、両方のプラットフォームのジョブを強制するのではなく、プラットフォーム固有のジョブを分割します。その結果は、スクリプトの複雑さよりも一貫性が重要です。

#!/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"

一貫性よりもスクリプトの巧みさを優先するのではなく、リリースの規律を優先します。

アプリにビルド時に名前を付けるコンフィグを1つ選択し、CIでローカルアドホックアップロードと競合しないようにしてください。 React Nativeの場合、リリース文字列をビルド生成されたコンフィグの1つの場所に格納し、

結果は単純です。イベントが到着すると、Sentryは、実際に配信した__CAPGO_KEEP_0__ではなく、配信したと想定した__CAPGO_KEEP_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.

__CAPGO_KEEP_0__と__CAPGO_KEEP_1__は置換される

クラッシュは何が壊れたかを教えてくれる。パフォーマンスのトレースはユーザーが諦めた直前に感じたことを教えてくれる。

一般的なレポートは次のように聞こえる。「ダッシュボードが遅い。」しかし、これだけではデバッグできない。遅いのはどこで?ナビゲーション中?データの取得中?重いチャートをレンダリング中?Sentryはここで役に立つ。エラーのインボックスとして扱わないようになり、実行中のアプリの挙動を計測するようになる。

予想せずに遅い画面を追跡するのではなく

初めに、初期化でパフォーマンスのトレースを有効にする。サンプリング戦略は環境と容量耐性に依存するが、構造は次のようになる。

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

React Navigationを使用する場合は、画面のトランジションがトレースデータを生成するように統合する。物理デバイスで、シミュレータでは実行できないような遅さを再現する。シミュレータはユーザーが感じるような遅さを隠す。

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

1. ユーザーがログイン後にメインダッシュボードを開く。
2. ナビゲーションが完了したが、コンテンツが遅れて表示される。
3. トレースは画面のトランジションが長いことを示している。
4. 子スパンは1つのAPIリクエストと1つの高コストのレンダリングパスを明らかにしている。
5. レンダリングパスを最適化し、再度配布し、トレースの新しい形状を比較する。

そのほうが、直感に頼ることよりはよいだろう。

ウェブビューまたはハイブリッドアプリの監視パターンについて幅広く考えているチーム向けのこの記事 Capacitor プロジェクトでのパフォーマンスモニタリングについての記事 は、スタックが異なっていても、運用の視点は似ているため、スキャンする価値がある。

エラーに有益なコンテキストを追加する

パフォーマンスデータは、イベントにビジネス上のコンテキストが含まれている場合にのみ、より有用になる。

ただし、ビジネス上のコンテキストではなく、虚飾のメタデータではない。

• ユーザーが影響を受けたかどうか、どの画面でいたか、そして何が直前に失敗したかを判断するのに十分な情報だけが必要だ。 これらのツールを意図的に使用する: Sentry.setUser() ユーザー情報
• と これにより、サポートが報告を関連付けることができるようになる。ユーザーが影響を受けたアカウントを特定するための推測を避けることができる。
• カスタムタグ API のような計画タイプ、機能フラグの状態、または地域の寸法に使用します。
• 例外をキャプチャする 例外をキャッチして再投げる、または制御された失敗を表面化するときに追加のコンテキストとともに。

例:

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' },
  });
}

ブレッドクランチが「アプリがフリーズした」ということと「ダッシュボードを開いて、syncを開始し、古いリクエストを再試行した後、アプリが失敗した」ということの差は、よくあることです。

カスタムインストルメンテーションが間違った場合、通常は過度にノイズが大きくなります。アプリのすべてのボタンを永久にキャプチャするのではなく、デバッグするときに重要な境界、状態の移行、オペレーションをキャプチャすること。イベントを説明するのに十分なコンテキスト。イベントを溺死させるほどのコンテキストではない。

統合を検証し、トラブルシューティングする

送信する前に、ビルドパイプラインの変更後、そしてSDKのアップグレード後、センチリを検証する必要があります。「何ヶ月も前は動いていた」というのは意味のあるテストではありません。

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

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

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ビルドでしか行うべきであり、注意して行うべきです。 exactヘルパーメソッドが利用可能なのは、SDKのバージョンとプラットフォームのワイヤリングによって異なります。 したがって、利用可能なヘルパーメソッドが変化する可能性があるため、SDKのドキュメントされたネイティブクラッシュテストユーティリティを使用することをお勧めします。

Sentry UI で確認するもの

イベントが表示されたら、タイトルだけではなくて詳細を確認すること。

確認するフィールド:

• プラットフォームとメカニズムJS例外とネイティブクラッシュを区別するのに役立ちます。
• リリースとディスト. これらが空白または不正の場合、ソースマップと符号化はずれます。
• スタックフレーム. 正しくアップロードされたJavaScriptマップの場合、読みやすいソースロケーションが表示されるはずです。
• パンくずとタグ. __CAPGO_KEEP_0__ のカスタムコンテキストが正常に到着したことを確認してください。
• 環境. 開発と運用イベントが混在して一つのストリームに混ざってはいけません。

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

症状

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

Live Updateワークフローと統合するCapgo

Live Updateはリリースモデルを変える。ストア内のバイナリは同じままになるが、JavaScriptバンドルは下から変化する。Sentryはまだ元のアプリバージョンにしか考えていないので、スタックトレースはすぐに誤解を招く

解決策は SentryリリースIDをLiveバンドルに従うリリースIDをLiveバンドルにマッチングする

__CAPGO_KEEP_0__

ライブ更新ワークフローでは、 release と dist を配信されたJavaScriptパッケージと紐付けられたランタイム識別子として扱う。

ネイティブアプリのバージョンはまだ重要ですが、配布できるパッケージが独立して変更できるようになったら、それだけでは十分ではありません。

• 実用的パターンは次のようになります。
• ネイティブアプリのバージョンをベースリリース名の一部として使用します。
• ライブ更新バージョンまたはパッケージ識別子を追加します。 dist チャンネルまたはビルド固有の区別に使用します。
• モデルに合った場合にのみ使用します。

各ライブバンドルの下に、精確なリリース識別子にアップロードするソースマップを使用します。

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

例えば、アプリが起動時に更新メタデータを読み込む場合、現在アクティブなバンドルから値を派生してSentryを初期化します。

静的ビルド構成のみからではなく、古いストアバンドルではなく、そのホットフィックスのソースマップでフレームを解決するようにSentryを設定する必要があります。 Capacitorのリアルタイム更新のしくみ は、実行可能な参考資料です。

ここでは、更新メタデータとリリーストラッキングを組み合わせたときの、チームが目指すような実行可能なビューの例を紹介します。

主なミスは、ポストストアの更新で1つの静的リリース文字列を再利用することです。

複数のバンドルが同じSentryリリースを共有している場合、デバッグはまたもや推測に戻ります。 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.