From 4fab2546409ca956f070635c1791606272b86bc8 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich Date: Fri, 11 Oct 2024 19:55:44 +0200 Subject: [PATCH 1/4] feat: Update CodePush guide for Debug IDs --- .../react-native/manual-setup/codepush.mdx | 103 ------------------ .../sourcemaps/uploading/codepush.mdx | 92 ++++++++++++++++ redirects.js | 4 + 3 files changed, 96 insertions(+), 103 deletions(-) delete mode 100644 docs/platforms/react-native/manual-setup/codepush.mdx create mode 100644 docs/platforms/react-native/sourcemaps/uploading/codepush.mdx diff --git a/docs/platforms/react-native/manual-setup/codepush.mdx b/docs/platforms/react-native/manual-setup/codepush.mdx deleted file mode 100644 index 12dc93deec66f..0000000000000 --- a/docs/platforms/react-native/manual-setup/codepush.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: CodePush -sidebar_order: 40 -description: "Learn about using CodePush with our React Native SDK." ---- - -To use Sentry together with CodePush, pass `release` and `dist` to `Sentry.init`. Our suggestion is to store them in an `app.json`, or you can just use the `package.json`. These values need to be unique to each version of your codebase and match the version on the source maps exactly, or they might not be symbolicated. - -When you set a custom `release` and `dist`, or manually upload source maps, you will need to disable the automatic source map upload script. Learn more in the [Disable the automatic source maps upload script](/platforms/react-native/sourcemaps/#2-disable-the-automatic-source-maps-upload-script) documentation. - -For more information on the `release` and `dist` parameters, check out the section on [Source Maps](/platforms/react-native/sourcemaps/). - -We recommend using the format `${BUNDLE_ID}@${APP_VERSION}+codepush:${DIST}` for release names. - -```javascript -import { release, dist } from "app.json"; - -Sentry.init({ - // ... - release, - dist, -}); -``` - -If you need to use `codePush.getUpdateMetadata`, you will have to wait to initialize the Sentry SDK until the Promise is resolved. - - - -This method is not recommended as any errors or crashes that happen before the initialization of the Sentry SDK will not be caught. - - - -```javascript -import codePush from "react-native-code-push"; - -codePush.getUpdateMetadata().then((update) => { - if (update) { - Sentry.init({ - // ... - release: `${update.appVersion}+codepush:${update.label}`, - dist: update.label, - }); - } -}); -``` - -If you're wrapping your root component with `Sentry.wrap` to access Performance features, `codePush` should be the outer most function because it needs access to the root component in order to swap out the bundle. - -```javascript -export default codePush(Sentry.wrap(App)); -``` - -## Making Releases - -After updating your CodePush release, you have to upload the new assets to Sentry: - -When making the release with CodePush, make sure to output the bundle and source maps by specifying `--sourcemap-output-dir ./build` and `--output-dir ./build`. - -```bash -appcenter codepush release-react -a {APP} -d {DEPLOYMENT} --sourcemap-output-dir ./build --output-dir ./build -``` - -Exporting the `SENTRY_PROPERTIES` will tell sentry-cli to use the properties in your project. The sentry-wizard install step should have generated this file for you. Alternatively, you can either pass it via parameters or a global settings file. To find more about this refer to [Working with Projects](/product/cli/configuration/#sentry-cli-working-with-projects). - -```bash -export SENTRY_PROPERTIES=./ios/sentry.properties -``` - -Upload the outputted bundle and source maps to Sentry. -If you use custom deployment names in CodePush, you will need to use `--deployment` to specify the deployment. - -```bash -sentry-cli react-native appcenter {APP} ios ./build ./build/CodePush --deployment {DEPLOYMENT} --dist {DIST} -``` - -For non-macOS devices building for iOS, you will need to pass extra parameters that can't be computed automatically (`--bundle-id` and `--version-name`). -Within your `Info.plist`, `--version-name` corresponds to `CFBundleShortVersionString` . - -On iOS: - -```bash -sentry-cli react-native appcenter {APP} ios ./build ./build/CodePush --deployment {DEPLOYMENT} --dist {DIST} --bundle-id {BUNDLE_ID} --version-name {VERSION_NAME} -``` - -If you don't want to use the automatically computed release format, instead of passing `--bundle-id` and `--version-name`, you'll need to pass the `--release-name` parameter. - -```bash -sentry-cli react-native appcenter {APP} ios ./build ./build/CodePush --deployment {DEPLOYMENT} --dist {DIST} --release-name {RELEASE_NAME} -``` - - - -Make sure to export the `APPCENTER_ACCESS_TOKEN` in your environment in order to run the `appcenter` commands above. Otherwise you will get the following error: - -```bash -Command 'appcenter codepush deployment history' requires a logged in user. Use the 'appcenter login' command to log in. -``` - -You can find more information about this in the [AppCenter CLI](https://docs.microsoft.com/en-us/appcenter/cli/#logging-in) documentation. - - - -If you still have issues with CodePush source maps, you can refer to [Source Maps for Other Platforms](/platforms/react-native/sourcemaps/) to manually bundle and upload source maps to Sentry. diff --git a/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx new file mode 100644 index 0000000000000..a529fb8d84947 --- /dev/null +++ b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx @@ -0,0 +1,92 @@ +--- +title: CodePush +sidebar_order: 100 +description: "Upload source maps for CodePush releases." +--- + +Sentry's React Native SDK works out of the box with CodePush. To see readable stack traces in the product, you must upload source maps to Sentry. This guide explains how to upload source maps for CodePush releases, that are created with the AppCenter CLI. + +## Prerequisities + +- [Sign up for an account](https://sentry.io/signup/) +- [Set up Sentry React Native SDK](/platforms/react-native) +- [Set up Sentry Metro Plugin](/platforms/react-native/manual-setup/metro) + - The plugin ensures that Debug IDs are enabled and used to link source maps to bundles. + +## Wrap Your App + +Ensure `codePush` is the outer most function because it needs access to the root component in order to swap out the bundle. + +```javascript +export default codePush(Sentry.wrap(App)); +``` + +## Create CodePush Release + +To ensure Sentry can symbolicate events from your CodePush releases, you need to generate and upload the necessary assets. When creating a CodePush release, include the `--sourcemap-output-dir` flag to generate source maps. This allows you to upload these files to Sentry in the next step. + +```bash {tabTitle:JSC} +appcenter codepush release-react \ + --app "${APP_NAME}" \ + --deployment-name "${DEPLOYMENT_NAME}" \ + --output-dir ./build \ + --sourcemap-output-dir ./build +``` + +```bash {tabTitle:Hermes} +rm -rf ./build +CODEPUSH_COMMAND="appcenter codepush release-react \ + --app \"${APP_NAME}\" \ + --deployment-name \"${DEPLOYMENT_NAME}\" \ + --use-hermes \ + --output-dir ./build \ + --sourcemap-output-dir ./build" + +DEBUG_ID=$(eval "$CODEPUSH_COMMAND" | tee /dev/tty | grep -o 'Bundle Debug ID: [0-9a-f-]*' | sed 's/Bundle Debug ID: //') + +# Find the .map file and add the debug_id to it +MAP_FILE=$(find ./build -name "*.map" -type f) +jq -c ". + {\"debug_id\": \"${DEBUG_ID}\"}" "${MAP_FILE}" > "${MAP_FILE}.tmp" +mv "${MAP_FILE}.tmp" "${MAP_FILE}" +``` + +### Notes + +If you are using Hermes make sure `jq` is installed on your system. If it's not, you can install it using your system's package manager. For example `apt-get install jq` on Ubuntu, or `brew install jq` on macOS with Homebrew. + +## Upload Source Maps + +Upload source maps for your CodePush release by setting up your environment variables and running the `react-native appcenter` command. + +Before running the upload command, make sure to set up your environment variables. + +```bash {tabTitle:Environment Variables} +export SENTRY_ORG=___ORG_SLUG___ +export SENTRY_PROJECT=___PROJECT_SLUG___ +export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ +``` + +To upload source maps for your CodePush release, use the `react-native appcenter` command. + +```bash {tabTitle:Sentry CLI} +npx sentry-cli sourcemaps upload \ + --debug-id-reference \ + --strip-prefix /path/to/project/root \ + ./build +``` + +## Notes + +### Optional Release and Dist + +To associate the uploaded artifacts with the CodePush release, use the `--release` and `--dist` options. Make sure that events reported by the SDK have the same `release` and `dist` values. You can follow the default schema `${BUNDLE}@${VERSION}+${BUILD}` for `release` and `${BUILD}` for `dist` or set the values manually in `Sentry.init`. This is optional when uploading artifacts with Debug IDs. + +### Using `codePush.getUpdateMetadata` + +Use `Sentry.setTag` to associate the CodePush Update Label with the captured events. + +```javascript +codePush.getUpdateMetadata().then((update) => { + Sentry.setTag('codepush', update.label); +}); +``` diff --git a/redirects.js b/redirects.js index 7f077aeedc2d1..4ea84e4a4b2aa 100644 --- a/redirects.js +++ b/redirects.js @@ -597,6 +597,10 @@ const userDocsRedirects = [ source: '/api/rate-limits/', destination: '/api/ratelimits/', }, + { + source: '/platforms/react-native/manual-setup/codepush/', + destination: '/platforms/react-native/sourcemaps/uploading/codepush/', + }, ]; /** From c6b46e43793fbb7d759b8cc67d5ec2c0817c688f Mon Sep 17 00:00:00 2001 From: Krystof Woldrich <31292499+krystofwoldrich@users.noreply.github.com> Date: Mon, 14 Oct 2024 15:48:12 +0200 Subject: [PATCH 2/4] Update docs/platforms/react-native/sourcemaps/uploading/codepush.mdx Co-authored-by: LucasZF --- docs/platforms/react-native/sourcemaps/uploading/codepush.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx index a529fb8d84947..1ab3aaf59b8cb 100644 --- a/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx +++ b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx @@ -6,7 +6,7 @@ description: "Upload source maps for CodePush releases." Sentry's React Native SDK works out of the box with CodePush. To see readable stack traces in the product, you must upload source maps to Sentry. This guide explains how to upload source maps for CodePush releases, that are created with the AppCenter CLI. -## Prerequisities +## Prerequisites - [Sign up for an account](https://sentry.io/signup/) - [Set up Sentry React Native SDK](/platforms/react-native) From 1263df8adaae384ff4639dde5ffafb632d488c77 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich <31292499+krystofwoldrich@users.noreply.github.com> Date: Mon, 14 Oct 2024 15:49:37 +0200 Subject: [PATCH 3/4] Update docs/platforms/react-native/sourcemaps/uploading/codepush.mdx Co-authored-by: LucasZF --- docs/platforms/react-native/sourcemaps/uploading/codepush.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx index 1ab3aaf59b8cb..59472a6f73a83 100644 --- a/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx +++ b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx @@ -79,7 +79,7 @@ npx sentry-cli sourcemaps upload \ ### Optional Release and Dist -To associate the uploaded artifacts with the CodePush release, use the `--release` and `--dist` options. Make sure that events reported by the SDK have the same `release` and `dist` values. You can follow the default schema `${BUNDLE}@${VERSION}+${BUILD}` for `release` and `${BUILD}` for `dist` or set the values manually in `Sentry.init`. This is optional when uploading artifacts with Debug IDs. +To associate the uploaded artifacts with the CodePush release, use the `--release` and `--dist` options, which are parameters of the sentry-cli command. Make sure that events reported by the SDK have the same `release` and `dist` values. You can follow the default schema `${BUNDLE}@${VERSION}+${BUILD}` for `release` and `${BUILD}` for `dist` or set the values manually in `Sentry.init`. This is optional when uploading artifacts with Debug IDs. ### Using `codePush.getUpdateMetadata` From 69f6fd6cb52e0fed1274fa143aa74e0200807986 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich <31292499+krystofwoldrich@users.noreply.github.com> Date: Mon, 14 Oct 2024 15:53:29 +0200 Subject: [PATCH 4/4] Update codepush.mdx --- docs/platforms/react-native/sourcemaps/uploading/codepush.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx index 59472a6f73a83..e56ec63c1f440 100644 --- a/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx +++ b/docs/platforms/react-native/sourcemaps/uploading/codepush.mdx @@ -83,7 +83,7 @@ To associate the uploaded artifacts with the CodePush release, use the `--releas ### Using `codePush.getUpdateMetadata` -Use `Sentry.setTag` to associate the CodePush Update Label with the captured events. +If you rely on `codePush.getUpdateMetadata` to get the CodePush Update Label, use `Sentry.setTag` to associate the CodePush Update Label with the captured events. This will enable you to filter events in the Sentry UI based on the label. We discourage using `codePush.getUpdateMetadata` to initialize the SDK as it delays the initialization and errors before the CodePush Update Label is available won't be reported to Sentry. ```javascript codePush.getUpdateMetadata().then((update) => {