Sentry React Native: 2026 連携ガイド

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

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

ほとんどのガイドは早すぎる。実際のセットアップはCI、App Storeのビルド、Androidのリリース、JavaScriptのバンドルが元のバイナリから来ない場合に、すべてを乗り切る必要がある

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

セントリ Sentry SDK

Sentry React Nativeを新しいアプリに導入する最速の方法は依然としてインストールウィザードです。ウィザードはほとんどの繰り返し設定を処理し、早期に機能する基準を達成します。そうすることが重要です。最初のインストールを手作業で行うと、初期のプロダクションクラッシュまで、目に見えない小さな不一致が生じることがよくあります。

Sentry React Nativeをインストールする前に必要なもの

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

Sentry React Nativeをインストールする前にチームの運用選択肢が正しいものであるかどうかを評価している場合ビジネス向けのReact Nativeガイドプラットフォームのトレードオフ、人件費、メンテナンスの期待値について、非マーケティング的な背景を提供します。共有コードベースの監視とリリースプロセスをコミットする前に読む価値があります。

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

npx @sentry/wizard@latest -i reactNative

ウィザードは開発者がよくスルーすることの多いいくつかの質問をします:

プロジェクトの選択. Sentryの実際に使用するプロダクション用のプロジェクトを選択してください。後で更新することなく、忘れられない仮想サンドボックスを選択しないでください。
ネイティブの変更JavaScriptのみのエラー収集では、モバイルアプリケーションには十分ではない。
オプション機能ウィザードを実行し、結果を確認する

ウィザードが完了したら、変更を検証するのではなく、レビューする。Sentryパッケージが

nativeの変更が package.jsonページ ios 、そしてアプリケーションエントリファイルの初期化ブロックが android初期化の例は次のようになります。

DSN

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

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

__CAPGO_KEEP_0__にイベントを送信する場所を教える。 環境設定をきれいに整理し、各環境でアプリケーションが正しくSentryプロジェクトに接続できるようにする。 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.

Apractical pattern is to load the DSN from environment-specific config and initialize Sentry before the rest of your app tree mounts. If you’re also working through startup polish, this guide to React Native splash screen setup は有用です。起動 code の順序は、チームがセンチリィの初期化を実行する場所と交差することがよくあります。

実践的なルール: アプリ起動の早い段階でセンチリィを初期化するようにしてください。ナビゲーション、認証、リモート設定の後まで待つと、起動時のエラーを捉えることができなくなります。

この段階では、完璧さを追求する必要はありません。すぐにアプリを起動し、後でこの記事で触れるようにJavaScriptの例外をトリガーし、センチリィにイベントが到達していることを確認することが目標です。そうすることで、ネイティブとリリースのレイヤーをより簡単に理解できます。

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

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

iOSで何が変わったか

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

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に関連するプラグインまたはタスクのワイヤリングも確認してください。

確認すること:

Sentry Gradle プラグインが適用されている リリースアーティファクトがビルド時で処理できる
バリアントハンドリングは正常 製品フラバーまたは複数のビルドタイプを使用する場合
ProGuardまたはR8の出力は、リリースビルドが縮小または混乱する場合 code

Androidの一般的なミスは、ローカルデバッグ実行が成功したことを証明することである。そうではない。リリースパスは異なる、特に最適化とCI署名が含まれる場合。チームが別々のデバッグ、ステージング、QA、ストアビルドを維持している場合、このモバイルビルドタイプの分解は、各ビルドバリアントの監視動作を揃えるのに役立つ

リリース設定の確認

ローカルデバッグ実行が成功したことを証明することである。そうではない。リリースパスは異なる、特に最適化とCI署名が含まれる場合。チームが別々のデバッグ、ステージング、QA、ストアビルドを維持している場合、この分解は、各ビルドバリアントの監視動作を揃えるのに役立つ。

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

iOSのビルドをローカルに保存する シンボル処理中にビルドが失敗しないことを確認してください。
リリース用のAndroidビルドを作成する セントリーリLATEDタスクのCIログを検査してください。
パッケージ名とバンドル識別子マッピングを確認する セントリーオーガニゼーション下で複数のアプリを管理する場合
リリース名の規約を確認するCIが不一致の名前のアーティファクトをアップロードする前に

ここではよく機能しないアプローチがあります:

アプローチ	何が間違っているのか
__CAPGO_KEEP_0__	wizardの確認なし
React Nativeやビルドツールの変更でネイティブ設定がずれます	デバッグモードでのみテスト
デバッグ成功はリリース時シンボリケーション問題を隠します	手動と自動アップロードのステップを混ぜ合わせる

アーティファクトは異なるリリース下に配置され、イベントと一致しません

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

If there’s one place where Sentry React Native setups fall apart, it’s here. Teams install the SDK, see events, and postpone release automation. Then the first serious production issue comes in and the stack trace is minified, the release is missing, or the source map upload belonged to a different bundle.

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

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

実践上の手動アップロードの失敗の理由は予測可能です

Someone forgets to upload maps 夜遅れの緊急修正後
The uploaded files belong to a different commit 実行中のバイナリやOTAバンドルとは異なるコミットのファイルがアップロードされる
The release name changes slightly iOS、Android、CIステップ間でリリース名が若干異なる
A rebuild happens after map upload マップのアップロード後、再ビルドが発生し、Sentryが対象とするものが無効化される

That’s why I don’t recommend a “document the steps in Notion” approach.

そのため、ノートションでステップをドキュメント化するアプローチはおすすめしない。

A seven-step flowchart illustrating the automated process of managing Sentry releases and source maps for React Native.

React Native用のSentryリリースとソースマップの自動管理の7ステップフローチャートを示す図表。

リリースIDは一度生成され そして全ての場所で再利用されます。
ビルド、バンドル、アップロードのステップは同じパイプラインで実行されます。.
ソースマップはCIからアップロードされます,開発者用ラップトップからではなく。
アプリはCIがアップロード時に使用した同じリリース文字列でSentryを初期化します。 最後の点は、一般的に予想されるよりも重要です。Sentryにソースマップが必要だけではありません。アプリが実行時に発行される正確なリリース識別子に紐付けされたソースマップが必要です。

あなたのチームがすでにモバイル自動化を標準化している場合、このガイドで説明されている__CAPGO_KEEP_0__ Actionsによる自動ビルドとリリースワークフローの設定方法は同じ運用モデルに合致します。 the correct source maps attached to the exact release identifier emitted by the app at runtime.

If your team is already standardizing mobile automation, this guide to automatic build and release workflows with 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"

CI スクリプトのパターン

CI スクリプトのパターン CI スクリプトのパターン

CI スクリプトのパターン 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.

CI スクリプトのパターン

__CAPGO_KEEP_0__でパフォーマンストレーシングを有効にすることから始めましょう。具体的なサンプリング戦略は環境と容量耐性に依存しますが、構造は次のようになります。

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

React Navigationを使用する場合は、画面のトランジションがトレースデータを生成するように統合する必要があります。次に、物理デバイスではなくシミュレータでだけ問題を再現しないでください。シミュレータはユーザーが感じるような遅さを隠します。

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

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

それが、直感に頼るのではなく、実際のデータに基づいて決定することの利点です。

ウェブビューまたはハイブリッドアプリの監視パターンについて幅広く考えるチームは、__CAPGO_KEEP_0__プロジェクトのパフォーマンス監視についてのこの記事を読む価値があります。 Capacitor __CAPGO_KEEP_0__

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

エラーが発生したときの状況を理解するには、ビジネス上のコンテキストが含まれるイベントが必要です。ただし、単にユーザー情報やメタデータを追加するのではなく、影響を受けたユーザーが誰だったか、どの画面でエラーが発生したか、エラーが発生する直前の状況を理解することが必要です。

次のツールを意図的に使用してください:

ユーザーコンテキスト と 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' },
  });
}

ブレークダウンが必要なのは、ユーザーが「アプリがフリーズした」と言っているのではなく、「ダッシュボードを開き、シンクを開始し、古いリクエストを再試行した後、アプリが失敗した」と言っている場合です。

カスタムインストルメンテーションが間違って行われる場合、通常は過度にノイズが生じます。アプリのすべてのボタンクリックを永久にキャプチャしないでください。デバッグする際に重要な境界、状態の移行、操作をキャプチャしてください。イベントを説明するのに十分なコンテキストを提供してください。イベントを溺れさせるほど多く提供しないでください。

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

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

最も簡潔な方法は、JavaScriptとネイティブの両方のパスで制御されたエラーをトリガーし、Sentryにどのように到達するかを調べることです。

ソフトウェア開発者が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 マップの場合、読みやすいソースロケーションが表示されるはずです。
ブレッドクラムとタグカスタムコンテキストが正常に到着したことを確認してください。
環境開発と生産イベントが混在しないように、確認してください。

nativeイベントが到着するが、シンボリック化が不十分な場合、codeアプリを繰り返し調整するのではなく、通常はビルドアーティファクトの問題です。

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

症状	可能性のある原因	解決策
JavaScriptエラーが到着するが、スタックトレースが最適化されている	ソースマップが、対応するリリースにアップロードされていません	CIがバンドル後にマップをアップロードし、そしてアップロードされたリリースと完全に一致するように `release` nativeクラッシュが表示されない `Sentry.init()` native__CAPGO_KEEP_0__のハックが欠落している、または早すぎて初期化されていない
Verify CI uploads maps after bundling and that	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イベントをトリガーし、リリース値を確認し、ソースの場所を検証し、ビルドをプロモートする前にビルドを検証します。

Integrating with Live Update Workflows like Capgo

__CAPGO_KEEP_0__

ライブアップデートはリリースモデルを変える。ストア内のバイナリは同じままなのに、JavaScriptバンドルは下の部分で変更される。Sentryは元のアプリバージョンだけを考慮している場合、スタックトレースはすぐに誤解を招くようになる。 解決策はSentryリリースIDをライブバンドルに従う

バイナリのみではなく

ライブアップデートワークフローでは release と dist コンテキスト: Capgoマーケティングウェブサイト。役割: ショートUIラベルまたはナビゲーションアイテム。見られる場所: page trust.astro。メッセージキー `and` (And)。

ライブバンドルと同じランタイムIDとして扱う。ネイティブアプリバージョンはまだ重要ですが、バンドルが独立して変更できるようになったらそれだけでは十分ではありません。

nativeアプリ版をベースリリース名の一部として使用してください。
ライブアップデートバージョンまたはパッケージIDを追加してください。
使用 dist チャネルまたはビルド固有の区別に使用してください。
ライブバンドルごとに、正確なリリースIDを使用してソースマップをアップロードしてください。

例えば、起動時にアップデートメタデータを読み込むアプリでは、現在のアクティブバンドルから値を取得してSentryを初期化するようにしてください。静的ビルド設定のみではありません。

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

そうすると、ホットファックスでエラーが発生したユーザーは、ソースマップをホットファックスのものではなく、古いストアバンドルのものに対して解決することができます。

これは、OTAスタイルのワークフローに関係なく重要です。OTAスタイルのワークフローに関する動的要素の説明はこちらの記事を参照してください。 Capacitorアプリのライブアップデートの動作についての説明はこちら。アップデートメタデータとリリーストラッキングを組み合わせると、チームは次のような運用視点を目指します。

https://__CAPGO_KEEP_0__.appからスクリーンショット

capgo

主なミスは、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.

Sentry React Native: 2026年統合ガイド

目次

セントリ Sentry SDK

Sentry React Nativeをインストールする前に必要なもの

ウィザードが完了したら、変更を検証するのではなく、レビューする。Sentryパッケージが

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

iOSで何が変わったか

Androidで何が変わりました

リリース設定の確認

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

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

A seven-step flowchart illustrating the automated process of managing Sentry releases and source maps for React Native.

A practical CI script pattern

CI スクリプトのパターン

CI スクリプトのパターン

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

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

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

Sentry UIで確認するべきもの

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

Integrating with Live Update Workflows like Capgo

バイナリのみではなく