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 tersebut rusak pada perangkat pengguna?

Tidak ada 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 memperbaiki tanpa menebak. Namun, ada pengecualian: Instalasi dasar adalah bagian yang mudah. Bagian yang menyakitkan datang kemudian: integrasi native, simbolisasi, peta sumber, penamaan rilis, dan menjaga semua itu seimbang ketika model pengiriman Anda termasuk pembaruan hidup.

Sebagian besar panduan berhenti terlalu awal. Konfigurasi yang sebenarnya harus bertahan melalui CI, build App Store, rilis Android, dan bundle JavaScript yang tidak selalu berasal dari binary asli.

Isi Kandungan

• Mulai Membuat dengan Sentry SDK
  • Apa yang Anda butuhkan sebelum menginstal
  • Menggunakan sihir dan memeriksa hasilnya
• Mengonfigurasi Projek iOS dan Android Native
  • Apa yang berubah pada iOS
  • Apa yang berubah pada Android
  • Pengaturan asli yang menghemat waktu di masa depan
• Mengautomasi Rilis dan Peta Sumber
  • Mengapa unggahan manual gagal dalam praktek
  • Proses rilis yang sebenarnya dapat dipercaya
  • 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 dengan aman
  • Apa yang harus diperiksa di UI Sentry
  • Masalah Umum Pemecahan Sentry React Native
• Integrasi dengan Live Update Alur Kerja seperti Capgo
  • Menyamakan identifikasi rilis dengan paket hidup

Mulai Menggunakan Sentry SDK

Metode Tercepat untuk Mengintegrasikan Sentry React Native ke Aplikasi Baru adalah Instalasi Asisten. Instalasi Asisten ini akan menghandle sebagian besar pengaturan yang berulang dan mendapatkan Anda ke basis kerja yang berfungsi dengan cepat. Hal ini sangat penting karena mengulang pengaturan instalasi pertama biasanya akan menyebabkan kesalahan kecil yang tidak Anda sadari sampai terjadi crash produksi pertama.

Apa yang Anda Butuhkan Sebelum Menginstal

Sebelum menginstal, Anda perlu memiliki lingkungan pengembangan React Native yang normal terlebih dahulu. Anda perlu memiliki Node, manajer paket, alat-alat platform untuk iOS dan Android, serta Watchman pada macOS jika sudah menjadi bagian dari alur kerja Anda. Anda juga perlu memiliki akun Sentry dan proyek yang dibuat untuk React Native.

Jika Anda masih mengevaluasi apakah React Native adalah pilihan operasional yang tepat untuk tim Anda, maka 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 pemantauan dan rilis sekitar kode bersama.

Instal SDK dengan menggunakan asisten dari root proyek:

npx @sentry/wizard@latest -i reactNative

Asisten ini akan bertanya beberapa hal yang sering kali diklik terlalu cepat oleh pengembang:

• Pilih proyekPilih proyek Sentry yang sebenarnya yang akan digunakan di produksi, bukan sandbox sementara yang akan terlupakan nanti.
• Pengaturan nativePilih ya. Pengambilan kesalahan JavaScript saja tidak cukup untuk aplikasi mobile.
• Fungsi opsionalPilih apa yang Anda ketahui akan digunakan, tetapi jangan mengaktifkan semuanya secara acak pada hari pertama jika tim Anda tidak akan memeriksa data yang dihasilkan.

Melakukan wizard dan memeriksa hasilnya

Setelah wizard selesai, periksa perubahan-perubahan tersebut bukan hanya percaya pada mereka tanpa memeriksa. Anda harus melihat paket Sentry di package.jsonPengaturan native di bawah ios dan android,dan blok inisialisasi di file entry aplikasi Anda.

, dan blok inisialisasi di file entry aplikasi Anda.

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

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

Indonesia DSN menginformasikan SDK mana yang harus mengirimkan event. Tidaklah tepat jika menganggapnya sebagai konfigurasi, bukan sebagai item yang harus selalu disembunyikan. Ini tidak sama dengan token autentikasi. Namun, pastikan setup lingkungan tetap bersih dan konsisten agar aplikasi Anda mengarah ke proyek Sentry yang tepat di setiap lingkungan.

Polanya yang praktis adalah mengambil DSN dari konfigurasi lingkungan spesifik dan menginisialisasi Sentry sebelum pohon aplikasi Anda berpindah. Jika Anda juga bekerja melalui proses penyempurnaan startup, panduan ini untuk setup layar splash React Native bisa berguna karena urutan startup code seringkali bertabrakan dengan tempat tim meletakkan inisialisasi Sentry.

Aturan praktis: inisialisasi Sentry secepat mungkin pada 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 utama sekarang adalah sederhana: luncurkan aplikasi, trigger kesalahan JavaScript di artikel ini, dan pastikan event mencapai Sentry. Setelah itu berhasil, lapisan native dan rilis menjadi lebih mudah untuk dipahami.

Mengonfigurasi Proyek iOS dan Android Natively

Pada tahap ini, banyak tim React Native memiliki kesan palsu bahwa mereka telah menyelesaikan tugas. JavaScript SDK telah diinstal, event muncul, dan semua orang menganggap pelaporan kegagalan crash sudah selesai. Tidaklah demikian. Jika integrasi native dimatikan, beberapa kegagalan crash yang paling penting Anda tidak akan pernah mencapai Sentry dalam bentuk yang dapat digunakan.

Apa yang berubah pada iOS

Terbuka proyek iOS dan tinjau apa yang diganti oleh sihir. Di aplikasi React Native yang sederhana, biasanya berarti perubahan seputar proses startup dan fase pembangunan. Anda mencari hook inisialisasi Sentry dan langkah unggah yang terkait dengan proses pembangunan Anda.

In Xcode, periksa tempat-tempat berikut:

• Delegasi aplikasi startup code. Aplikasi membutuhkan 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 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 mereka sesuai dengan bentuk proyek Anda.

Yang penting adalah niat: iOS native crashes membutuhkan 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 bukan “Sentry yang rusak.” Itu simbol unggah atau matching rilis.

What changed pada Android

Pada Android, biasanya perubahan ditambahkan pada file Gradle dan konfigurasi tingkat manifest secara terkadang. Review android/build.gradle, android/app/build.gradle, dan kabel atau tugas plugin terkait Sentry.

Hal-hal untuk dipastikan:

1. Plugin Gradle Sentry diterapkan sehingga artefak rilis dapat diproses selama waktu build.
2. Pengaturan varian yang seimbang jika Anda menggunakan rasa produk atau beberapa jenis build.
3. Output ProGuard atau R8 diakui jika rilis Anda mengurangi atau mengaburkan code.

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

Penataan asli Native yang menghemat waktu di kemudian hari.

Tidak berhenti di “sihir telah 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 nama paket dan identifikasi bundle mapping di Sentry jika Anda mengelola aplikasi yang berbeda di bawah satu organisasi.
• Pastikan konvensi nama rilis sekarang, sebelum CI mulai mengunggah artefak dengan nama yang tidak konsisten.

Berikut ini yang biasanya tidak berfungsi dengan baik:

Pengaturan terbaik adalah yang sederhana. Hook startup native sudah ada, skrip pembangunan berjalan setiap kali, dan nama rilis sudah ditentukan secara konsisten di iOS, Android, dan JavaScript bundle.

Mengautomasi Rilis dan Peta Sumber

Jika ada satu tempat di mana pengaturan Sentry React Native gagal, maka itu adalah 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.

Manual unggah peta sumber terdengar wajar ketika Anda sedang mengirimkan jarang. Dalam prakteknya, mereka gagal karena manusia buruk dalam melakukan buku catatan rilis yang berulang.

Mengapa unggah manual gagal dalam praktek

Mode gagal yang dapat diprediksi:

• Seseorang lupa mengunggah peta setelah perbaikan malam hari yang mendadak.
• File yang diunggah milik komit yang berbeda daripada binary atau bundle OTA yang digunakan pengguna.
• Nama rilis berubah sedikit antara iOS, Android, dan langkah CI.
• Terjadi rebuild setelah unggah peta dan membuat tidak valid apa yang Sentry harus mencocokkan terhadapnya.

Itulah mengapa saya tidak merekomendasikan pendekatan “dokumentasikan langkah-langkah di Notion”. Ini berfungsi sampai satu rilis darurat keluar di bawah tekanan.

Proses rilis yang sebenarnya dapat bertahan

A reliable setup has a few properties:

• ID rilis dihasilkan sekali dan digunakan di mana-mana. dapat digunakan kembali di mana-mana.
• Peta sumber diunggah dari CI, bukan dari laptop pengembang..
• Peta sumber dikirim dari CIbukan dari laptop pengembang.
• Aplikasi menginisialisasi Sentry dengan string rilis yang sama ID rilis dihasilkan sekali dan digunakan di mana-mana.

Itu poin terakhir lebih penting daripada yang diharapkan. Anda tidak hanya memerlukan peta sumber di Sentry, tetapi Sumber peta yang benar yang terpasang ke identifikasi rilis yang tepat yang dihasilkan oleh aplikasi pada waktu eksekusi.

Jika tim Anda sudah menerapkan otomatisasi mobile, panduan ini tentang aliran otomatis pembangunan dan rilis dengan GitHub Actions cocok dengan model operasional yang sama.

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

Disciplin rilis mengalahkan penulisan skrip yang cerdas. Pilih satu konvensi nama, 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 ke 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.

Mengambil Data Kinerja dan Event Kustom

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

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

Mengikuti jejak lambat layar daripada menebak

Mulai dengan mengaktifkan tracing kinerja di inisialisasi. Strategi pengambilan contoh yang tepat bergantung pada lingkungan dan toleransi volume, 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 di perangkat fisik, bukan hanya simulator. Simulator menyembunyikan jenis lambatnya yang pengguna perhatikan.

Contoh dashboard yang praktis:

1. Pengguna membuka dashboard utama setelah login.
2. Navigasi selesai, tetapi konten muncul terlambat.
3. Trace menunjukkan transaksi layar yang lama.
4. Span anak menunjukkan satu permintaan API dan satu jalur render yang mahal.
5. Anda memperbaiki jalur render, mengirimkan lagi, dan membandingkan bentuk trace baru.

Itu lebih baik daripada berargumen dari perasaan hati.

Untuk tim yang berpikir luas tentang pola pemantauan webview atau aplikasi hybrid, tulisan ini tentang pemantauan kinerja di Capacitor proyek Mengapa ini patut dipertimbangkan karena mindset operasionalnya mirip meskipun stacknya berbeda.

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

Pakai alat-alat ini dengan sengaja:

• Konteks pengguna dengan Sentry.setUser() agar dukungan dapat menghubungkan laporan ke akun yang terpengaruh tanpa harus mencari-cari.
• 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.
• Kecacatan yang tertangkap dengan konteks tambahan ketika Anda menangkap dan melempar kembali atau menampilkan gagal kendali.

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 kaki kriptografi seringkali adalah perbedaan antara “pengguna mengatakan aplikasi membeku” dan “aplikasi gagal setelah membuka dashboard, memulai sinkronisasi, dan mencoba permintaan yang ketinggalan.”

Ketika instrumen kustom salah, biasanya salah karena terlalu berisik. Jangan tangkap setiap tekan tombol di aplikasi selamanya. Tangkap batas, transisi keadaan, dan operasi yang penting ketika debugging. Cukup konteks untuk menjelaskan acara. Tidak cukup untuk tenggelamkan.

Memastikan dan Mengatasi Masalah Integrasi Anda

Anda harus memastikan Sentry sebelum mengirim, setelah perubahan pipeline pembangunan, dan setelah SDK pembaruan. “Aplikasi berjalan bulan lalu” bukanlah tes yang bermakna.

Cara paling bersih adalah mengaktifkan kegagalan kendali untuk jalur JavaScript dan native, kemudian lihat bagaimana mereka tiba di Sentry.

Mengaktifkan acara uji 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');
  }}
/>

For a captured exception that won’t crash the app:

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

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

Apa yang perlu dicek di UI Sentry:

Ketika event muncul, periksa lebih dari judul saja.

Periksa bidang berikut:

• Sistem operasi dan mekanisme. Ini membantu membedakan kejadian JavaScript dari crash native.
• Versi dan distribusi. Jika mereka kosong atau salah, peta sumber dan simbolisasi akan berubah.
• Frame stackSumber lokasi yang dapat dibaca harus muncul untuk peta JavaScript yang diunggah dengan benar.
• Breadcrumbs dan tagKonfirmasi konteks kustom Anda telah diterima.
• EnvironmentPastikan event pengembangan dan produksi tidak dicampur dalam satu aliran.

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

Masalah Umum Pemecahan Masalah Sentry React Native

A final habit that pays off is keeping a tiny “monitoring smoke test” checklist in your release process. Trigger one JS event in staging, confirm release values, and verify source locations before promoting a build.

Mengintegrasikan dengan Live Update Alur Kerja seperti Capgo

Live updates change the release model. The binary in the store might stay the same while the JavaScript bundle changes underneath it. If Sentry still thinks only in terms of the original app version, stack traces become misleading fast.

Integrasi dengan __CAPGO_KEEP_0__ Alur kerja seperti __CAPGO_KEEP_1__ Identitas rilis Sentry mengikuti bundle hidupSolusinya adalah membuat

Identitas rilis Sentry mengikuti bundle hidup

Untuk aliran kerja live update, anggap release dan dist sebagai identifikasi waktu eksekusi yang terkait dengan paket JavaScript yang disampaikan. Versi aplikasi native masih berperan, tetapi tidak cukup sendiri ketika bundle dapat berubah secara independen.

Polanya yang praktis seperti ini:

• Pakai versi aplikasi native sebagai bagian dari nama rilis dasar.
• Tambahkan versi live update atau identifier paket.
• Pakai dist untuk membedakan channel atau build khusus ketika itu sesuai dengan model Anda.
• Unggah peta sumber untuk setiap bundle hidup 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 toko lama.

Ini berlaku untuk setiap alur kerja OTA. Jika Anda ingin memahami bagaimana model pengiriman tersebut bekerja, Anda bisa membaca penjelasan tentang Bagaimana Live Update Bekerja di Aplikasi Capacitor adalah referensi yang solid.

Berikut adalah jenis pandangan operasional yang tim ingin capai ketika mereka kombinasi metadata pembaruan dengan pengawasan rilis:

Kesalahan utama yang harus dihindari adalah menggunakan string rilis statis yang sama untuk setiap pembaruan setelah penyimpanan. Jika beberapa paket berbagi rilis Sentry yang sama, debugging berubah menjadi spekulasi lagi.

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