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 dev yang tidak sesuai dengan produksi. Dengan Sentry React Native yang terinstal dengan benar, Anda mendapatkan kesalahan, stack, rilis yang mengirimkannya, dan cukup konteks untuk memperbaikinya tanpa menebak. Masalahnya adalah bahwa instalasi 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.

Sebagian besar 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 menghemat waktu kemudian
• Mengautomasi Rilis dan Peta Sumber
  • Mengapa unggahan manual gagal dalam praktek
  • Proses rilis yang sebenarnya dapat diandalkan
  • Polanya skrip CI yang praktis
• Mengabadikan Data Kinerja dan Acara Kustom
  • Mengikuti layar lambat bukan menebak
  • Menambahkan konteks yang berguna pada kesalahan
• Mengverifikasi dan Mengatasi Integrasi Anda
  • Mengaktifkan acara uji coba dengan aman
  • Apa yang perlu dicek di antarmuka UI Sentry
  • Masalah Umum Integrasi React Native Sentry
• Mengintegrasikan dengan Alur Pembaruan Hidup seperti Capgo
  • Mengidentifikasi penanda rilis yang sesuai dengan paket hidup

Mulai Berjalan dengan SDK Sentry

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

Apa yang Anda butuhkan sebelum menginstal

Anda membutuhkan lingkungan pengembangan React Native normal terlebih dahulu. Node, manajer paket, alat platform untuk iOS dan Android, dan Watchman pada macOS jika itu sudah bagian dari alur kerja Anda. Anda juga membutuhkan 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 mengkomit proses pengawasan dan proses rilis seputar 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 Anda maksudkan 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 fitur yang Anda ketahui akan digunakan, tapi jangan mengaktifkan semuanya secara acak pada hari pertama jika tim Anda tidak akan memeriksa data hasilnya.

Menggunakan sihir dan memeriksa hasilnya

Setelah sihir selesai, periksa perubahan daripada mengandalkan mereka tanpa memeriksa. Anda seharusnya 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 selalu tidak terlihat. Ini tidak sama dengan token autentikasi. Meskipun demikian, jaga setup lingkungan Anda tetap 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.

Pola yang 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 ke 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 mengejar kesempurnaan. Tujuan segera adalah sederhana: luncurkan aplikasi, trigger kesalahan JavaScript kemudian di artikel ini, dan konfirmasi bahwa event mencapai Sentry. Setelah itu, lapisan native dan rilis menjadi lebih mudah untuk dipahami.

Mengonfigurasi Proyek Native iOS dan Android

Pada tahap ini, banyak tim React Native mendapatkan kesan palsu bahwa pekerjaan selesai. JavaScript SDK telah diinstal, event muncul, dan semua orang menganggap pelaporan kegagalan crash sudah selesai. Tidaklah begitu. Jika integrasi native dimatikan, beberapa kegagalan crash 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 Anda.

Di Xcode, periksa tempat-tempat ini:

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

Jika aplikasi Anda menggunakan AppDelegate.mm, inisialisasi biasanya 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 kejadian crash iOS muncul di Sentry dengan frame native yang tidak dapat dibaca, masalah biasanya bukanlah “Sentry yang rusak.” Itu simbol unggah atau matching rilis.

Apakah yang berubah pada Android

Android biasanya menambahkan perubahan pada file Gradle dan kadang-kadang konfigurasi tingkat manifest. Tinjau android/build.gradle, android/app/build.gradle, dan koneksi plugin atau tugas terkait Sentry.

Hal-hal untuk diverifikasi:

1. Plugin Sentry Gradle telah 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 yang diakui jika rilis Anda mengurangi atau mengaburkan code.

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

Pengecekan setup native yang menghemat waktu

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

Gunakan daftar periksa ini:

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

Berikut ini yang biasanya tidak berfungsi dengan baik:

Konfigurasi terbaik adalah yang sederhana. Hook startup native sudah ada, skrip pembangunan berjalan setiap kali, dan penamaan rilis adalah deterministik di iOS, Android, dan bundle JavaScript.

Mengotomasi 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 tumpukan jejak 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 dari binary atau bundle OTA yang digunakan pengguna.
• Nama rilis berubah sedikit antara iOS, Android, dan langkah CI.
• Rebuild terjadi setelah unggah peta dan membuat tidak valid apa yang Sentry harus cocokkan.

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

Diagram alir tujuh langkah yang menggambarkan proses otomatis mengelola rilis Sentry dan peta sumber untuk React Native.

Proses rilis yang sebenarnya dapat bertahan lama.

• ID rilis dihasilkan sekali dan digunakan di mana-mana. Langkah-langkah pembangunan, pengemasan, dan unggah terjadi dalam alur kerja 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 daripada yang diharapkan. Anda tidak hanya membutuhkan peta sumber di Sentry. Anda membutuhkan peta sumber yang tepat yang terkait dengan identifikasi rilis yang tepat yang dihasilkan oleh aplikasi pada saat runtime.
• Jika tim Anda sudah mengstandardisasi otomatisasi mobile, panduan ini untuk alur kerja pembangunan dan rilis otomatis dengan __CAPGO_KEEP_0__ Actions sesuai dengan model operasional 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 daripada yang diharapkan. Anda tidak hanya membutuhkan peta sumber di Sentry. Anda membutuhkan peta sumber yang tepat yang terkait dengan identifikasi rilis yang tepat yang dihasilkan oleh aplikasi pada saat runtime..

Jika tim Anda sudah mengstandardisasi otomatisasi mobile, panduan ini untuk alur kerja pembangunan dan rilis otomatis dengan __CAPGO_KEEP_0__ Actions sesuai dengan model operasional yang sama. automatic build and release workflows with GitHub Actions Aplikasi memulai inisialisasi Sentry dengan string rilis yang sama yang digunakan CI selama unggah.

A pola skrip CI yang praktis

Pakai 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.

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. 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.

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

Mengambil Data Kinerja dan Event Kustom

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

Seorang pengembang perangkat lunak yang sedang mengetik di laptop dengan grafik visualisasi data yang ditampilkan di monitor latar belakang.

Mulai dengan mengaktifkan tracing kinerja di inisialisasi Anda. Strategi pengambilan contoh yang tepat tergantung pada lingkungan dan toleransi volume Anda, tetapi struktur 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 lebih 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 optimalkan jalur render, kirim lagi, dan bandingkan bentuk tracing baru.

Itu lebih baik dari berargumen dari perasaan hati.

Untuk tim yang berpikir luas tentang pola monitoring webview atau aplikasi hybrid, tulisan ini tentang pengawasan kinerja di Capacitor proyek layak 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 hanya untuk memuaskan. Cukup untuk menjawab siapa yang terpengaruh, layar mana 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 (breadcrumbs) 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 gagal 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 beku” 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 batas, transisi keadaan, dan operasi yang penting ketika debugging. Cukup konteks untuk menjelaskan event. Tidak cukup untuk tenggelamkan.

Mengverifikasi dan Mengatasi Masalah Integrasi

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

Cara yang paling bersih adalah dengan memicu kegagalan terkendali untuk jalur JavaScript dan native, kemudian memeriksa bagaimana mereka tiba di Sentry.

Memicu 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 kecuali yang tidak akan membuat aplikasi beku:

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

Pengujian kecelakaan native harus dilakukan dengan hati-hati dan hanya dalam pembangunan atau pembangunan QA yang dikendalikan. Metode helper yang tepat tersedia dapat bervariasi tergantung pada versi SDK dan pengaturan platform, jadi saya lebih suka menggunakan utilitas kecelakaan native yang terdokumentasi SDK ketika ada daripada menciptakan jalur kecelakaan 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 stack. 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 dalam satu aliran.

If sebuah event asli datang tapi memiliki symbolisasi yang buruk, jangan terus-menerus mengatur aplikasi code. Biasanya itu adalah masalah artifact 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 Anda. Aktifkan satu event JS di tahap pengujian, konfirmasi nilai rilis, dan verifikasi lokasi sumber sebelum mempromosikan sebuah bangun.

Mengintegrasikan 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 hanya dalam hal versi aplikasi asli, jejak stack menjadi menipu cepat.Solusi adalah membuat

Identitas rilis Sentry mengikuti paket live

, bukan hanya binari native. release Mengidentifikasi rilis yang sesuai dengan paket hidup dist Untuk alur pembaruan hidup, anggap

dan

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

Misalnya, 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-style apa pun. 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 pengawasan rilis:

Jangan salah satu yang harus dihindari adalah mengulang string rilis statis untuk setiap pembaruan setelah penyimpanan. Jika beberapa bundle memiliki rilis Sentry yang sama, debugging berubah menjadi spekulasi lagi.

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