1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
Deprecated React Native
=======================
The deprecated plugin "React Native for Raven.js" is a pure JavaScript
error reporting solution. The plugin will report errors originating from
React Native's JavaScript engine (e.g. programming errors like "x is
undefined"), but might not catch errors that originate from the underlying
operating system (iOS / Android) unless they happen to be transmitted to
React Native's global error handler.
**Do not use this plugin for new code but instead use the new
:ref:`react-native` client integration instead**.
.. admonition:: Note
Unless you have specific reasons not to, it's recommended to instead
the new :ref:`react-native` client instead which supports native and
JavaScript crashes as well as an improved integration into the Xcode
build process.
Installation
------------
In the root of your React Native project, install raven-js via npm:
.. sourcecode:: bash
$ npm install --save raven-js
At the top of your main application file (e.g. index.ios.js and/or index.android.js), add the following code:
.. sourcecode:: javascript
var React = require('react');
var Raven = require('raven-js');
require('raven-js/plugins/react-native')(Raven);
Configuring the Client
----------------------
Now we need to set up Raven.js to use your Sentry DSN:
.. code-block:: javascript
Raven
.config('___PUBLIC_DSN___', { release: RELEASE_ID })
.install();
RELEASE_ID is a string representing the “version” of the build you are
about to distribute. This can be the SHA of your Git repository’s HEAD. It
can also be a semantic version number (e.g. “1.1.2”), pulled from your
project’s package.json file. More below.
About Releases
--------------
Every time you build and distribute a new version of your React Native
app, you’ll want to create a new release inside Sentry. This is for two
important reasons:
- You can associate errors tracked by Sentry with a particular build
- You can store your source files/source maps generated for each build inside Sentry
Unlike a normal web application where your JavaScript files (and source
maps) are served and hosted from a web server, your React Native code is
being served from the target device’s filesystem. So you’ll need to upload
both your **source code** AND **source maps** directly to Sentry, so that
we can generate handy stack traces for you to browse when examining
exceptions triggered by your application.
Generating and Uploading Source Files/Source Maps
-------------------------------------------------
To generate both an application JavaScript file (main.jsbundle) and source map for your project (main.jsbundle.map), use the react-native CLI tool:
.. code-block:: bash
react-native bundle \
--dev false \
--platform ios \
--entry-file index.ios.js \
--bundle-output main.jsbundle \
--sourcemap-output main.jsbundle.map
This will write both main.jsbundle and main.jsbundle.map to the current directory. Next, you'll need to `create a new release and upload these files as release artifacts
<https://docs.sentry.io/hosted/clients/javascript/sourcemaps/#uploading-source-maps-to-sentry>`__.
Naming your Artifacts
~~~~~~~~~~~~~~~~~~~~~
In Sentry, artifacts are designed to be "named" using the full URL or path at which that artifact is located (e.g. `https://example.org/app.js` or `/path/to/file.js/`).
Since React Native applications are installed to a user's device, on a path that includes unique device identifiers (and thus different for every user),
the React Native plugin strips the entire path leading up to your application root.
This means that although your code may live at the following path:
.. code::
/var/containers/Bundle/Application/{DEVICE_ID}/HelloWorld.app/main.jsbundle
The React Native plugin will reduce this to:
.. code::
/main.jsbundle
Therefore in this example, you should name your artifacts as "/main.jsbundle" and "/main.jsbundle.map".
Source Maps with the Simulator
------------------------------
When developing with the simulator, it is not necessary to build source maps manually, as they are generated automatically on-demand.
Note however that artifact names are completely different when using the simulator. This is because instead of those files existing
on a path on a device, they are served over HTTP via the `React Native packager
<https://github.com/facebook/react-native/tree/master/packager>`__.
Typically, simulator assets are served at the following URLs:
- Bundle: http://localhost:8081/index.ios.bundle?platform=ios&dev=true
- Source map: http://localhost:8081/index.ios.map?platform=ios&dev=true
If you want to evaluate Sentry's source map support using the simulator, you will need to fetch these assets at these URLs (while the React Native
packager is running), and upload them to Sentry as artifacts. They should be named using the full URL at which they are located, including
the query string.
Expanded Usage
--------------
It's likely you'll end up in situations where you want to gracefully
handle errors. A good pattern for this would be to setup a logError helper:
.. code-block:: javascript
function logException(ex, context) {
Raven.captureException(ex, {
extra: context
});
/*eslint no-console:0*/
window.console && console.error && console.error(ex);
}
Now in your components (or anywhere else), you can fail gracefully:
.. code-block:: javascript
var Component = React.createClass({
render() {
try {
// ..
} catch (ex) {
logException(ex);
}
}
});
|
