Skip to content

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.

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.

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:

FieldExampleWhy it’s collected and how it helps you
app_id8a9a1b2c-...Says which of your Shorebird apps this is, from shorebird.yaml, so it gets your patches.
channelstableSays which track to look on (stable unless your app asks for another), so you can test patches before rollout.
release_version1.0.0+1Says which release is installed, so it only gets a patch built for that release.
platformandroidPicks the patch for the right platform.
archaarch64Picks the patch for the right CPU architecture.
current_patch_number3Says which patch the app runs now, so it isn’t sent a patch it already has.
client_id0c7e5f3a-6b1d-4e2f-9a8b-1d2c3e4f5a6bThe 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 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.

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:

EventSent 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 as network, out_of_space or corrupt_patch, so you can tell a flaky network from a broken patch.
  • message: a short description of what went wrong, such as update_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 revision 01aea2e, 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.

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 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-Agent header, 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.

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:

FieldExampleWhat it is
Commandpatch, iosWhich command ran, for which platform.
Outcomefailed, link_percentageWhether it succeeded and, if not, a short reason code. Never the error message, apart from the link-details line above.
Release, patch1.4.2+88, patch 3The release the run made or patched, and the patch it made, if it got that far.
Start, duration17:00:04, 6m12sWhen the run started building this platform, and how long that took.
Build detailslink 87%The same versions, CI provider, yes/no build facts and stage timings listed above, sent whether or not the run published anything.
Build flagsAPI_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 bundle23 MBFor 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 runfalseWhether it was a --dry-run.
Run ID5d0e...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.

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 patch run 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-info sends 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-define values, 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.