Sentry React Native: Panduan Integrasi 2026

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

Tidak ada Sentry, jawabannya biasanya buruk. Anda mendapatkan tiket dukungan, sebuah tangkapan layar yang kabur, mungkin sebuah 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 memperbaiki masalah tanpa menebak. Namun, ada kelemahan Pemasangan dasar adalah bagian yang mudah. Bagian yang menyakitkan datang kemudian: integrasi native, symbolikasi, peta sumber, penamaan rilis, dan menjaga semua itu seimbang ketika model pengiriman Anda termasuk pembaruan waktu nyata.

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.

Daftar Isi

• Mulai Menggunakan Sentry SDK
  • Apa yang Anda butuhkan sebelum menginstal
  • Menggunakan sihir dan memeriksa hasilnya
• Mengonfigurasi Projek Native iOS dan Android
  • Apa yang berubah pada iOS
  • Apa yang berubah pada Android
  • Pemeriksaan setup native yang menghemat waktu
• Mengautomasi Rilis dan Peta Sumber
  • Mengapa unggahan manual gagal dalam praktek
  • Proses rilis yang sebenarnya dapat bertahan
  • Polanya skrip CI yang praktis
• Mengambil Data Kinerja dan Acara Kustom
  • Mengikuti layar lambat bukan menebak
  • Menambahkan konteks yang berguna pada kesalahan
• Memastikan dan Mengatasi Integrasi Anda
  • Mengaktifkan acara uji coba dengan aman
  • Apa yang harus diperiksa di UI Sentry
  • Pengaturan Umum Pemecahan Masalah Sentry React Native
• Integrasi dengan Alur Pembaruan Langsung seperti Capgo
  • Mengidentifikasi penanda rilis dengan paket hidup

Mulai Menggunakan SDK Sentry

Metode tercepat untuk memasukkan Sentry React Native ke dalam aplikasi baru masih menggunakan asisten instalasi. Asisten ini mengelola sebagian besar pengaturan yang berulang dan membawa Anda ke garis dasar yang berfungsi dengan cepat. Hal ini penting karena mengulangi instalasi pertama biasanya menyebabkan kesalahan kecil yang tidak Anda sadari sampai terjadi crash produksi pertama.

Apa yang Anda butuhkan sebelum menginstal

Sebelum menginstal, Anda membutuhkan lingkungan pengembangan React Native yang normal terlebih dahulu. Node, manajer paket, alat pengembangan platform untuk iOS dan Android, serta Watchman pada macOS jika sudah menjadi 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 yang berguna di luar pemasaran seputar perbandingan platform, staf, dan harapan perawatan. Hal ini patut dibaca sebelum Anda mengkomitkan 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 proyekPilih proyek Sentry yang sebenarnya yang Anda rencanakan untuk digunakan di produksi, bukan sandbox sementara yang Anda lupakan untuk diperbarui kemudian.
• Pengubahan nativeJangan hanya mengandalkan penangkapan kesalahan JavaScript saja untuk aplikasi mobile.
• Fitur opsionalJangan mengaktifkan semua fitur secara berlebihan pada hari pertama jika tim Anda tidak akan memeriksa data hasilnya.

Melakukan sihir dan memeriksa hasilnya

Setelah sihir selesai, periksa perubahan-perubahan tersebut tanpa harus mempercayainya tanpa memeriksa. Anda seharusnya melihat sebuah paket Sentry di package.jsonperubahan native di ios dan androidcontext: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan).

, dan sebuah blok inisialisasi di file entry aplikasi Anda.

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

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

Contoh inisialisasi biasa seperti ini: DSN menginformasikan SDK di mana harus mengirimkan event. Tidaklah tepat jika menganggapnya sebagai rahasia yang tidak boleh terlihat. Ini bukanlah sama dengan token autentikasi. Namun, pastikan setup lingkungan Anda tetap bersih dan konsisten agar aplikasi Anda mengarah ke proyek Sentry yang tepat di setiap lingkungan.

Polanya yang praktis adalah memuat DSN dari konfigurasi spesifik lingkungan dan menginisialisasi Sentry sebelum pohon aplikasi Anda berdiri. Jika Anda juga bekerja melalui penyempurnaan startup, panduan ini ke Penyiapan 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 pastikan event mencapai Sentry. Setelah itu berhasil, lapisan native dan rilis menjadi lebih mudah untuk dipahami.

Pengaturan Projek Native iOS dan Android

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

Apa yang berubah pada iOS

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

Dalam Xcode, periksa tempat-tempat ini:

• Startup code delegasi aplikasiPerlu inisialisasi native Sentry pada awal peluncuran aplikasi.
• Build PhasesCari skrip unggah Sentry yang terkait dengan simbol debug atau pengelolaan peta sumber.
• Konfigurasi Build dan perilaku arsip.Simbol file harus dihasilkan dan tersedia selama proses arsip.

Jika aplikasi Anda menggunakan AppDelegate.mminisialisasi 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 acak kecuali yang sesuai dengan bentuk proyek Anda.

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

Jika crash iOS muncul di Sentry dengan frame native yang tidak dapat dibaca, masalah biasanya bukanlah "Sentry yang rusak." Masalahnya adalah unggahan simbol atau matching rilis.

Apakah yang berubah pada Android

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

Hal-hal untuk dipastikan:

1. Sentry Gradle plugin telah diterapkan sehingga artefak rilis dapat diproses selama waktu pembangunan.
2. Penanganan varian yang normal jika Anda menggunakan rasa produk atau jenis pembangunan yang berbeda.
3. ProGuard atau R8 yang dihasilkan diakui jika rilis Anda mengurangi 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, staging, QA, dan toko yang berbeda, pemahaman ini tentang jenis bangunan mobile adalah referensi yang berguna untuk menjaga perilaku pemantauan sejalan dengan setiap varian bangunan.

Periksa setup native yang menghemat waktu di kemudian hari

Tidak berhenti di “sihir mengubah file.” Periksa 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 bundle di Sentry jika Anda mengelola aplikasi yang berbeda di bawah satu organisasi.
• Konfirmasikan konvensi nama rilis sekarang, sebelum CI mulai mengunggah artefak dengan nama yang tidak konsisten.

Berikut ini yang biasanya tidak berjalan dengan baik:

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

Mengotomasi Rilis dan Peta Sumber

Jika ada satu tempat di mana setup Sentry React Native runtuh, itu di sini. Tim menginstal SDK, melihat event, dan menunda otomatisasi rilis. Kemudian masalah produksi serius datang dan tumpukan jejaknya sudah di-minifikasi, rilis hilang, atau unggah peta sumber milik bundle yang berbeda.

Unggah peta sumber manual terdengar wajar ketika Anda mengirimkan jarang. Namun, 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 adalah:

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

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

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

Proses rilis yang sebenarnya berfungsi dengan baik.

• ID rilis dihasilkan sekali saja dan digunakan di mana-mana.
• Langkah-langkah pembangunan, pengemasan, dan unggah terjadi dalam alur yang sama.
• Sumber peta diunggah dari CIbukan dari laptop pengembang.
• Aplikasi memulai Sentry dengan string rilis yang sama yang digunakan CI selama unggah.

Poin terakhir itu lebih penting daripada yang diharapkan. Anda tidak hanya memerlukan sumber peta di Sentry. Anda memerlukan sumber peta yang tepat yang terikat pada identifikasi rilis yang tepat yang dihasilkan oleh aplikasi pada saat runtime.

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.

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 hal. Itu tidak apa-apa. Yang penting adalah konsistensi.

Disciplin rilis mengalahkan scripting 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.

Perekaman 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 chart yang berat? Sentry menjadi berguna di sini ketika Anda berhenti menganggapnya seperti kotak surat kesalahan dan mulai menginstrumentasi perilaku aplikasi.

Mengikuti jejak lambat daripada menebak

Mulai dengan mengaktifkan tracing kinerja pada inisialisasi Anda. Strategi pengambilan contoh yang tepat bergantung pada lingkungan dan toleransi volume Anda, tetapi struktur yang terlihat 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. Navigation 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 memperbaiki 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 pada 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. Bukan metadata yang hanya untuk memuaskan. 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() agar tim dukungan dapat menghubungkan laporan ke akun yang terpengaruh tanpa harus mencari jawaban secara tebak-tebakan.
• 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' },
  });
}

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

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

Verifikasi dan Mengatasi Masalah Integrasi

Kamu harus memverifikasi 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 mengaktifkan kegagalan terkendali untuk jalur JavaScript dan native, kemudian lihat bagaimana mereka tiba di Sentry.

Mengaktifkan Event Uji Coba dengan Aman

Untuk kesalahan JavaScript, tambahkan tombol sementara di layar produksi:

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

Untuk kecenderungan kecuali yang tidak akan membuat aplikasi jatuh:

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

Menguji Kecelakaan Native harus dilakukan dengan hati-hati dan hanya dalam pembangunan atau pembangunan QA yang dikendalikan. Metode bantuan yang tepat 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.
• Rilis dan dist. Jika mereka 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.

Jika sebuah event native datang tetapi memiliki symbolikasi yang buruk, jangan terus-menerus mengatur aplikasi code. Biasanya masalah ini adalah masalah artifact build.

Masalah Umum Pemecahan Masalah Sentry React Native

Kebiasaan akhir yang menguntungkan adalah menjaga daftar

Integrating with Live Update Workflows like Capgo

monitoring

monitoring monitoringmonitoring

monitoring

monitoring release monitoring dist monitoring

monitoring

• Gunakan versi aplikasi native sebagai bagian dari nama rilis dasar.
• Tambahkan versi live update atau identifier paket.
• Gunakan dist untuk membedakan channel atau rilis spesifik ketika itu sesuai dengan model Anda.
• Unggah peta sumber untuk setiap bundle live 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,
});

Jadi, ketika pengguna mengalami kesalahan pada bundle yang diperbarui secara langsung, Sentry menyelesaikan frame terhadap peta sumber untuk hotfix tersebut bukan bundle penyimpanan yang lebih tua.

Hal ini berlaku dengan model pengiriman OTA apa pun. Jika Anda ingin memahami bagaimana potongan-potongan bergerak di balik model pengiriman tersebut, penjelasan tentang bagaimana update live bekerja di aplikasi __CAPGO_KEEP_0__ how live updates work in Capacitor apps Berikut adalah jenis pandangan operasional yang tim ingin capai ketika mereka kombinasi metadata update dengan pemantauan rilis:

Gambar dari https://__CAPGO_KEEP_0__.app

Jangan menggunakan string rilis statis yang sama untuk setiap pembaruan penyimpanan. Jika beberapa paket berbagi rilis Sentry yang sama, debugging menjadi spekulasi lagi.

Jika tim Anda mengirimkan perbaikan di luar siklus tinjauan toko aplikasi, 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.