When considering product analytics on ATProto (or any federated service) we need to consider the 3 classes of stakeholders and what each of them need. For this purpose let's consider a hypothetical Bluesky communities feature. Communities have posts similar to Bluesky, but they're private to their community. There are also feeds similar to a "for you" feed that surface posts in your communities that are relevant to you. From this app we lay out our 3 classes of stakeholders and who fits into each of them.
- 1.
The App - Bluesky. This is the application in which a user actually interacts with posts. The App is where any analytics events are generated from. They also are the place where we get things like user identity.
- 2.
The Users - Viewers of the content, the people who are actually using the app, interacting with posts, etc. Users may use an app anonymously or authenticated. For our purposes we should assume that authenticated means having a PDS (although this can be made optional)
- 3.
The Creators and Curators - The Group owner, the Post author, and the feed service. These are the people who have an interest in understanding
Guiding Principles
- 1.
Creators and Curators should be able to see how their creations are being interacted with across the atmosphere without needing to ask permission from every atmosphere app.
- 2.
Users should be able to easily opt-out of tracking and should feel safe switching and trying new apps as they know their data is under their control.
- 3.
Apps should not be able to see events from other apps, even if they're sharing users and records.
The Basic Flow
As a user interacts with an app the app creates analytics events
The analytics events are sent to an aggregator - could be part of the app or a service
The aggregator collects the events into batches identified by a 3 part tuple (App, Creator/Curator, User) in the case that an event applies to multiple Creators / Curators then events are duplicated.
The aggregator writes batches of events to a PDS, leveraging authentication from the app.
At some point later an App owner, Creator, or Curator access an analytics tool to view the event data and extract insights.
PDS Layout
Spaces for analytics follow this format
at://<app did>/space/community.lexicon.analytics/<creator or curator hash>/<user did>/community.lexicon.analytics/<tid>
- 1.
The root authority for the space is the app. The app can read all the data written by it, and request it be deleted.
- 2.
The event data is written to the repo for the user who the events pertain to, Users can delete and modify their own data
- 3.
The creator/curator did is hashed to determine a space key, a creator/curator can be given read access to all the events related to content they created.
In order for a creator/curator to obtain all their records they will need to ask every app that created them for access. This is logistically feasible given 2 things
- 1.
A space access delegate that gives access read access to creator / curator did based on it's hash.
- 2.
A public announce record - Minimally a record for the app did that states it provides analytics in the documented space format. Ideally a record per creator/curator although we should consider if this leaks sensitive data.
What is actually written
At the above path a record provides some aggregate data and points to the CID for a zipped, JSONL record containing the associated events.
Why write a blob instead of putting the raw events.
- 1.
Size: Users will record many thousands of very small events. temporally most will share many attributes so packing them into a JSONL and compressing it makes it very space efficient.
- 2.
Shared: For cases where a series of events belong to more than one creator / curator a single blob can be shared between multiple records.
Responsibilities
The App: An app must capture events and provide a did under which events can be placed. The app did must grant space according to the standard.
The Aggregator: The Aggregator must pack analytics events from one app into efficient blobs and generate appropriate summary data.
The Analytics Tool: The analytics tool must build an index of all apps that a creator / curator has analytics from and join this data into a single queryable data set.
Anonymous Events
Some events will not be associated with an identified user for those cases the aggregator should provide a "PDS like" interface that can participate in spaces, this requires a subset of the PDS interface but when done correctly allows anonymous events to fit the same access patterns as identified ones. When an anonymous user is identified we can write to their PDS clean up the anonymous PDS.
Write Delegates
When logging in and "identifying" a user an app will request write access to it's analytics space. The aggregator app cannot leverage this authentication directly, instead a small app is run by the application that proxies aggregator writes to a PDS.