|
| 1 | +--- |
| 2 | +title: Crash Reporting with Sentry |
| 3 | +description: When your app breaks, fix it faster with Sentry. |
| 4 | +contributors: |
| 5 | + - NathanWalker |
| 6 | +--- |
| 7 | + |
| 8 | +<svg class="css-lfbo6j e1igk8x04" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 222 66" width="400" height="119"><path d="M29,2.26a4.67,4.67,0,0,0-8,0L14.42,13.53A32.21,32.21,0,0,1,32.17,40.19H27.55A27.68,27.68,0,0,0,12.09,17.47L6,28a15.92,15.92,0,0,1,9.23,12.17H4.62A.76.76,0,0,1,4,39.06l2.94-5a10.74,10.74,0,0,0-3.36-1.9l-2.91,5a4.54,4.54,0,0,0,1.69,6.24A4.66,4.66,0,0,0,4.62,44H19.15a19.4,19.4,0,0,0-8-17.31l2.31-4A23.87,23.87,0,0,1,23.76,44H36.07a35.88,35.88,0,0,0-16.41-31.8l4.67-8a.77.77,0,0,1,1.05-.27c.53.29,20.29,34.77,20.66,35.17a.76.76,0,0,1-.68,1.13H40.6q.09,1.91,0,3.81h4.78A4.59,4.59,0,0,0,50,39.43a4.49,4.49,0,0,0-.62-2.28Z M124.32,28.28,109.56,9.22h-3.68V34.77h3.73V15.19l15.18,19.58h3.26V9.22h-3.73ZM87.15,23.54h13.23V20.22H87.14V12.53h14.93V9.21H83.34V34.77h18.92V31.45H87.14ZM71.59,20.3h0C66.44,19.06,65,18.08,65,15.7c0-2.14,1.89-3.59,4.71-3.59a12.06,12.06,0,0,1,7.07,2.55l2-2.83a14.1,14.1,0,0,0-9-3c-5.06,0-8.59,3-8.59,7.27,0,4.6,3,6.19,8.46,7.52C74.51,24.74,76,25.78,76,28.11s-2,3.77-5.09,3.77a12.34,12.34,0,0,1-8.3-3.26l-2.25,2.69a15.94,15.94,0,0,0,10.42,3.85c5.48,0,9-2.95,9-7.51C79.75,23.79,77.47,21.72,71.59,20.3ZM195.7,9.22l-7.69,12-7.64-12h-4.46L186,24.67V34.78h3.84V24.55L200,9.22Zm-64.63,3.46h8.37v22.1h3.84V12.68h8.37V9.22H131.08ZM169.41,24.8c3.86-1.07,6-3.77,6-7.63,0-4.91-3.59-8-9.38-8H154.67V34.76h3.8V25.58h6.45l6.48,9.2h4.44l-7-9.82Zm-10.95-2.5V12.6h7.17c3.74,0,5.88,1.77,5.88,4.84s-2.29,4.86-5.84,4.86Z" transform="translate(11, 11)" fill="#362d59"></path></svg> |
| 9 | + |
| 10 | +Gain critical insights into app issues by integrating [Sentry](https://sentry.io), an advanced error tracking and performance monitoring service. Follow this guide to set up Sentry in your NativeScript application using the [@nativescript-community/sentry](https://github.com/nativescript-community/sentry) plugin. |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +## Step 1: Create a Sentry Account and Project |
| 15 | + |
| 16 | +First, [sign up](https://sentry.io) for a Sentry account and create a new project specifically for your NativeScript app. |
| 17 | + |
| 18 | +## Step 2: Install the Plugin |
| 19 | + |
| 20 | +Install the Sentry SDK into your NativeScript project: |
| 21 | + |
| 22 | +```bash |
| 23 | +npm install @nativescript-community/sentry |
| 24 | +``` |
| 25 | + |
| 26 | +## Step 3: Set Up Environment Variables |
| 27 | + |
| 28 | +Create a `.env` file at the root of your project with these Sentry-related variables: |
| 29 | + |
| 30 | +- **`SENTRY_ORG_SLUG`**: Found under your project's Organization Settings. |
| 31 | +- **`SENTRY_PROJECT_SLUG_IOS` & `SENTRY_PROJECT_SLUG_ANDROID`**: Identifiers for your iOS and Android projects. |
| 32 | +- **`SENTRY_DSN_IOS` & `SENTRY_DSN_ANDROID`**: Obtain from `[Project] > Settings > Client Keys (DSN)`. |
| 33 | +- **`SENTRY_AUTH_TOKEN`**: Generate via your Sentry account under User Auth Tokens. |
| 34 | + |
| 35 | +Example `.env`: |
| 36 | + |
| 37 | +```bash |
| 38 | +SENTRY_ORG_SLUG=nativescript |
| 39 | +SENTRY_PROJECT_SLUG_IOS=myapp-ios |
| 40 | +SENTRY_PROJECT_SLUG_ANDROID=myapp-android |
| 41 | +SENTRY_DSN_IOS=your-ios-dsn |
| 42 | +SENTRY_DSN_ANDROID=your-android-dsn |
| 43 | +SENTRY_AUTH_TOKEN=your-auth-token |
| 44 | +``` |
| 45 | + |
| 46 | +Replace the above placeholders with your actual Sentry details. |
| 47 | + |
| 48 | +## Step 4: Configure Webpack |
| 49 | + |
| 50 | +We will use Webpack to manage environment variables and source maps with plugins: |
| 51 | + |
| 52 | +```bash |
| 53 | +npm install plist @sentry/webpack-plugin dotenv -D |
| 54 | +``` |
| 55 | + |
| 56 | +Update your `webpack.config.js` to configure Sentry integration: |
| 57 | + |
| 58 | +```js |
| 59 | +const webpack = require('@nativescript/webpack') |
| 60 | +const { resolve, join, relative } = require('path') |
| 61 | +const { readFileSync } = require('fs') |
| 62 | +const { parse } = require('plist') |
| 63 | +// load .env without having to specify cli env flags |
| 64 | +require('dotenv').config() |
| 65 | + |
| 66 | +const SentryCliPlugin = require('@sentry/webpack-plugin').sentryWebpackPlugin |
| 67 | +const SourceMapDevToolPlugin = require('webpack').SourceMapDevToolPlugin |
| 68 | + |
| 69 | +const SENTRY_PREFIX = process.env.SENTRY_PREFIX || 'app://github.com/' |
| 70 | +const SENTRY_SOURCE_MAP_PATH = join(__dirname, 'dist', 'sourcemaps') |
| 71 | + |
| 72 | +module.exports = (env) => { |
| 73 | + webpack.init(env) |
| 74 | + |
| 75 | + webpack.chainWebpack((config) => { |
| 76 | + const isStoreBuild = !!env.production |
| 77 | + const sentryDev = !isStoreBuild && !!env['sentryDev'] |
| 78 | + |
| 79 | + const platform = webpack.Utils.platform.getPlatformName() |
| 80 | + const projectSlug = |
| 81 | + platform === 'android' |
| 82 | + ? process.env.SENTRY_PROJECT_SLUG_ANDROID |
| 83 | + : process.env.SENTRY_PROJECT_SLUG_IOS |
| 84 | + const versionString = |
| 85 | + platform === 'android' |
| 86 | + ? readFileSync( |
| 87 | + resolve(__dirname, 'App_Resources/Android/app.gradle'), |
| 88 | + 'utf8', |
| 89 | + ).match(/versionName\s+"([^"]+)"/)[1] |
| 90 | + : parse( |
| 91 | + readFileSync( |
| 92 | + resolve(__dirname, 'App_Resources/iOS/Info.plist'), |
| 93 | + 'utf8', |
| 94 | + ), |
| 95 | + )['CFBundleShortVersionString'] |
| 96 | + |
| 97 | + const SENTRY_DIST = sentryDev ? `dev-${Date.now()}` : `${Date.now()}` |
| 98 | + const SENTRY_RELEASE = sentryDev ? SENTRY_DIST : versionString |
| 99 | + |
| 100 | + config.plugin('DefinePlugin').tap((args) => { |
| 101 | + Object.assign(args[0], { |
| 102 | + __SENTRY_DIST__: `'${SENTRY_DIST}'`, |
| 103 | + __SENTRY_RELEASE__: `'${SENTRY_RELEASE}'`, |
| 104 | + __SENTRY_ENVIRONMENT__: `'${ |
| 105 | + isStoreBuild ? 'production' : 'development' |
| 106 | + }'`, |
| 107 | + __ENABLE_SENTRY__: isStoreBuild || sentryDev, |
| 108 | + __SENTRY_PREFIX__: `'${SENTRY_PREFIX}'`, |
| 109 | + __SENTRY_DSN_IOS__: JSON.stringify(process.env.SENTRY_DSN_IOS), |
| 110 | + __SENTRY_DSN_ANDROID__: JSON.stringify(process.env.SENTRY_DSN_ANDROID), |
| 111 | + }) |
| 112 | + return args |
| 113 | + }) |
| 114 | + |
| 115 | + if (isStoreBuild || sentryDev) { |
| 116 | + config.devtool(false) |
| 117 | + |
| 118 | + config |
| 119 | + .plugin('SourceMapDevToolPlugin|sentry') |
| 120 | + .use(SourceMapDevToolPlugin, [ |
| 121 | + { |
| 122 | + append: `\n//# sourceMappingURL=${SENTRY_PREFIX}[name].js.map`, |
| 123 | + filename: relative( |
| 124 | + webpack.Utils.platform.getAbsoluteDistPath(), |
| 125 | + join(SENTRY_SOURCE_MAP_PATH, '[name].js.map'), |
| 126 | + ), |
| 127 | + }, |
| 128 | + ]) |
| 129 | + |
| 130 | + config |
| 131 | + .plugin('SentryCliPlugin') |
| 132 | + .init(() => |
| 133 | + SentryCliPlugin({ |
| 134 | + org: process.env.SENTRY_ORG_SLUG, |
| 135 | + project: projectSlug, |
| 136 | + // force ignore non-legacy sourcemaps |
| 137 | + sourcemaps: { |
| 138 | + assets: '/dev/null', |
| 139 | + }, |
| 140 | + release: { |
| 141 | + uploadLegacySourcemaps: { |
| 142 | + paths: [ |
| 143 | + join(__dirname, 'dist', 'sourcemaps'), |
| 144 | + webpack.Utils.platform.getAbsoluteDistPath(), |
| 145 | + ], |
| 146 | + urlPrefix: SENTRY_PREFIX, |
| 147 | + }, |
| 148 | + dist: SENTRY_DIST, |
| 149 | + cleanArtifacts: true, |
| 150 | + deploy: { |
| 151 | + env: sentryDev ? 'development' : 'production', |
| 152 | + }, |
| 153 | + setCommits: { |
| 154 | + auto: true, |
| 155 | + ignoreMissing: true, |
| 156 | + }, |
| 157 | + ...(SENTRY_RELEASE ? { name: SENTRY_RELEASE } : {}), |
| 158 | + }, |
| 159 | + authToken: process.env.SENTRY_AUTH_TOKEN, |
| 160 | + }), |
| 161 | + ) |
| 162 | + .use(SentryCliPlugin) |
| 163 | + |
| 164 | + config.optimization.minimizer('TerserPlugin').tap((args) => { |
| 165 | + // we format here otherwise the sourcemaps will be broken |
| 166 | + args[0].terserOptions.format = { |
| 167 | + ...args[0].terserOptions.format, |
| 168 | + max_line_len: 1000, |
| 169 | + indent_level: 1, |
| 170 | + } |
| 171 | + return args |
| 172 | + }) |
| 173 | + } |
| 174 | + }) |
| 175 | + |
| 176 | + return webpack.resolveConfig() |
| 177 | +} |
| 178 | +``` |
| 179 | + |
| 180 | +## Step 5: Initialize Sentry in Your App |
| 181 | + |
| 182 | +Create `sentry.ts` to initialize Sentry: |
| 183 | + |
| 184 | +```ts |
| 185 | +import { Application, Trace, TraceErrorHandler } from '@nativescript/core' |
| 186 | +import * as Sentry from '@nativescript-community/sentry' |
| 187 | + |
| 188 | +declare const __SENTRY_DIST__: string |
| 189 | +declare const __SENTRY_RELEASE__: string |
| 190 | +declare const __SENTRY_ENVIRONMENT__: string |
| 191 | +declare const __ENABLE_SENTRY__: boolean |
| 192 | +declare const __SENTRY_PREFIX__: string |
| 193 | +declare const __SENTRY_DSN_IOS__: string |
| 194 | +declare const __SENTRY_DSN_ANDROID__: string |
| 195 | + |
| 196 | +let initialized = false |
| 197 | +export function initSentry() { |
| 198 | + if (initialized || !__ENABLE_SENTRY__) return |
| 199 | + initialized = true |
| 200 | + |
| 201 | + Sentry.init({ |
| 202 | + dsn: __APPLE__ ? __SENTRY_DSN_IOS__ : __SENTRY_DSN_ANDROID__, |
| 203 | + debug: __DEV__, |
| 204 | + enableAppHangTracking: false, |
| 205 | + enableNativeCrashHandling: true, |
| 206 | + enableAutoPerformanceTracking: true, |
| 207 | + enableAutoSessionTracking: true, |
| 208 | + attachScreenshot: false, |
| 209 | + dist: __SENTRY_DIST__, |
| 210 | + release: __SENTRY_RELEASE__, |
| 211 | + environment: __SENTRY_ENVIRONMENT__, |
| 212 | + appPrefix: __SENTRY_PREFIX__, |
| 213 | + appHangsTimeoutInterval: 5, |
| 214 | + }) |
| 215 | + |
| 216 | + Application.on('uncaughtError', (event) => |
| 217 | + Sentry.captureException(event.error), |
| 218 | + ) |
| 219 | + Application.on('discardedError', (event) => |
| 220 | + Sentry.captureException(event.error), |
| 221 | + ) |
| 222 | + Trace.setErrorHandler(errorHandler) |
| 223 | +} |
| 224 | + |
| 225 | +const errorHandler: TraceErrorHandler = { |
| 226 | + handlerError(error: Error) { |
| 227 | + if (__DEV__) { |
| 228 | + // (development) - log it |
| 229 | + console.error(error) |
| 230 | + // (development) - or use Trace writing (categorical logging) |
| 231 | + Trace.write(error, Trace.categories.Error) |
| 232 | + // (development) - throw it |
| 233 | + throw error |
| 234 | + } |
| 235 | + |
| 236 | + // (production) - send it to sentry |
| 237 | + Sentry.captureException(error) |
| 238 | + }, |
| 239 | +} |
| 240 | +``` |
| 241 | + |
| 242 | +In your main bootstrap file (`app.ts` or `main.ts`), initialize on launch: |
| 243 | + |
| 244 | +```ts |
| 245 | +import { initSentry } from './sentry' |
| 246 | + |
| 247 | +Application.on('launch', () => { |
| 248 | + initSentry() |
| 249 | +}) |
| 250 | +``` |
| 251 | + |
| 252 | +## Step 6: Test Your Setup |
| 253 | + |
| 254 | +Trigger a test crash to verify setup: |
| 255 | + |
| 256 | +```ts |
| 257 | +throw new Error('Sentry test crash') |
| 258 | +``` |
| 259 | + |
| 260 | +For native crashes: |
| 261 | + |
| 262 | +- iOS: |
| 263 | + |
| 264 | +```ts |
| 265 | +NSString.stringWithString(null) |
| 266 | +``` |
| 267 | + |
| 268 | +- Android: |
| 269 | + |
| 270 | +```ts |
| 271 | +new java.lang.String(null) |
| 272 | +``` |
| 273 | + |
| 274 | +Your crashes should appear in your Sentry dashboard shortly after triggering. |
| 275 | + |
| 276 | +<img class="mx-auto" src="../assets/images/guide/ns-sentry-ios.png" alt="Sentry Crash Reporting with iOS" /> |
| 277 | + |
| 278 | +<img class="mx-auto" src="../assets/images/guide/ns-sentry-ios-native.png" alt="Sentry Crash Reporting with iOS for Native Stacktraces" /> |
| 279 | + |
| 280 | +<img class="mx-auto" src="../assets/images/guide/ns-sentry-android.png" alt="Sentry Crash Reporting with Android" /> |
| 281 | + |
| 282 | +--- |
| 283 | + |
| 284 | +You're now successfully integrated with Sentry, gaining powerful insights into your app's performance and stability. |
0 commit comments