Sentry React Native: Panduan Integrasi 2026

Anda telah memiliki aplikasi React Native yang berjalan lokal, QA telah menyetujui, dan produksi sudah dekat. Kemudian pertanyaan yang jelas muncul: apa yang terjadi ketika aplikasi ini bermasalah pada perangkat pengguna?

Tanpa Sentry, jawabannya biasanya buruk. Anda mendapatkan tiket dukungan, tangkapan layar yang kabur, mungkin log konsol dari build pengembang yang tidak sesuai dengan produksi. Dengan Sentry React Native yang diatur dengan benar, Anda mendapatkan kesalahan, stack, rilis yang mengirimkannya, dan cukup konteks untuk memperbaiki masalah tanpa menebak. Masalahnya adalah bahwa Pemasangan dasar adalah bagian yang mudah. Bagian yang menyakitkan datang kemudian: integrasi asli, simbolisasi, peta sumber, penamaan rilis, dan menjaga semua itu seimbang ketika model pengiriman Anda termasuk pembaruan langsung.

Rata-rata panduan berhenti terlalu awal. Konfigurasi nyata harus bertahan melalui CI, pembangunan App Store, rilis Android, dan bundle JavaScript yang tidak selalu berasal dari biner asli.

Tabel Konten

• Mulai dengan Sentry SDK
  • Apa yang Anda butuhkan sebelum menginstal
  • Menggunakan sihir dan memeriksa hasilnya
• Mengkonfigurasi Projek iOS dan Android Asli
  • Apa yang berubah pada iOS
  • Apa yang berubah pada Android
  • Pemeriksaan pengaturan asli yang dapat menghemat waktu kemudian
• Mengautomasi Rilis dan Peta Sumber
  • Mengapa unggahan manual gagal dalam praktek
  • Proses rilis yang sebenarnya dapat bertahan
  • Polanya skrip CI yang praktis
• Mengabadikan Data Kinerja dan Acara Kustom
  • Mencari jejak layar lambat daripada menebak
  • Menambahkan konteks yang berguna ke kesalahan
• Mengverifikasi dan Mengatasi Integrasi Anda
  • Mengaktifkan acara uji dengan aman
  • Apa yang harus diperiksa di antarmuka UI Sentry
  • Masalah Umum Integrasi Sentry React Native
• Mengintegrasikan dengan Alur Pembaruan Langsung seperti Capgo
  • Mencocokkan identifikasi rilis ke bundle hidup

Mulai Berjalan dengan SDK

Cara termudah untuk mendapatkan Sentry React Native ke dalam aplikasi baru masih menggunakan asisten instalasi. Asisten ini mengatasi sebagian besar pengaturan yang berulang dan mendapatkan Anda ke garis dasar yang berfungsi dengan cepat. Hal ini penting, karena mengulangi pengaturan instalasi pertama biasanya menyebabkan kesalahan kecil yang Anda tidak sadari sampai crash produksi pertama.

Apa yang Anda butuhkan sebelum menginstal

Anda memerlukan lingkungan pengembangan React Native normal terlebih dahulu. Node, manajer paket, alat pengembangan platform untuk iOS dan Android, dan Watchman pada macOS jika itu sudah bagian dari alur kerja Anda. Anda juga memerlukan akun Sentry dan proyek yang dibuat untuk React Native.

Jika Anda masih mengevaluasi apakah React Native adalah pilihan operasional yang tepat untuk tim Anda, ini Petunjuk React Native untuk bisnis memberikan konteks non-pemasaran yang berguna seputar perbandingan platform, staf, dan harapan perawatan. Ini patut dibaca sebelum Anda mengkomitkan proses pengawasan dan proses rilis sekitar kode bersama.

Instal SDK dengan asisten dari root proyek:

npx @sentry/wizard@latest -i reactNative

Asisten ini bertanya beberapa hal yang pengembang seringkali klik terlalu cepat:

• Pemilihan proyek. Pilih proyek Sentry yang sebenarnya yang Anda rencanakan untuk digunakan dalam produksi, bukan sandbox sementara yang Anda akan lupa untuk memperbarui nanti.
• Perubahan asli. Ya, setuju. Pengambilan kesalahan JavaScript saja tidak cukup untuk aplikasi mobile.
• Fitur opsional. Aktifkan apa yang Anda ketahui Anda akan gunakan, tetapi jangan mengaktifkan semuanya secara tidak berpikir pada hari pertama jika tim Anda tidak akan memeriksa data hasilnya.

Menggunakan sihir dan memeriksa hasilnya

Setelah sihir selesai, periksa perubahan daripada percaya pada mereka tanpa memeriksa. Anda harus melihat paket Sentry di package.json, perubahan native di ios , dan blok inisialisasi di file entry aplikasi Anda. androidInisialisasi biasanya terlihat seperti ini:

DSN

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

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

menunjukkan ke __CAPGO_KEEP_0__ tempat mengirimkan event. Tatalah sebagai konfigurasi, bukan sebagai item vault rahasia yang harus tidak pernah terlihat. Ini tidak sama dengan token autentikasi. Meskipun demikian, jaga setup lingkungan Anda bersih dan konsisten sehingga aplikasi Anda mengarah ke proyek Sentry yang tepat di setiap lingkungan. 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.

Aplikasi yang lebih praktis adalah memuat DSN dari konfigurasi spesifik lingkungan dan menginisialisasi Sentry sebelum pohon aplikasi lainnya terpasang. Jika Anda juga bekerja melalui penyempurnaan startup, panduan ini untuk Pengaturan Layar Splash React Native is useful because startup code order often intersects with where teams place Sentry initialization.

Aturan praktis: inisialisasi Sentry secepat mungkin dalam startup aplikasi. Jika Anda menunggu sampai setelah navigasi, hidrasi autentikasi, atau konfigurasi remote, Anda akan melewatkan kegagalan startup.

Pada tahap ini, jangan mencari kesempurnaan. Tujuan segera adalah sederhana: luncurkan aplikasi, trigger kesalahan JavaScript lebih lanjut dalam artikel ini, dan konfirmasi bahwa event mencapai Sentry. Setelah itu berhasil, lapisan native dan rilis menjadi lebih mudah untuk dipahami.

Mengonfigurasi Projek Native iOS dan Android

Pada tahap ini, banyak tim React Native mendapatkan kesan palsu bahwa aplikasi sudah selesai. JavaScript SDK sudah terinstal, event muncul, dan semua orang menganggap pelaporan kecelakaan sudah selesai. Tidaklah begitu. Jika integrasi native dimatikan, beberapa kecelakaan yang paling Anda pedulikan tidak akan pernah mencapai Sentry dalam bentuk yang dapat digunakan.

Apa yang berubah pada iOS

Buka proyek iOS dan tinjau apa yang berubah. Dalam aplikasi React Native yang sederhana, biasanya berarti perubahan seputar startup aplikasi dan fase pembangunan. Anda sedang mencari hook inisialisasi Sentry dan langkah unggah yang terkait dengan proses pembangunan.

Dalam Xcode, periksa tempat-tempat ini:

• Startup code delegasi aplikasi. Aplikasi memerlukan inisialisasi native Sentry pada awal peluncuran.
• Fase Pembangunan. Cari skrip unggah Sentry yang terkait dengan simbol debug atau pengelolaan map sumber.
• Pengaturan Pembangunan dan perilaku arsip. File simbol harus dihasilkan dan tersedia selama pembangunan arsip.

Jika aplikasi Anda menggunakan AppDelegate.mm, inisialisasi sering berada dekat dengan bootstrapping jembatan React Native.

Konten file dapat bervariasi tergantung pada versi React Native, template, dan apakah Anda menggunakan arsitektur baru, jadi jangan salin snippet dari repositori random kecuali yang sesuai dengan bentuk proyek Anda.

Yang penting adalah niat: iOS native crashes memerlukan data simbol, dan aplikasi harus memulai Sentry sebelum kejadian crash dapat diamati secara andal.

Jika crash iOS muncul di Sentry dengan frame native yang tidak dapat dibaca, masalah biasanya bukan “Sentry yang rusak.” Itu simbol unggah atau matching rilis.

Apa yang berubah pada Android android/build.gradle, android/app/build.gradleAndroid biasanya menambahkan perubahan pada file Gradle dan kadang-kadang konfigurasi tingkat manifest. Tinjau”, dan koneksi atau pengaturan plugin terkait Sentry.

Hal-hal yang perlu diverifikasi:

1. Plugin Sentry Gradle diterapkan sehingga artefak rilis dapat diproses selama waktu pembangunan.
2. Pengaturan varian yang wajar jika Anda menggunakan varian produk atau beberapa jenis pembangunan.
3. Keluaran ProGuard atau R8 diakui jika rilis Anda menyusut atau mengaburkan code.

Kesalahan Android yang umum adalah menganggap jalankan debug lokal berhasil membuktikan pengaturan rilis yang benar. Tidak. Jalur rilis berbeda, terutama setelah minifikasi dan tanda tangan CI masuk ke dalam gambar. Jika tim Anda menjaga bangunan debug, pengujian, QA, dan toko yang terpisah, pemahaman ini tentang jenis bangunan mobile adalah referensi yang berguna untuk menjaga perilaku monitoring sejalan dengan setiap varian bangunan.

Pengecekan setup native yang menghemat waktu nanti

Jangan berhenti di “sihir mengubah file.” Verifikasi perilaku secara langsung.

Gunakan daftar periksa ini:

• Simpan bangun iOS secara lokal dan pastikan bangun tidak gagal selama proses simbol.
• Buat bangun rilis Android dan periksa log CI untuk tugas terkait Sentry.
• Periksa nama paket dan identifikasi bundel di Sentry jika Anda mengelola aplikasi beberapa di bawah satu organisasi.
• Pastikan konvensi penamaan rilis sekarang, sebelum CI mulai mengunggah artefak dengan nama yang tidak konsisten.

Berikut ini biasanya tidak berfungsi dengan baik:

Pengaturan terbaik adalah yang biasa. Hooks awal native sudah ada, skrip pembangunan berjalan setiap kali, dan penamaan rilis adalah deterministik di iOS, Android, dan bundle JavaScript.

Mengautomasi Rilis dan Map Sumber

Jika ada satu tempat di mana setup Sentry React Native runtuh, itu di sini. Tim menginstal SDK, melihat acara, dan menunda otomatisasi rilis. Kemudian masalah produksi serius datang dan tanda-tanda stack adalah minifikasi, rilis hilang, atau unggah map sumber milik bundle yang berbeda.

Unggah map sumber manual terdengar wajar ketika Anda mengirimkan jarang. Dalam prakteknya, mereka gagal karena manusia buruk dalam menjaga buku catatan rilis yang berulang.

Mengapa unggah manual gagal dalam prakteknya

Mode gagal yang dapat diprediksi:

• Seseorang lupa mengunggah peta setelah patch malam hari.
• File yang diunggah milik commit yang berbeda daripada binary atau bundle OTA yang dijalankan pengguna.
• Nama rilis berubah sedikit antara langkah iOS, Android, dan CI.
• Rebuild terjadi setelah unggah peta dan membuat tidak valid apa yang Sentry harus mencocokkan.

Itulah mengapa saya tidak merekomendasikan pendekatan “dokumentasikan langkah-langkah di Notion”.

Proses rilis yang sebenarnya dapat bertahan

Konfigurasi yang dapat diandalkan memiliki beberapa sifat:

• ID rilis dihasilkan sekali dan digunakan di mana-mana.
• Langkah-langkah pembangunan, pengemasan, dan unggah terjadi dalam alur pipa yang sama.
• Peta sumber diunggah dari CI, bukan dari laptop pengembang.
• Aplikasi memulai inisialisasi Sentry dengan string rilis yang sama yang digunakan CI selama unggah.

Poin terakhir itu lebih penting dari yang diharapkan. Anda tidak hanya membutuhkan peta sumber di Sentry. Anda membutuhkan peta sumber yang tepat yang terpasang pada identifikasi rilis yang tepat yang dihasilkan oleh aplikasi pada waktu eksekusi.

Jika tim Anda sudah mengstandarkan otomatisasi mobile, panduan ini untuk alur kerja otomatis pembangunan dan rilis dengan GitHub Actions cocok dengan model operasional yang sama.

Menggunakan Pola Skrip CI yang Praktis

Gunakan skrip seperti ini di CI dan berikan nilai dari lingkungan pipeline Anda:

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

Anda perlu menyesuaikan perintah bundel untuk Android, dan banyak tim membagi pekerjaan spesifik platform daripada memaksa satu skrip untuk melakukan kedua hal itu. Itu tidak apa-apa. Yang penting adalah konsistensi.

Disciplin rilis mengalahkan penulisan skrip yang cerdas. Pilih satu konvensi penamaan, masukkan ke dalam aplikasi pada saat pembangunan, dan jangan biarkan unggahan ad hoc lokal bersaing dengan CI.

Untuk React Native, saya lebih suka menyimpan string rilis di satu lokasi konfigurasi yang dibangun dan membacanya selama Sentry.init():

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

Hasilnya sederhana. Ketika suatu event datang, Sentry dapat menerjemahkan frame yang di-minifikasi ke code yang Anda kirim, bukan code yang Anda pikir Anda kirim.

Mengumpulkan Data Kinerja dan Event Kustom

Kecelakaan memberitahu Anda apa yang rusak. Perekaman kinerja memberitahu Anda apa yang dirasakan pengguna sebelum mereka menyerah.

Laporan umum terdengar seperti ini: “Dashboard ini lambat.” Itu tidak cukup untuk debug. Lambat di mana? Pada navigasi? Saat mengambil data? Saat mengrender grafik yang berat? Sentry menjadi berguna di sini ketika Anda berhenti menganggapnya seperti kotak masuk kesalahan dan mulai menginstrumentasi perilaku aplikasi.

Mengikuti jejak lambat aplikasi bukan menebaknya

Mulai dengan mengaktifkan tracing kinerja di inisialisasi Anda. Strategi pengambilan contoh yang tepat bergantung pada lingkungan dan toleransi volume Anda, tetapi struktur yang sama seperti ini:

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

Jika Anda menggunakan React Navigation, hubungkan integrasi sehingga transisi layar menghasilkan data tracing. Kemudian reproduksi keluhan pada perangkat fisik, bukan hanya simulator. Simulator menyembunyikan jenis kelembaban yang pengguna perhatikan.

Contoh dashboard yang praktis:

1. Pengguna membuka dashboard utama setelah login.
2. Navigasi selesai, tetapi konten muncul terlambat.
3. Tracing menunjukkan transaksi layar yang lama.
4. Span anak menunjukkan satu API permintaan dan satu jalur render yang mahal.
5. Anda mengoptimalkan jalur render, kirim lagi, dan bandingkan bentuk tracing baru.

Itu lebih baik daripada berargumen dari perasaan.

Untuk tim yang berpikir luas tentang pola monitoring aplikasi webview atau hybrid, tulisan ini tentang pengawasan kinerja di Capacitor proyek patut dibaca karena mindset operasionalnya sama meskipun stacknya berbeda.

Menambahkan konteks yang berguna pada kesalahan

Data kinerja menjadi lebih berguna ketika event membawa konteks bisnis. Tidak metadata yang berlebihan. Cukup untuk menjawab siapa yang terpengaruh, layar apa yang mereka gunakan, dan apa yang terjadi sebelum kegagalan.

Gunakan alat-alat ini dengan sengaja:

• Konteks pengguna dengan Sentry.setUser() sehingga dukungan dapat menghubungkan laporan ke akun yang terpengaruh tanpa harus mencari jawaban yang mungkin salah.
• Jejak langkah untuk aksi seperti menekan tombol submit, membuka modal, atau memulai sinkronisasi.
• Tag kustom untuk dimensi seperti jenis rencana, status flag fitur, atau API wilayah.
• Kesalahan yang terjebak dengan konteks tambahan ketika Anda menangkap dan melempar kembali atau menampilkan kegagalan yang dikendalikan.

Contoh:

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

Jejak breadcrumb seringkali menjadi perbedaan antara “pengguna mengatakan aplikasi membeku” dan “aplikasi gagal setelah membuka dashboard, memulai sinkronisasi, dan mencoba permintaan yang ketinggalan.”

Ketika instrumen kustom bermasalah, biasanya bermasalah karena terlalu berisik. Jangan tangkap setiap tekanan tombol di aplikasi selamanya. Tangkap batasan, transisi keadaan, dan operasi yang penting ketika debugging. Cukup konteks untuk menjelaskan event. Tidak cukup untuk tenggelamkannya.

Verifikasi dan Mengatasi Masalah Integrasi

Anda harus memverifikasi Sentry sebelum mengirim, setelah perubahan pipeline build, dan setelah SDK diperbarui. “Aplikasi berfungsi beberapa bulan yang lalu” bukanlah tes yang bermakna.

Cara yang paling bersih adalah dengan memicu kegagalan yang terkendali untuk jalur JavaScript dan native, kemudian inspeksi bagaimana mereka datang ke Sentry.

Mengaktifkan Event Uji Coba dengan Aman

Untuk kesalahan JavaScript, tambahkan tombol sementara di layar non-produksi:

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

Untuk kecenderungan kecuali yang tidak akan membuat aplikasi crash:

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

Pengujian crash native harus dilakukan dengan hati-hati dan hanya dalam build pengembangan atau QA yang terkendali. Metode helper yang tepat tersedia dapat bervariasi tergantung pada SDK versi dan pengaturan platform, jadi saya lebih suka menggunakan utilitas crash test native SDK yang terdokumentasi ketika ada daripada membuat jalur crash sendiri.

Apa yang harus diperiksa di UI Sentry

Ketika event muncul, periksa lebih dari judul.

Periksa bidang-bidang berikut:

• Platform dan mekanisme. Hal ini membantu membedakan kesalahan JS dari crash native.
• Release dan dist. Jika kosong atau salah, peta sumber dan simbolisasi akan berubah.
• Frame frame tumpukan. Lokasi sumber yang dapat dibaca harus muncul untuk peta JavaScript yang diunggah dengan benar.
• Breadcrumbs dan tag. Pastikan konteks kustom Anda telah sampai.
• Lingkungan. Pastikan event pengembangan dan produksi tidak dicampur menjadi satu aliran.

If sebuah event asli datang tapi memiliki symbolisasi yang buruk, jangan terus-menerus mengatur aplikasi code. Biasanya itu adalah masalah artefak build.

Masalah Umum Pemecahan Masalah Sentry React Native

Habitus akhir yang menghasilkan adalah menjaga daftar

Integrating with Live Update Workflows like Capgo

kecil

di proses rilis. Aktifkan satu event JS di tahap pengujian, konfirmasi nilai rilis, dan verifikasi lokasi sumber sebelum mempromosikan bangunan. Integrasi dengan Alur Pembaruan Hidup seperti __CAPGO_KEEP_0__Pembaruan hidup mengubah model rilis. Binari di toko mungkin tetap sama sementara paket JavaScript berubah di bawahnya. Jika Sentry masih berpikir dalam istilah aplikasi asli, jejak stack menjadi menipu cepat.

Solusi adalah membuat

Identitas rilis Sentry mengikuti paket live release , bukan hanya binari native. dist Pembaruan identifikasi rilis yang sesuai dengan paket live

Untuk alur pembaruan hidup, traktir dan sebagai identifikasi waktu eksekusi yang terkait dengan paket JavaScript yang disampaikan. Versi aplikasi native masih penting, tetapi tidak cukup sendiri jika paket dapat berubah secara independen secara bebas.

• Gunakan versi aplikasi asli sebagai bagian dari nama rilis dasar.
• Tambahkan versi live update atau identifier paket.
• Gunakan dist untuk perbedaan kanal atau rilis spesifik ketika itu sesuai dengan model Anda.
• Unggah peta sumber untuk setiap live bundle di bawah identifier rilis yang tepat.

Contoh, jika aplikasi Anda memuat metadata update pada startup, inisialisasi Sentry dengan nilai yang dihasilkan dari bundle aktif saat ini, bukan hanya dari konfigurasi build statis.

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

Dengan demikian, ketika pengguna mengalami kesalahan pada bundle yang diperbarui secara langsung, Sentry menyelesaikan frame terhadap peta sumber untuk hotfix tersebut bukan bundle toko lama.

Hal ini berlaku dengan model kerja OTA apapun. Jika Anda ingin primer yang baik tentang bagian-bagian yang bergerak di balik model pengiriman itu, penjelasan tentang bagaimana update live bekerja di aplikasi Capacitor adalah referensi yang solid.

Berikut adalah jenis pandangan operasional tim yang berusaha mencapai ketika mereka kombinasi metadata update dengan tracking rilis:

Jangan salah besar dengan menggunakan string rilis statis yang sama untuk setiap pembaruan setelah penyimpanan. Jika beberapa bundle menggunakan rilis Sentry yang sama, maka debugging menjadi spekulasi lagi.

Jika tim Anda mengirimkan perbaikan di luar siklus tinjauan toko aplikasi, Capgo layak dievaluasi. Ini memberikan tim Capacitor cara yang terstruktur untuk mengirimkan pembaruan hidup, menargetkan saluran, mengontrol peluncuran, dan memulihkan dari rilis buruk dengan cepat. Pasang itu dengan penamaan rilis Sentry yang disiplin dan unggah peta sumber, dan Anda akan mendapatkan alur kerja di mana kesalahan masih menunjukkan pengguna code yang menjalankan.