What Shorebird Collects
This page covers the technical behavior of the open source code Shorebird publishes, and only that:
- The Shorebird updater, which you bundle into your app. It determines what Shorebird collects from your app’s users.
- The Shorebird CLI, which you and your team run. It determines what Shorebird collects about you, your company and your builds.
Everything else about what Shorebird collects and does, such as analytics on its website and console, its servers, how long it keeps data and the vendors it uses, is in Shorebird’s privacy policy. The privacy policy is the legal document; this page is a technical explainer that goes with it. If the two ever disagree, the privacy policy wins.
Each section links to the code it describes, so you can read exactly what it
does. Those links point at specific lines, which can go stale as the code
changes; the code on main is always the current truth.
The updater: data from your app’s users
Section titled “The updater: data from your app’s users”The short version
Section titled “The short version”Your app sends Shorebird what it needs to deliver the right patch, including to the right share of installs in a percentage rollout, to show you how your patches are doing and to count your installs, and nothing else. It sends nothing about who your users are: no names, no accounts, no device identifiers, no location, and nothing from your app’s data.
Patch checks
Section titled “Patch checks”Your app checks for a patch so that your users get your fixes without waiting for an app store release. By default it checks each time it starts (see When do updates happen?). Each check sends:
| Field | Example | Why it’s collected and how it helps you |
|---|---|---|
app_id | 8a9a1b2c-... | Says which of your Shorebird apps this is, from shorebird.yaml, so it gets your patches. |
channel | stable | Says which track to look on (stable unless your app asks for another), so you can test patches before rollout. |
release_version | 1.0.0+1 | Says which release is installed, so it only gets a patch built for that release. |
platform | android | Picks the patch for the right platform. |
arch | aarch64 | Picks the patch for the right CPU architecture. |
current_patch_number | 3 | Says which patch the app runs now, so it isn’t sent a patch it already has. |
client_id | 0c7e5f3a-6b1d-4e2f-9a8b-1d2c3e4f5a6b | The anonymous install identifier, used to count installs and to run percentage rollouts (below). |
Source:
PatchCheckRequest in network.rs.
If there’s a new patch, the app then downloads the patch file. That download is a plain HTTPS request for the file and carries none of the fields above.
The anonymous install identifier
Section titled “The anonymous install identifier”The updater sends the anonymous install identifier for two things, both of which take a way to tell one install from another:
- Counting installs, such as your app’s monthly active users (MAUs) and new installs, which the console shows you.
- Percentage rollouts: when a patch is rolled out to a percentage of installs, the identifier decides whether this install is in that percentage.
Your bill doesn’t use it: plans are priced on patch installs.
Only releases built with Flutter 3.35.7 or newer send it. Releases built with an older Flutter version send no identifier at all, so until your users update to a newer release, some of your installs don’t send one. Those installs don’t take part in percentage rollouts: they get a patch once it’s rolled out to every install.
client_id is a random v4 UUID that the Shorebird updater generates the first
time your app runs. The updater stores it in state.json inside your app’s own
storage (see
What does the Shorebird updater store on disk?).
- It’s random. It isn’t derived from anything on the device.
- It’s per install, not per device. Two Shorebird apps on the same phone get two unrelated identifiers.
- It lasts until the app is uninstalled or its data is cleared. The next launch generates a new one. Release and patch updates keep it.
Source:
generate_client_id in updater_state.rs.
The FAQ has more on what the identifier is and what Shorebird does with it.
Patch events
Section titled “Patch events”Shorebird collects patch events so it can show you, in the Shorebird console, whether each patch is succeeding or failing in the wild: how many devices downloaded it, how many installed it, and how many hit a problem and why. That tells you whether a patch is reaching your users and working, without your app adding any reporting of its own. Your app sends four events:
| Event | Sent when |
|---|---|
__patch_download__ | A patch finished downloading. |
__patch_install__ | A patch was installed and launched successfully. |
__patch_update_failure__ | Downloading or installing a patch failed. |
__patch_install_failure__ | An installed patch failed to launch, so the app rolled back. |
Each event carries the same app_id, release_version, platform, arch and
client_id as a patch check, so it’s counted against the right app, release and
patch and toward your MAUs, plus:
patch_number: the patch the event is about, so the console shows it under that patch.timestamp: when it happened, in seconds since the Unix epoch, so the console can show how a rollout went over time.event_id: a random UUID for the event itself, so an event sent twice is counted once and your numbers stay accurate.
Failure events also carry what you’d need to fix the failure:
failure_category: a short code such asnetwork,out_of_spaceorcorrupt_patch, so you can tell a flaky network from a broken patch.message: a short description of what went wrong, such asupdate_failure: patch 3 failed (...). It’s capped at 256 characters. In releases built with Flutter 3.47.8 or newer, or 3.47.7 at revision01aea2e, the updater replaces the app’s file system paths with placeholders like<storage>before sending it, since those paths can contain a user name. Other releases can send a file path as the error wrote it. Apart from such a path, the message never contains your app’s data or anything about your users.
Events that can’t be sent right away (the device is offline, or the app is about
to roll back a patch that failed) are queued in state.json and sent on a later
launch, so the console’s counts include them.
Source:
PatchEvent and EventType in events.rs,
and the
failure categories in updater.rs.
What the updater doesn’t send
Section titled “What the updater doesn’t send”The fields above are everything the updater sends. In particular, it doesn’t send:
- Device identifiers: no IDFA, IDFV, Android ID, advertising ID, serial number or hardware identifier.
- Device details: no device model, OS version or locale.
- Anything about your users: no names, emails, account IDs or user IDs from your app.
- Your app’s data: nothing your app stores or displays.
- Crash reports or logs: a failed patch sends only the short failure message above.
- Analytics: no screens, sessions, taps or usage beyond the patch check and patch events.
- Location.
The CLI: data from you and your team
Section titled “The CLI: data from you and your team”The shorebird command line tool, which you and your team run, talks to
Shorebird as your signed-in account. It uploads your release and patch files so
Shorebird can deliver them to your users. With them it sends:
- With each release and patch: the platform; Flutter and Shorebird versions; your operating system’s name and version; and Xcode’s version for Apple builds. When a build or patch goes wrong, support can see your toolchain without asking you for it, and Shorebird knows which Flutter versions and platforms its customers rely on, so it keeps supporting them.
- Your
shorebird.yaml, so support can see how your app is configured when you ask for help. - Whether the build ran on CI and which CI provider, so Shorebird can make its CI integrations work for the providers you use.
- A few yes/no facts about the build, such as whether a patch changed assets or native code, so support can tell why a patch behaves as it does.
- How long each stage of the build took, so Shorebird can find and fix the steps that slow your builds down.
- With every request: the CLI’s version, your operating system, your machine’s
CPU architecture (CLI 1.6.135 and newer) and the Dart version, in the
User-Agentheader, so Shorebird can tell you when your CLI needs an update and keep older versions working until then.
The CLI never sends logs or source code. It sends your compiled app code only in
a release or patch, and in a debug bundle you choose to
share. Apart from what that compiled code holds, such as file paths from the
machine that built it, the CLI doesn’t send your machine’s name, your user name
or file paths. The only error text it sends is why Shorebird couldn’t read an
iOS patch’s link details, when that happens: one line of about 200 characters at
most, with everything from the first file path on replaced by <path>. Apart
from the build history records below, it has no analytics or usage tracking.
Source:
UpdateReleaseMetadata,
CreatePatchMetadata,
BuildEnvironmentMetadata,
BuildTraceSummary
and
build_history.dart.
Build history
Section titled “Build history”When a shorebird release or shorebird patch run ends, the CLI sends a record
of it, whether it succeeded or failed. Shorebird keeps these records as your
organization’s build history, so you can see how
often your builds fail, why, and how long they take. The CLI sends them for
every plan; the Enterprise plan shows them in the console and the API. Runs are
recorded by Shorebird 1.6.139 and newer.
Each record holds one platform’s run:
| Field | Example | What it is |
|---|---|---|
| Command | patch, ios | Which command ran, for which platform. |
| Outcome | failed, link_percentage | Whether it succeeded and, if not, a short reason code. Never the error message, apart from the link-details line above. |
| Release, patch | 1.4.2+88, patch 3 | The release the run made or patched, and the patch it made, if it got that far. |
| Start, duration | 17:00:04, 6m12s | When the run started building this platform, and how long that took. |
| Build details | link 87% | The same versions, CI provider, yes/no build facts and stage timings listed above, sent whether or not the run published anything. |
| Build flags | API_HOST: 9f86d0... | The names of the --dart-define values the run passed, including those from --dart-define-from-file, with a SHA-256 hash of each value, and a hash of --target. Never the values or paths. The hashes aren’t salted, so a guessed value can be checked against them. |
| Debug bundle | 23 MB | For a patch run: whether you passed --share-debug-info and, if the run wrote a debug bundle, its size, so Shorebird can tell whether to accept the bundle. Shorebird keeps the flag, as why the bundle was shared, and the size only when the bundle is shared. |
| Dry run | false | Whether it was a --dry-run. |
| Run ID | 5d0e... | A random ID that ties together the records of one run that built several platforms. |
Who ran it is the account or API key the CLI signed in as, which Shorebird already knows from the request.
Runs that stop before Shorebird has confirmed your app (and, for a patch, found the release), runs stopped with Ctrl-C, and runs that end because the CLI crashed aren’t recorded. The CLI waits at most 5 seconds to send a record, or 30 seconds when the run wrote a debug bundle.
Besides showing it to you, Shorebird reads build history in aggregate, across customers, to improve the product, such as finding which build stages are slow or which failures are common.
Debug bundles (opt-in)
Section titled “Debug bundles (opt-in)”When shorebird patch links an iOS patch against its release, it writes
build/patch-debug.zip, the patch’s debug bundle. Shorebird needs it to tell
why a patch failed or linked poorly. The CLI sends it to Shorebird only when you
choose to share it:
- Every failed patch, with your organization’s setting. Turn on Share
debugging information with Shorebird on the General tab of your
organization’s settings in the
Shorebird console. It’s off by default, it’s
available on every plan, and only the organization’s Admins and Owner can
change it. With it on, each
shorebird patchrun that fails after writing a bundle sends it. A run that succeeds doesn’t send its bundle. - One run, with a flag.
shorebird patch --share-debug-infosends that run’s bundle, whether it fails or succeeds and whatever your organization’s setting, for when you’re working through a problem with Shorebird.
Both need Shorebird 1.6.140 or newer. When a bundle is sent, the CLI prints
Shared debugging information with Shorebird (org setting) or
(--share-debug-info). The CLI uploads it once that platform’s patch run ends,
and waits at most 5 minutes for it. Sending never changes the run’s result: if
the upload fails or runs out of time, the CLI warns
Could not share debugging information with Shorebird.
The bundle holds:
- The compiled Dart code (AOT snapshots) of the release, and of the patch at
each stage of linking, including stages your app never runs. It can contain
your app’s function and class names, its string constants, including
--dart-definevalues, and file paths from the machine that built it, such as your project’s path. - The linker’s reports on those snapshots: listings of their classes, functions and constants, and which code the patch shares with the release and which it doesn’t.
It doesn’t hold your source code, assets, logs or Shorebird credentials.
Shorebird engineers use a shared bundle only to support you. Each one is listed on its release’s Artifacts tab in the console, under Shared with Shorebird, with when it was shared, the platform and how the run ended. Members who can create releases see that tab, and can download a shared bundle or delete it there. Deleting the release, the app or the organization deletes its bundles too. Moving an app to another organization moves its bundles with it, onto the same release’s Artifacts tab there. Turning the setting off stops failed runs from sharing; it doesn’t delete bundles already shared.
Your own copy stays in build/patch-debug.zip. To send it by hand instead, see
Sending a patch-debug.zip to Shorebird.
Source:
build_history.dart
(when it’s sent) and
apple.dart
(what goes in it).
- Everything this page doesn’t cover, including how long Shorebird keeps what it collects: Shorebird’s privacy policy.
- Shorebird’s commitments for your app’s users’ data, as a signed agreement: Shorebird’s Data Processing Agreement.
- Questions for a security review or procurement questionnaire: contact@shorebird.dev.