From 9f559decde7a7ae78a763339496510da32147af9 Mon Sep 17 00:00:00 2001 From: Akhil Date: Tue, 6 Oct 2026 20:58:53 +0530 Subject: [PATCH] docs(builder-codes): add tool-agnostic user analytics section for app developers Adds a Track User Analytics section to the Builder Codes for App Developers page describing what to measure and where each signal comes from, without naming analytics tools or wallet libraries. Supersedes #2077. --- .../builder-codes/for-app-developers.mdx | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index 3ac3cabe8..ebe8c6194 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -239,3 +239,46 @@ To confirm your Builder Code is being appended correctly: - Select transaction type - Enter the transaction or UserOperation hash - Click the **Check Attribution** button + +## Track User Analytics + +To understand how people use your app, such as active users, retention and conversion, track user activity in your app alongside your onchain data. This section covers what to measure and where each signal comes from. Which analytics stack you use and how you set it up is up to you. + +| Metric | Data source | +|---|---| +| Daily, weekly and monthly active users | Wallet connections and app sessions | +| D1, D7 and D30 retention | Returning wallet addresses | +| Conversion funnel (open, connect, first successful transaction) | App sessions, wallet connections and onchain transactions | +| Onchain activity attributed to your app | Transactions that carry your Builder Code | + + + + Use the connected wallet address, lowercased, as the user identifier, and clear it when the wallet disconnects. This lets you join in-app activity with onchain activity for the same user. + + Wallet address should be the only identifier you collect. Do not record emails, names, government IDs or payment details. + + + + Record when a user: + + 1. Opens the app, along with the referrer or campaign source + 2. Connects a wallet + 3. Submits a transaction, along with what the transaction does in your app (for example, mint, swap or deposit) + + + + Onchain data is the source of truth for transaction outcomes. For each transaction, look at: + + - **Builder Code:** whether the calldata carries your Builder Code suffix (see [Verify Attribution](#verify-attribution)) + - **Sender:** the wallet address that sent it, which matches the user identifier from step 1 + - **Status:** whether the transaction receipt shows success or a revert + + + + With these signals in place, set up: + + 1. **Growth:** daily, weekly and monthly active users, plus new vs. returning wallets. + 2. **Retention:** D1, D7 and D30 cohorts by the week a wallet was first seen. + 3. **Funnel:** open → connect → first successful transaction, split by referrer or campaign source. + +