From 25f32f81235cdb94084e0e66b0facc8ae2aeb5f0 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Fri, 4 Sep 2026 17:12:08 -0700 Subject: [PATCH] docs: explain the anonymous install identifier in the FAQ Customers ask what the anonymous device identifier named in our privacy policy actually is, and whether it can be tied back to one of their users. We had no single place to point them. Adds two FAQ entries under Teams, access, and privacy, each leading with a direct answer before the detail: - What it is: a random ID Shorebird creates and stores inside their app, to allow Shorebird to count how many copies are active. A random v4 UUID created on first run, stored in state.json in the app's own storage, per-install rather than per-device, not the IDFA, IDFV or Android advertising ID, and gone on uninstall or a clear-data. - What Shorebird does with it: counts, and nothing else. Shorebird collects nothing it could be correlated against, and the counts are produced as aggregates. Never shown to anyone, never returned by an API, never sold or shared for advertising. Standardizes on "anonymous install identifier" as the name, since it is the most accurate description of the value, and lists the other names for it once. Links the privacy policy and the DPA, and points anyone who needs more detail at privacy@shorebird.dev. Also links the source that creates and sends the value, so customers can verify the payload themselves, and adds IDFA and IDFV to the spell-check dictionary. --- .cspell.yaml | 2 + src/content/docs/code-push/faq.mdx | 104 ++++++++++++++++++++++++++++- 2 files changed, 104 insertions(+), 2 deletions(-) diff --git a/.cspell.yaml b/.cspell.yaml index a282d18f..5724dbf8 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -53,6 +53,8 @@ words: - graphql - geocodes - hotfixes + - idfa + - idfv - jank - janky - lateinit diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index 239d492c..f1ef3831 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -488,8 +488,8 @@ Requests sent from the app to Shorebird servers include: - patch_number (generated as part of `shorebird patch android`) - arch (e.g. `aarch64`, needed to send down the right patch) - platform (e.g. `android`, needed to send down the right patch) -- client_id (anonymous, aggregated, per-app identifier used to provide active - user metrics) +- client_id (the anonymous install identifier, used to count active users, see + [What is the anonymous install identifier?](#what-is-the-anonymous-install-identifier)) The code for this is public in the [updater package](https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs) @@ -563,6 +563,106 @@ No. Shorebird servers never see or store your source code. When you run `shorebird release` or `shorebird patch` the `shorebird` tool only uploads the same compiled app binary that you send to the app stores. +### What is the anonymous install identifier? + +It is a random ID that Shorebird creates and stores inside your app, to allow +Shorebird to count how many copies of your app are active in a given month. That +count is the number Shorebird bills you on and reports back to you. + +Shorebird is designed to never know anything about _your_ users. It sends back +only what it needs in order to deliver patches and to bill for them, and this +identifier is the piece that makes the monthly count possible. + +You will see other names for the same value. Shorebird's +[privacy policy](https://shorebird.dev/privacy/) calls it an anonymous device +identifier, and in Shorebird's source code the field is named `client_id`. +Shorebird has referred to it in the past, in issues and support threads, as the +device ID or the install ID. These are all the same thing, and this page uses +"anonymous install identifier" throughout, because that is the most accurate +description of what it is. + +Shorebird creates the value the first time your app runs, as a random v4 UUID, +and stores it in `state.json` inside your app's own storage (see +[What does the Shorebird updater store on disk?](#what-does-the-shorebird-updater-store-on-disk)). +It is sent each time your app checks for a new patch. + +It does not identify a device, and it does not identify a person. It identifies +a single install of your app. Shorebird does not read the IDFA, IDFV, Android +advertising ID, or any other identifier that has meaning outside of Shorebird. +Because Shorebird creates the value itself: + +- It is per-install, not per-device. Two Shorebird apps on the same phone get + two unrelated identifiers, and Shorebird has no mechanism to link them. +- It survives release and patch updates, and goes away when the user uninstalls + your app or clears its app data. The next launch generates a new one. +- It carries no information about the user. It is not derived from anything on + the device, and Shorebird never correlates it with any other data, in keeping + with Shorebird's [privacy policy](https://shorebird.dev/privacy/). + +Shorebird therefore cannot tell one of your users from another, identify a +person, or link an install back to an account in your app. + +What Shorebird can do with it is count. It can tell how many unique installs of +your app were active in a given month, which is the number your bill is based on +and the number behind the monthly active users shown in the +[Shorebird console](https://console.shorebird.dev). + +### What does Shorebird do with the anonymous install identifier? + +Shorebird counts with it, and nothing else. It goes into counts of how many +unique installs of your app were active, daily as well as monthly. Those counts +are what Shorebird shows you in the +[Shorebird console](https://console.shorebird.dev) and what your bill is based +on, and they are all that comes back out. + +Shorebird collects nothing the identifier could be correlated against. Your app +sends no location, no device fingerprint, and no advertising identifier — the +[full list of what is sent](#what-information-is-sent-to-shorebird-servers) is a +short set of fields identifying the app, its build, and the architecture it is +running on. Shorebird records nothing else about the request alongside it. + +As with any service on the internet, the infrastructure Shorebird runs on +produces its own operational logs, and those can include network details such as +the IP address a request arrived from. Shorebird does not collect these +deliberately, keeps them only for a limited period for traffic management and +abuse prevention, and never joins them to the anonymous install identifier or to +anything else. They are covered by Shorebird's +[privacy policy](https://shorebird.dev/privacy/). + +The numbers you see are computed as aggregates. Active user counts are produced +as HyperLogLog sketches, a statistical structure that estimates how many +distinct installs were seen without the sketch itself containing any of the +identifiers that produced the count. That aggregate is what reaches your console +and your invoice. + +What Shorebird can say about the identifier in every case: + +- It is never shown to you or to anyone else. No Shorebird API returns it, and + there is no way to set, query, or look up an individual identifier. What + Shorebird surfaces, in the console and on your invoice, is aggregate counts. +- It is never correlated with anything else. It is not joined against your + account data, against other apps, or against any third-party data set. +- It is never sold, and never shared for advertising. + +How long Shorebird retains what it collects is described in Shorebird's +[privacy policy](https://shorebird.dev/privacy/), which is the authoritative +statement. If you need these commitments as a signed agreement rather than a +policy, Shorebird offers a +[Data Processing Agreement](https://shorebird.dev/dpa/). And if you need more +specific detail for a security review or a procurement questionnaire, reach out +to Shorebird's [privacy team](mailto:privacy@shorebird.dev) and Shorebird will +answer directly. + +The code that creates the identifier and the code that sends it are both public +and can be reviewed at any time: + +- `generate_client_id` in + [`updater_state.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/updater_state.rs), + which generates and stores the value +- `PatchCheckRequest` in + [`network.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs), + which is the full payload sent to Shorebird servers + ### Will your app still work if you cancel your Shorebird subscription? Yes. Apps built with Shorebird will continue to function normally (as if they