Sentry React Native: 2026 連携ガイド

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

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

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

Getting Started with the Sentry SDK
- セントリとCapgoの__CAPGO_KEEP_0__の始め方
- インストールする前に必要なもの
ワイザードの実行と結果の確認
ネイティブのセットアップチェックが後で時間を節約することになる理由は何か
パフォーマンスデータとカスタムイベントのキャプチャ
- 画面の遅さを推測するのではなく、スロー画面を追跡する
- エラーに役立つコンテキストを追加する
インテグレーションを検証し、トラブルシューティングする
ライブアップデートワークフローと統合するCapgo
- ライブバンドルのリリース識別子とマッチングする

Sentry SDK

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

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

Sentryをインストールするには、まず通常の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-only エラーのキャプチャは、モバイルアプリ用では十分ではありません。
オプションの機能. 必要な機能だけを有効にして、チームが結果のデータを確認するのを待たずにすべての機能を有効にしないでください。

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

ワイザードが完了したら、結果を信頼するのではなく、変更を確認してください。 Sentry パッケージが package.jsonnative の変更が ios 、 androidアプリのエントリファイルに初期化ブロックが追加されます。

初期化の例は次のとおりです。

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

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

DSNは、__CAPGO_KEEP_0__にイベントを送信する場所を示します。設定値として扱ってください。秘密の鍵として扱う必要はありません。認証トークンと同じではありません。環境設定を整理して、各環境でアプリが正しいSentryプロジェクトに接続できるようにしてください。 The 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.

A practical 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 の順序は、チームがセンチリの初期化を置く場所と交差することがよくあります。

Practical rule: Sentryをアプリ起動の早い段階で初期化すること。ナビゲーション、認証、リモート設定の後でも遅くてもいいのですが、起動時エラーを逃すことになるので注意してください。

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

Native iOS and Android Projectsの設定

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

iOSで何が変わったか

iOSプロジェクトを開いて、ウィザードが変更した部分を確認してください。バーレスReact Nativeアプリの場合、通常はアプリ起動とビルドフェーズの周りで変更が見つかります。センチリの初期化のハンドルとアップロードステップをビルドプロセスと関連付ける必要があります。

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

App delegate startup code. アプリは起動の早い段階でネイティブのSentryの初期化が必要です。
ビルドフェーズ. デバッグシンボルやソースマップの処理に関連するSentryのアップロードスクリプトを探してください。
ビルド設定とアーカイブの動作. シンボルファイルはアーカイブビルドの際に生成され、利用可能でなければなりません。

アプリが使用している場合 AppDelegate.mm, 初期化はよくReact Nativeのブリッジのブートストラップに近い位置にあります。 React Nativeのバージョン、テンプレート、および新しいアーキテクチャを使用しているかどうかによって、ファイルの内容は異なります。したがって、プロジェクトの形状に合致するものでないリポジトリからスニペットをコピーしないでください。

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

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

Androidで何が変わったか

Androidでは通常、Gradleファイルの変更やマニフェストレベルでの設定の変更が行われます。 android/build.gradle, android/app/build.gradleGradleファイルとSentryに関連するプラグインまたはタスクのワイヤリングを確認してください。

確認すること:

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

ローカルデバッグ実行が成功してもリリース設定が正しいとは限らないリリースパスは異なる、特に最適化とCI署名が含まれる場合チームが別々のデバッグ、ステージング、QA、ストアビルドを維持している場合

モバイルビルドタイプの分解

モニタリングの動作を各ビルドバリアントと同期するために役立つ参考資料です。

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

iOSのビルドをローカルに保存してください シンボル処理中にビルドが失敗しないことを確認してください。
リリース用Androidビルドを作成してください CIログを確認して、Sentry関連のタスクが正常に実行されていることを確認してください。
Sentryで複数のアプリを管理する場合、パッケージ名とバンドル識別子をマッピングしてください。 リリースの命名規則を確認してください
CIが不一致の名前でアーティファクトをアップロードする前にここではよく機能しないアプローチがあります:

アプローチ

何が間違っているのか	What goes wrong
ウィザードの信頼を確認せずに	React Native またはビルドツールの変更により、ネイティブのセットアップがずれます
テストはデバッグモードのみで行われます	デバッグの成功は、リリース時におけるシンボリケーションの問題を隠します
手動と自動のアップロードステップを組み合わせると	アーティファクトは異なるリリース下に配置され、イベントと一致しません

最良のセットアップは、ネイティブの起動ハンドルが設定され、ビルドスクリプトが毎回実行され、iOS、Android、JavaScript バンドルのリリース名が決定論的であることです。

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

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

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

実践における手動アップロードの失敗の理由

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

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.

「Notionで手順を記録する」アプローチは、緊急リリースが発生するまで機能するが、実際には推奨しない

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による自動ビルドとリリースワークフロー は同じ運用モデルに適合します。.

automatic build and release workflows with __CAPGO_KEEP_0__ Actions automatic build and release workflows with GitHub Actions Release IDs are generated once and reused everywhere.

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

ブレークダウンは、ユーザーが「アプリがフリーズした」という意見と「ダッシュボードを開き、同期を開始し、古いリクエストを再試行した後、アプリが失敗した」という意見の差を示すことがよくあります。

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

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

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

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

男性のソフトウェア開発者が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のドキュメントされたネイティブクラッシュテストユーティリティを使用することを推奨します。代わりに独自のクラッシュパスを作成するのではなく。

セントリUIで確認すること

イベントが表示されたときは、タイトルだけでは十分ではありません。

次のフィールドを確認してください。

プラットフォームとメカニズムこれは、JSエラーとネイティブクラッシュを区別するのに役立ちます。
リリースとディストソースマップとシンボリケーションが正しく機能するためには、空白または誤った値ではありません。
スタックフレーム適切にアップロードされたJavaScriptマップの場合、読みやすいソースロケーションが表示されるはずです。
パンくずとタグカスタムコンテキストが正常に到着したことを確認してください。
環境開発と運用イベントが混在しないように、確実に確認してください。

nativeイベントが到着するが、シンボリケーションが悪い場合は、codeアプリをずっと調整しないでください。それは通常ビルドアーティファクトの問題です。

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

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

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

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

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

SentryリリースIDをライブバンドルに従うようにします。 Sentry release identity follow the live bundleライブアップデートワークフローでは、

ライブアップデートワークフローでは、

ライブアップデートワークフローでは、 release ライブアップデートワークフローでは、 dist ライブアップデートワークフローでは、

ライブアップデートワークフローでは、

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

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

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

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

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

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

capgo

主なミスを避けるべきことは、1 つの静的リリース文字列をすべての post-store アップデートに再利用することです。複数のバンドルが同じ Sentry リリースを共有している場合、デバッグはまたもや推測に戻ります。

チームがアプリストアのレビューサイクル外で修正を出荷している場合、 Capgo チームに Capacitor を提供することで、チームはライブアップデートを配信するための構造化された方法で、チャンネルをターゲットにし、ロールアウトを制御し、悪いリリースから迅速に回復できます。Disciplined Sentry リリース名付けとソースマップのアップロードを組み合わせると、エラーは依然として正確な code ユーザーが実行しているものに指示します。

Sentry React Native: 2026年統合ガイド

目次

Sentry SDK

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

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

Native iOS and Android Projectsの設定

iOSで何が変わったか

Androidで何が変わったか

モバイルビルドタイプの分解

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

実践における手動アップロードの失敗の理由

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

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

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

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

セントリUIで確認すること

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

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

ライブアップデートワークフローでは、