From 5ae64d12d10c5a5a3d4aa6cf892bc4409398cf32 Mon Sep 17 00:00:00 2001 From: Noah Martin Date: Wed, 3 Dec 2025 13:17:18 +0100 Subject: [PATCH 1/5] feat: Add iOS auto-update SDK --- .../build-distribution/auto-update.mdx | 20 +--- .../ios/build-distribution/auto-update.mdx | 91 ++++++++++++++++++ .../create-integration-token.mdx | 20 ++++ .../images/create-auth-token.png | Bin .../images/create-new-integration.png | Bin .../images/internal-integration.png | Bin .../build-distribution/images/name-token.png | Bin .../images/set-permissions.png | Bin 8 files changed, 112 insertions(+), 19 deletions(-) create mode 100644 docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx create mode 100644 includes/build-distribution/create-integration-token.mdx rename {docs/platforms/android => includes}/build-distribution/images/create-auth-token.png (100%) rename {docs/platforms/android => includes}/build-distribution/images/create-new-integration.png (100%) rename {docs/platforms/android => includes}/build-distribution/images/internal-integration.png (100%) rename {docs/platforms/android => includes}/build-distribution/images/name-token.png (100%) rename {docs/platforms/android => includes}/build-distribution/images/set-permissions.png (100%) diff --git a/docs/platforms/android/build-distribution/auto-update.mdx b/docs/platforms/android/build-distribution/auto-update.mdx index d3068f3f07fe13..816a7dfda8a70c 100644 --- a/docs/platforms/android/build-distribution/auto-update.mdx +++ b/docs/platforms/android/build-distribution/auto-update.mdx @@ -21,25 +21,7 @@ Make sure your Sentry Java version is at least 8.27.0 and you have the [Sentry A You'll also need an [internal integration token](#create-an-integration-token) with Build Distribution permissions. -## Create an Integration Token - -To use the Auto-Update SDK, you need to create an internal integration token with the appropriate permissions: - -1. Navigate to **Settings > Custom Integrations** in your Sentry organization -2. Click **Create New Integration** - ![Create New Integration =800x](./images/create-new-integration.png) - -3. Select **Internal Integration** and click **Next** - ![Internal Integration =600x](./images/internal-integration.png) - -4. Give your integration a name (e.g., "Build Distribution") - ![Name token =800x](./images/name-token.png) -5. Under **Permissions**, select **Read** next to the **Distribution** scope. - ![Set Permissions =800x](./images/set-permissions.png) -6. Click **Save Changes** -7. Scroll down to the Tokens section and click **New Token** - ![Create New Token =800x](./images/create-auth-token.png) -8. Copy the generated token to your CI secrets as an environment `SENTRY_DISTRIBUTION_AUTH_TOKEN` + ## Installation diff --git a/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx new file mode 100644 index 00000000000000..12720251f0dad5 --- /dev/null +++ b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx @@ -0,0 +1,91 @@ +--- +title: Auto-Update SDK +sidebar_title: Auto-Update SDK +sidebar_order: 10 +description: Enable automatic update checks and installations for internal iOS builds using the Sentry Auto-Update SDK. +--- + + + + + +The Auto-Update SDK is designed for **internal builds only** and should never be used in production builds distributed through the App Store. + + + +The Sentry Auto-Update SDK enables your internal iOS builds to automatically check for and install newer versions distributed through Sentry's Build Distribution. This is particularly useful for distributing nightly, alpha, or beta builds to your internal teams. It is not required to use the Sentry crash reporting SDK to use the iOS Auto-Update SDK. + +## Pre-requisites + +The SDK can only be installed using Swift Package Manager. + +You'll also need an [internal integration token](#create-an-integration-token) with Build Distribution permissions. + + + +## Installation + +Add a dependency on the `SentryDistribution` target contained in the sentry-cocoa package (https://github.com/getsentry/sentry-cocoa) + +```swift {filename:Package.swift} +.package(url: "https://github.com/getsentry/sentry-cocoa", from: "{{@inject packages.version('sentry.cocoa') }}"), + +.target(name: "MyTarget", dependencies: ["SentryDistribution"]), +``` + +## Usage + +Use the SDK by calling `Updater.checkForUpdate(params: )`. In addition to the access token, provide your Sentry org and project slug in the CheckForUpdateParams. For example: + +```swift {filename:MyView.swift} +import SentryDistribution +import SwiftUI + +struct MyView: View { + var body: some View { + Button("Check For Update") { + UpdateUtil.checkForUpdates() + } + } +} + +enum UpdateUtil { + static func checkForUpdates() { + let params = CheckForUpdateParams( + accessToken: "MY_TOKEN", + organization: "MY_ORGANIZATION", + project: "MY_PROJECT") + Updater.checkForUpdate(params: params) { result in + handleUpdateResult(result: result) + } + } + + static func handleUpdateResult(result: Result) { + guard case let .success(releaseInfo) = result else { + if case let .failure(error) = result { + print("Error checking for update: \(error)") + } + return + } + + guard let releaseInfo = releaseInfo.update else { + print("Already up to date") + return + } + + guard let url = Updater.buildUrlForInstall(releaseInfo.downloadUrl) else { + return + } + DispatchQueue.main.async { + Updater.install(url: url) + } + } +} +``` + +## Security Considerations + +- **Internal Use Only**: Never ship the auto-update SDK in production builds destined for public app stores +- **Token Security**: The distribution token is embedded in the app and can be extracted by reverse engineering. Use tokens with only the distribution read permission which is the minimum required permission for the auto-update SDK. + + diff --git a/includes/build-distribution/create-integration-token.mdx b/includes/build-distribution/create-integration-token.mdx new file mode 100644 index 00000000000000..ecddfd177b685b --- /dev/null +++ b/includes/build-distribution/create-integration-token.mdx @@ -0,0 +1,20 @@ +## Create an Integration Token + +To use the Auto-Update SDK, you need to create an internal integration token with the appropriate permissions: + +1. Navigate to **Settings > Custom Integrations** in your Sentry organization +2. Click **Create New Integration** + ![Create New Integration =800x](./images/create-new-integration.png) + +3. Select **Internal Integration** and click **Next** + ![Internal Integration =600x](./images/internal-integration.png) + +4. Give your integration a name (e.g., "Build Distribution") + ![Name token =800x](./images/name-token.png) +5. Under **Permissions**, select **Read** next to the **Distribution** scope. + ![Set Permissions =800x](./images/set-permissions.png) +6. Click **Save Changes** +7. Scroll down to the Tokens section and click **New Token** + ![Create New Token =800x](./images/create-auth-token.png) +8. Copy the generated token to your CI secrets as an environment `SENTRY_DISTRIBUTION_AUTH_TOKEN` + diff --git a/docs/platforms/android/build-distribution/images/create-auth-token.png b/includes/build-distribution/images/create-auth-token.png similarity index 100% rename from docs/platforms/android/build-distribution/images/create-auth-token.png rename to includes/build-distribution/images/create-auth-token.png diff --git a/docs/platforms/android/build-distribution/images/create-new-integration.png b/includes/build-distribution/images/create-new-integration.png similarity index 100% rename from docs/platforms/android/build-distribution/images/create-new-integration.png rename to includes/build-distribution/images/create-new-integration.png diff --git a/docs/platforms/android/build-distribution/images/internal-integration.png b/includes/build-distribution/images/internal-integration.png similarity index 100% rename from docs/platforms/android/build-distribution/images/internal-integration.png rename to includes/build-distribution/images/internal-integration.png diff --git a/docs/platforms/android/build-distribution/images/name-token.png b/includes/build-distribution/images/name-token.png similarity index 100% rename from docs/platforms/android/build-distribution/images/name-token.png rename to includes/build-distribution/images/name-token.png diff --git a/docs/platforms/android/build-distribution/images/set-permissions.png b/includes/build-distribution/images/set-permissions.png similarity index 100% rename from docs/platforms/android/build-distribution/images/set-permissions.png rename to includes/build-distribution/images/set-permissions.png From 5675b5e96676456890d5dd9a1fdf23f91c1e36c9 Mon Sep 17 00:00:00 2001 From: Noah Martin Date: Wed, 3 Dec 2025 15:48:51 +0100 Subject: [PATCH 2/5] PR feedback --- .../ios/build-distribution/auto-update.mdx | 26 +++++++------------ 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx index 12720251f0dad5..44d80bcb425a70 100644 --- a/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx +++ b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx @@ -44,28 +44,20 @@ import SwiftUI struct MyView: View { var body: some View { Button("Check For Update") { - UpdateUtil.checkForUpdates() - } - } -} - -enum UpdateUtil { - static func checkForUpdates() { - let params = CheckForUpdateParams( - accessToken: "MY_TOKEN", - organization: "MY_ORGANIZATION", - project: "MY_PROJECT") - Updater.checkForUpdate(params: params) { result in - handleUpdateResult(result: result) + let params = CheckForUpdateParams( + accessToken: "MY_TOKEN", + organization: "___ORG_SLUG___", + project: "___PROJECT_SLUG___") + Updater.checkForUpdate(params: params) { result in + handleUpdateResult(result: result) + } } } static func handleUpdateResult(result: Result) { guard case let .success(releaseInfo) = result else { - if case let .failure(error) = result { - print("Error checking for update: \(error)") - } - return + // Handle error + return } guard let releaseInfo = releaseInfo.update else { From 5c05dd752944b49b6010a10786474ab835bf9437 Mon Sep 17 00:00:00 2001 From: Noah Martin Date: Wed, 3 Dec 2025 16:07:28 +0100 Subject: [PATCH 3/5] Fix token usage --- .../android/build-distribution/auto-update.mdx | 1 + .../guides/ios/build-distribution/auto-update.mdx | 1 + .../create-integration-token.mdx | 14 ++++++-------- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/platforms/android/build-distribution/auto-update.mdx b/docs/platforms/android/build-distribution/auto-update.mdx index 816a7dfda8a70c..f9a67afdfe5c32 100644 --- a/docs/platforms/android/build-distribution/auto-update.mdx +++ b/docs/platforms/android/build-distribution/auto-update.mdx @@ -22,6 +22,7 @@ Make sure your Sentry Java version is at least 8.27.0 and you have the [Sentry A You'll also need an [internal integration token](#create-an-integration-token) with Build Distribution permissions. +1. Copy the generated token to your CI secrets as an environment `SENTRY_DISTRIBUTION_AUTH_TOKEN` ## Installation diff --git a/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx index 44d80bcb425a70..63692acc23c374 100644 --- a/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx +++ b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx @@ -22,6 +22,7 @@ The SDK can only be installed using Swift Package Manager. You'll also need an [internal integration token](#create-an-integration-token) with Build Distribution permissions. +1. Save the new token, you will need it when using the SDK from Swift. ## Installation diff --git a/includes/build-distribution/create-integration-token.mdx b/includes/build-distribution/create-integration-token.mdx index ecddfd177b685b..6aa06e84875cf1 100644 --- a/includes/build-distribution/create-integration-token.mdx +++ b/includes/build-distribution/create-integration-token.mdx @@ -3,18 +3,16 @@ To use the Auto-Update SDK, you need to create an internal integration token with the appropriate permissions: 1. Navigate to **Settings > Custom Integrations** in your Sentry organization -2. Click **Create New Integration** +1. Click **Create New Integration** ![Create New Integration =800x](./images/create-new-integration.png) -3. Select **Internal Integration** and click **Next** +1. Select **Internal Integration** and click **Next** ![Internal Integration =600x](./images/internal-integration.png) -4. Give your integration a name (e.g., "Build Distribution") +1. Give your integration a name (e.g., "Build Distribution") ![Name token =800x](./images/name-token.png) -5. Under **Permissions**, select **Read** next to the **Distribution** scope. +1. Under **Permissions**, select **Read** next to the **Distribution** scope. ![Set Permissions =800x](./images/set-permissions.png) -6. Click **Save Changes** -7. Scroll down to the Tokens section and click **New Token** +1. Click **Save Changes** +1. Scroll down to the Tokens section and click **New Token** ![Create New Token =800x](./images/create-auth-token.png) -8. Copy the generated token to your CI secrets as an environment `SENTRY_DISTRIBUTION_AUTH_TOKEN` - From c3b68306b99039238be018113bd2e70a48b330f5 Mon Sep 17 00:00:00 2001 From: Noah Martin Date: Wed, 3 Dec 2025 19:20:57 +0100 Subject: [PATCH 4/5] Update wording --- docs/platforms/android/build-distribution/auto-update.mdx | 3 ++- .../apple/guides/ios/build-distribution/auto-update.mdx | 1 - includes/build-distribution/create-integration-token.mdx | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/platforms/android/build-distribution/auto-update.mdx b/docs/platforms/android/build-distribution/auto-update.mdx index f9a67afdfe5c32..062e21df7a1e20 100644 --- a/docs/platforms/android/build-distribution/auto-update.mdx +++ b/docs/platforms/android/build-distribution/auto-update.mdx @@ -22,7 +22,6 @@ Make sure your Sentry Java version is at least 8.27.0 and you have the [Sentry A You'll also need an [internal integration token](#create-an-integration-token) with Build Distribution permissions. -1. Copy the generated token to your CI secrets as an environment `SENTRY_DISTRIBUTION_AUTH_TOKEN` ## Installation @@ -62,6 +61,8 @@ sentry { } ``` +This expect to find the environment variable `SENTRY_DISTRIBUTION_AUTH_TOKEN`, copy the token you generated in the preceding step to this variable in your CI environment. + ### Configuration Options | Option | Description | Default | diff --git a/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx index 63692acc23c374..44d80bcb425a70 100644 --- a/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx +++ b/docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx @@ -22,7 +22,6 @@ The SDK can only be installed using Swift Package Manager. You'll also need an [internal integration token](#create-an-integration-token) with Build Distribution permissions. -1. Save the new token, you will need it when using the SDK from Swift. ## Installation diff --git a/includes/build-distribution/create-integration-token.mdx b/includes/build-distribution/create-integration-token.mdx index 6aa06e84875cf1..8eb6b0de1de584 100644 --- a/includes/build-distribution/create-integration-token.mdx +++ b/includes/build-distribution/create-integration-token.mdx @@ -16,3 +16,4 @@ To use the Auto-Update SDK, you need to create an internal integration token wit 1. Click **Save Changes** 1. Scroll down to the Tokens section and click **New Token** ![Create New Token =800x](./images/create-auth-token.png) +1. Save the generated token, you'll need it to integrate the SDK \ No newline at end of file From 3ee031788b94973d44b4552dba927b5183c10a85 Mon Sep 17 00:00:00 2001 From: Noah Martin Date: Wed, 10 Dec 2025 10:08:53 -0500 Subject: [PATCH 5/5] typos --- docs/platforms/android/build-distribution/auto-update.mdx | 2 +- includes/build-distribution/create-integration-token.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/android/build-distribution/auto-update.mdx b/docs/platforms/android/build-distribution/auto-update.mdx index 062e21df7a1e20..19165816856537 100644 --- a/docs/platforms/android/build-distribution/auto-update.mdx +++ b/docs/platforms/android/build-distribution/auto-update.mdx @@ -61,7 +61,7 @@ sentry { } ``` -This expect to find the environment variable `SENTRY_DISTRIBUTION_AUTH_TOKEN`, copy the token you generated in the preceding step to this variable in your CI environment. +This expects to find the environment variable `SENTRY_DISTRIBUTION_AUTH_TOKEN`, copy the token you generated in the preceding step to this variable in your CI environment. ### Configuration Options diff --git a/includes/build-distribution/create-integration-token.mdx b/includes/build-distribution/create-integration-token.mdx index 8eb6b0de1de584..6332943827e778 100644 --- a/includes/build-distribution/create-integration-token.mdx +++ b/includes/build-distribution/create-integration-token.mdx @@ -15,5 +15,5 @@ To use the Auto-Update SDK, you need to create an internal integration token wit ![Set Permissions =800x](./images/set-permissions.png) 1. Click **Save Changes** 1. Scroll down to the Tokens section and click **New Token** - ![Create New Token =800x](./images/create-auth-token.png) + ![Create New Token =800x](./images/create-auth-token.png) 1. Save the generated token, you'll need it to integrate the SDK \ No newline at end of file