Skip to content

docs(builder-codes): add tool-agnostic user analytics section for app developers #2082

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bvsakhil wants to merge 1 commit into from
Closed

docs(builder-codes): add tool-agnostic user analytics section for app developers #2082

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions docs/specifications/builder-codes/for-app-developers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

<Steps>
<Step title="Identify Users by Wallet Address">
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.
</Step>

<Step title="Record Key Moments in the User Journey">
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)
</Step>

<Step title="Use Onchain Data for Transactions">
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
</Step>

<Step title="Build Three Dashboards">
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.
</Step>
</Steps>
Loading