# For AI agents (/ai-agents)
## Give your agent the skill [#give-your-agent-the-skill]
[`SKILL.md`](/SKILL.md) is an instruction file for coding agents, in the open
[Agent Skills](https://agentskills.io) format. It walks the agent through the whole integration: the tracker in your
framework, wallet events, OpenTelemetry for your API, registering your contracts, and then a test that checks the data
arrived. It stops and asks you for anything that needs your wallet.
Install it as a project skill:
```sh
mkdir -p .claude/skills/usagemap-instrument
curl -fsSL https://docs.usagemap.dev/SKILL.md -o .claude/skills/usagemap-instrument/SKILL.md
```
Then ask: *"Add UsageMap analytics to this app."*
Codex and other agents that support Agent Skills look in `.agents/skills/`:
```sh
mkdir -p .agents/skills/usagemap-instrument
curl -fsSL https://docs.usagemap.dev/SKILL.md -o .agents/skills/usagemap-instrument/SKILL.md
```
Any other assistant: paste the file's link into the chat and ask it to follow it.
Your agent needs your **site key** (from the website's **Snippet** tab) and, for APIs, an **ingest token**. The site
key is public. Put the token in an environment variable or your secret store, never in the code or the chat.
## Docs for language models [#docs-for-language-models]
| File | What's in it |
|---|---|
| [`/llms.txt`](/llms.txt) | An index of every page in these docs, with a one-line summary |
| [`/llms-full.txt`](/llms-full.txt) | All pages in one Markdown file, ready to paste into a context window |
| Any page as Markdown | Every page has a Markdown version. Use the **Copy Markdown** button at the top of a page. |
## Ask your numbers from your assistant (coming) [#ask-your-numbers-from-your-assistant-coming]
A read-only MCP server is built and will run at `https://app.usagemap.dev/mcp`. It isn't deployed yet; this section
will say so when it is.
With it, an assistant such as Claude can answer questions like "how many verified visitors did we have last month?"
from your own project's numbers. You connect it with a **share key** (`scfa_pub_…`, project → **Sharing**), which
can only read your metrics document and your signed snapshots. It can never change anything.
# Already using an APM? (/api/existing-apm)
OpenTelemetry's environment variables describe one destination. If you already export to an APM, add UsageMap as a
**second** destination instead of replacing the first.
## Recommended: fan out from your own Collector [#recommended-fan-out-from-your-own-collector]
Point your services at an OpenTelemetry Collector you run. It sends everything to your APM as before, and a filtered
copy (only the HTTP server metric, with a minimal set of attributes) to UsageMap. Your APM key never leaves your
infrastructure.
```yaml title="otel-collector.yaml"
receivers:
otlp:
protocols:
grpc: { endpoint: 0.0.0.0:4317 }
http: { endpoint: 0.0.0.0:4318 }
processors:
memory_limiter: { check_interval: 1s, limit_percentage: 80, spike_limit_percentage: 20 }
batch: {}
filter/usagemap_http_server_only:
error_mode: ignore
metric_conditions:
- not (metric.name == "http.server.request.duration" or metric.name == "http.server.duration")
transform/usagemap_minimal_attrs:
error_mode: ignore
metric_statements:
- keep_keys(datapoint.attributes, ["http.route", "http.request.method", "http.response.status_code", "error.type", "url.scheme", "network.protocol.version", "http.method", "http.status_code", "http.target"])
- keep_keys(resource.attributes, ["service.name", "service.namespace", "service.version", "service.instance.id", "deployment.environment.name"])
exporters:
otlp_http/apm:
endpoint: https://apm.example
headers: { api-key: "${env:APM_API_KEY}" }
otlp_http/usagemap:
endpoint: https://e1.usagemap.dev
headers: { Authorization: "Bearer ${env:USAGEMAP_TOKEN}" }
compression: gzip
sending_queue: { enabled: true }
retry_on_failure: { enabled: true }
service:
pipelines:
traces/apm: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlp_http/apm] }
metrics/apm: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlp_http/apm] }
logs/apm: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlp_http/apm] }
metrics/usagemap:
receivers: [otlp]
processors: [memory_limiter, filter/usagemap_http_server_only, transform/usagemap_minimal_attrs, batch]
exporters: [otlp_http/usagemap]
```
## Alternative: a second exporter in code [#alternative-a-second-exporter-in-code]
You can also add a second metric exporter in your app's code, with UsageMap's endpoint and token, next to your APM's.
With Node.js, Python or Rust, leave `OTEL_EXPORTER_OTLP_HEADERS` and `OTEL_EXPORTER_OTLP_METRICS_HEADERS` **unset**
and put your APM key in code. Those SDKs merge the variables into every exporter: Node.js and Python would send your
APM key to UsageMap, and Rust would replace the UsageMap token (and every request would fail with `401`). Go, .NET
and a Collector are not affected.
## Send one signal, not two [#send-one-signal-not-two]
Send **either** the HTTP server metric **or** server spans for a service, not both, or its requests are counted
twice. Metrics are the recommended choice. Spans are only needed for frameworks that produce no server metric, such as
Next.js with `@vercel/otel`.
# API analytics (/api)
UsageMap reads the standard HTTP server metric that every OpenTelemetry SDK already produces
(`http.server.request.duration`). You don't add a vendor SDK, and your code stays the same.
## Before you start [#before-you-start]
**Register the service.** In your project, open **API services → Register an API service**. The service name must match
your `OTEL_SERVICE_NAME`.
**Create an ingest token.** Open **Ingest tokens**, create one (optionally limited to this service) and copy it. It
starts with `scfa_ing_` and is shown only once, so store it in your secret manager.
## Connect your API [#connect-your-api]
No code change. Install two packages:
```sh
npm install --save-exact @opentelemetry/auto-instrumentations-node@0.83.0 @opentelemetry/instrumentation@0.301.1
```
Then start your app like this:
```sh
OTEL_SERVICE_NAME=my-api \
OTEL_EXPORTER_OTLP_ENDPOINT=https://e1.usagemap.dev \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${USAGEMAP_TOKEN}" \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_METRICS_EXPORTER=otlp OTEL_TRACES_EXPORTER=none OTEL_LOGS_EXPORTER=none \
OTEL_RESOURCE_ATTRIBUTES="service.instance.id=${HOSTNAME}" \
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs \
--import @opentelemetry/auto-instrumentations-node/register app.mjs
```
For CommonJS apps, drop the `--experimental-loader` line and use `--require` instead of `--import`.
```txt title="requirements.txt"
opentelemetry-distro==0.66b2
opentelemetry-exporter-otlp-proto-http==1.45.2
opentelemetry-instrumentation-fastapi==0.66b2
```
Add a flush on shutdown, so that the last minute of data isn't lost on restart:
```python title="app.py"
from contextlib import asynccontextmanager
from fastapi import FastAPI
from opentelemetry import metrics
@asynccontextmanager
async def lifespan(_app):
yield
getattr(metrics.get_meter_provider(), "shutdown", lambda: None)()
app = FastAPI(lifespan=lifespan)
```
```sh
OTEL_SERVICE_NAME=my-api \
OTEL_EXPORTER_OTLP_ENDPOINT=https://e1.usagemap.dev \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${USAGEMAP_TOKEN}" \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_METRICS_EXPORTER=otlp OTEL_TRACES_EXPORTER=none OTEL_LOGS_EXPORTER=none \
OTEL_SEMCONV_STABILITY_OPT_IN=http \
OTEL_RESOURCE_ATTRIBUTES="service.instance.id=${HOSTNAME}" \
opentelemetry-instrument uvicorn app:app --host 0.0.0.0 --port 8000
```
```sh
go get go.opentelemetry.io/otel@v1.47.0 go.opentelemetry.io/otel/sdk/metric@v1.47.0 \
go.opentelemetry.io/contrib/exporters/autoexport@v0.72.0 \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@v0.72.0
```
```go title="main.go"
reader, err := autoexport.NewMetricReader(ctx) // reads OTEL_* from the environment
if err != nil {
log.Fatal(err)
}
res, err := resource.New(ctx, resource.WithService(), resource.WithFromEnv(), resource.WithTelemetrySDK())
if err != nil {
log.Fatal(err)
}
mp := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader), sdkmetric.WithResource(res))
otel.SetMeterProvider(mp)
defer mp.Shutdown(context.Background()) // flushes the last interval
mux := http.NewServeMux()
mux.HandleFunc("GET /accounts/{id}", getAccount) // the pattern becomes the route
log.Fatal(http.ListenAndServe(":8080", otelhttp.NewHandler(mux, "api")))
```
```sh
OTEL_SERVICE_NAME=my-api
OTEL_EXPORTER_OTLP_ENDPOINT=https://e1.usagemap.dev
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20scfa_ing_...
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_METRICS_EXPORTER=otlp
OTEL_RESOURCE_ATTRIBUTES=service.instance.id=api-1
```
```toml title="Cargo.toml"
[dependencies]
opentelemetry = "0.33.1"
opentelemetry_sdk = "0.33.1"
opentelemetry-otlp = { version = "0.33.1", features = ["reqwest-rustls"] }
opentelemetry-instrumentation-tower = { version = "0.19.0", features = ["axum"] }
```
```rust title="main.rs"
let exporter = opentelemetry_otlp::MetricExporter::builder().with_http().build()?;
let mp = SdkMeterProvider::builder()
.with_resource(Resource::builder().build()) // reads OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES
.with_periodic_exporter(exporter)
.build();
global::set_meter_provider(mp.clone()); // before building the layer
let app = axum::Router::new()
.route("/accounts/{id}", axum::routing::get(account))
.layer(opentelemetry_instrumentation_tower::http::server::Layer::new()); // after the routes
```
Use the same environment variables as for Go, without `OTEL_METRICS_EXPORTER`. The `axum` feature is required, or every
request lands under `{unknown}`.
## Edge runtimes and Stellar SDK calls [#edge-runtimes-and-stellar-sdk-calls]
Both packages below are not yet on the public npm registry. Until they are, use the environment variables above on
servers.
`@scf-analytics/edge-otel` wraps a fetch-style handler (Cloudflare Workers, Vercel Edge, Next.js route handlers, Deno,
Bun) and exports the same request metric, with route templates, without an OpenTelemetry SDK:
```ts title="worker.ts"
import { optionsFromEnv, withUsageMap } from "@scf-analytics/edge-otel";
import app from "./app";
export default withUsageMap(app, (env) => ({
...optionsFromEnv(env), // wrangler secret put OTEL_EXPORTER_OTLP_HEADERS
routes: ["/.well-known/stellar.toml", "/auth", "/sep24/transactions/:id"],
}));
```
The export never delays the response. If the configuration is missing or invalid, the wrapper switches itself off and
your handler runs unchanged.
`@scf-analytics/stellar-otel` measures the calls your backend makes with `@stellar/stellar-sdk` 17: latency per RPC
method and Horizon route, and the outcome of submissions, polls and simulations. It records through your own
OpenTelemetry setup, and never records an address, hash, XDR, key or URL.
```ts
import { rpc, Horizon } from "@stellar/stellar-sdk";
import { instrumentStellarRpc, instrumentHorizon } from "@scf-analytics/stellar-otel";
export const server = new rpc.Server("https://soroban-testnet.stellar.org");
instrumentStellarRpc(server, { network: "testnet" });
instrumentHorizon(new Horizon.Server("https://horizon-testnet.stellar.org"), { network: "testnet" });
```
These show up under **By Stellar surface** on the API dashboard. They describe the health of your outbound calls,
and never count as API traffic.
Any OpenTelemetry SDK that exports the HTTP server duration metric over OTLP/HTTP works. Already exporting to
an APM such as Datadog, Grafana or Honeycomb? [Send a copy to UsageMap](/api/existing-apm).
## Test with curl [#test-with-curl]
Send one data point by hand, without touching your app. A `200` means accepted; it appears on the API dashboard within
about two minutes as the route `/curl-test`.
```sh
curl -sS -i https://e1.usagemap.dev/v1/metrics \
-H "Authorization: Bearer $USAGEMAP_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"resourceMetrics":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"my-api"}},{"key":"service.instance.id","value":{"stringValue":"curl-test"}}]},"scopeMetrics":[{"scope":{"name":"curl-test"},"metrics":[{"name":"http.server.request.duration","unit":"s","histogram":{"aggregationTemporality":1,"dataPoints":[{"attributes":[{"key":"http.request.method","value":{"stringValue":"GET"}},{"key":"http.route","value":{"stringValue":"/curl-test"}},{"key":"http.response.status_code","value":{"intValue":"200"}}],"startTimeUnixNano":"'$(( $(date +%s) - 60 ))000000000'","timeUnixNano":"'$(date +%s)000000000'","count":"1","sum":0.012,"bucketCounts":["0","1","0"],"explicitBounds":[0.005,0.025]}]}}]}]}]}'
```
The **Integration kit** in the app gives you this command with your own service name filled in.
## What is kept [#what-is-kept]
Service name and instance, environment, route, HTTP method, status code, duration.
Every other metric and attribute, logs, query strings, headers and request bodies.
Stellar accounts and contracts in paths become `{account}` and `{contract}`; secrets, tokens and e-mails become `{redacted}`.
Up to 50 requests per second per project, 4 MiB per request (compressed). Over the limit you get `429` with `Retry-After`, and SDKs retry by themselves.
The API dashboard's **Data quality** section shows exactly what was received and what was dropped, and why.
# Your dashboard (/dashboard)
Everything lives in [app.usagemap.dev](https://app.usagemap.dev). After you sign in, **Your projects** lists every
project you belong to. Open one to see its tabs.
## Where to find what [#where-to-find-what]
| I want to see… | Go to |
|---|---|
| The big picture for the last 30 days | Project → **Overview** |
| Page views, visitors, referrers, countries, devices | Project → website → **Dashboard** |
| Wallet connections and signatures | Project → website → **Wallets** |
| Funnels, goals and journeys | Project → website → **Reports** |
| Whether my snippet works | Project → website → **Installation check** |
| API requests, errors and latency | Project → **API services** → service → **Dashboard** |
| What was filtered out, and why | Project → **Trust and anomalies** |
| A public page or badge for my project | Project → **Sharing** |
| A signed report of a period | Project → **Traction snapshots** |
## Overview [#overview]
The project's home page. Four tiles cover the last 30 days: **Verified page views**, **Visitors**, **API requests** and
**On-chain invocations**. Below them are any anomaly flags and a sparkline for each website.
## Website dashboard [#website-dashboard]
Page views, unique visitors, visits, bounce rate, average visit duration and suspect page views.
A chart of verified vs raw traffic, with anomaly flags marked. Turn on **Compare with previous period** for a second line.
Referrers, top pages, countries, devices, browsers, operating systems and custom events.
**Download daily figures (CSV)** for any range.
Pick a range at the top: the last 24 hours, 7, 30 or 90 days, 12 months, all time, or **Custom days**.
## API dashboard [#api-dashboard]
Requests, server errors (5xx), client errors (4xx) and p50 / p95 / p99 latency, then **Status codes**, **Routes**
(with a CSV export), **By Stellar surface** for Horizon and RPC calls, **Availability objective** with its error
budget, and **Data quality**, which shows what was received but not kept.
## Verified, raw and suspect [#verified-raw-and-suspect]
UsageMap checks every event before counting it, and always shows you the result:
| | Meaning |
|---|---|
| **Verified** | Passed every check. This is the headline number. |
| **Suspect** | Counted in *raw* only: for example, an unverified domain, data-centre traffic or a missing proof of work. |
| **Rejected** | Never counted: for example, a page that isn't on one of your domains. |
The **Trust and anomalies** tab lists the reasons, day by day. You can add a note to a flagged day, for example
"launch on Product Hunt", so that anyone reading your numbers knows why it spiked.
# Features (/features)
## Website analytics [#website-analytics]
Page views, unique visitors, visits, bounce rate and average visit duration, with a verified vs raw toggle.
Referrers, top pages, countries, devices, browsers, operating systems and your own custom events.
Route changes are picked up automatically in Next.js, React, Vue, Svelte and any app using the History API.
Build a funnel from pages and events, set goals, and see the paths people take through your site.
## Stellar-specific [#stellar-specific]
From "wallet dialog opened" to "transaction submitted", by wallet type (Freighter, xBull, LOBSTR, Ledger, …) and
network.
Count passkey sign-ins and smart wallets created with Passkey Kit or Smart Account Kit.
Daily invocations, successes and distinct callers of your verified Soroban contracts on mainnet.
See which API calls hit Horizon or Soroban RPC, next to your own endpoints.
## API analytics [#api-analytics]
Requests, 4xx and 5xx errors and status codes per route, from standard OpenTelemetry.
p50, p95 and p99 latency per route, plus an availability objective with an error budget.
For Node.js and Python, environment variables are enough. Go and Rust need a few lines.
Account IDs, contract IDs, secrets and e-mails in paths are replaced before storage. Query strings are always dropped.
## Trust and sharing [#trust-and-sharing]
Every event is checked for bots, automation, data-centre traffic and replays. You always see how much was filtered and why.
Unusual spikes are flagged, and you can annotate a day ("launch on Product Hunt").
Opt in to a public page for your project, and embed a live badge in your README or site.
Freeze a period's numbers into a signed snapshot that anyone can verify, for example for a grant report.
## Privacy [#privacy]
Nothing is stored in the visitor's browser except an opt-out flag, if they choose to opt out.
No IP addresses, raw user agents, query strings, page titles or wallet addresses are ever stored.
Global Privacy Control and Do Not Track are honoured. An optional consent mode waits for your banner.
Data is stored in the EU (Sweden), with backups in the same region.
E-mail alerts, webhooks and a public directory of projects are not part of UsageMap today.
# Welcome to UsageMap (/)
UsageMap tells you how your Stellar project is used: **visits to your website, wallet connections, calls to your API and
invocations of your contracts**, in one dashboard. It does this without cookies, without storing IP addresses, and
without ever recording a visitor's wallet address.
From zero to your first counted page view in about five minutes.
Everything UsageMap measures, on one page.
Give your coding agent our `SKILL.md` and let it do the integration.
A tour of the dashboard: where each number lives.
## What you can integrate [#what-you-can-integrate]
One script tag, or a few lines in Next.js, Nuxt, SvelteKit, Astro, React and others. [Set it up →](/web)
Connect and sign funnels for Stellar Wallets Kit, Freighter, Albedo, xBull, LOBSTR and passkeys. [Wallets →](/wallets)
Standard OpenTelemetry from Node.js, Python, Go, Rust or your own Collector. [API analytics →](/api)
Register your Soroban contracts and see daily on-chain usage next to your traffic. [Contracts →](/onchain)
## How it works [#how-it-works]
**You add a small tracker** (about 3 KB) to your site, or point your API's OpenTelemetry exporter at UsageMap.
**UsageMap checks every event.** Bots, data-centre traffic and replayed requests are filtered out or marked as
suspect, so your numbers hold up when someone else looks at them.
**You see verified numbers** in the dashboard, and you can share them on a public page, as a badge or as a signed
snapshot.
No cookies, no fingerprinting, no IP addresses, no query strings, no page titles and no wallet addresses are ever
stored. Whether your site still needs a consent prompt depends on where you and your visitors are, so a consent
mode is built in. [What we collect →](/privacy)
# Smart contracts (/onchain)
UsageMap can count how often your contracts are used on the Stellar network: **daily invocations, successful
invocations and distinct callers**, on mainnet. It reads public ledger data; you don't install anything.
### Prove you own a Stellar account [#prove-you-own-a-stellar-account]
In your project, open **Verification** and link the Stellar account that deployed (or administers) your contracts, by
signing a message with it.
### Register your contracts [#register-your-contracts]
Open **Set-up wizard → Stellar contracts** (or **Register your Stellar contracts**) and add each contract ID (`C…`)
with its network, mainnet or testnet. A contract is **verified** when its deployer or admin is one of your linked
accounts.
No contracts? Choose **no footprint** so the dashboard stops asking.
### See the numbers [#see-the-numbers]
The **Overview** tile **On-chain invocations** shows the last 30 days for your verified mainnet contracts, and the
website's **Wallets** tab shows the same counts next to the wallet funnel.
On-chain counting is off until a project owner or admin turns it on. There is no switch in the app yet: send
`PATCH /v1/tenants/{project_id}` with `{"onchain_correlation_enabled": true}` while signed in. The project's
**Overview** shows whether it is on.
On-chain counts are shown **next to** your web and wallet numbers, never joined with them: UsageMap does not know
which visitor made which transaction, by design.
Only contract IDs can be registered today. Issuing accounts, app accounts and WASM hashes aren't supported yet.
# Privacy and data (/privacy)
## Never stored [#never-stored]
IP addresses, raw user-agent strings, cookies, cross-site identifiers, wallet addresses and transaction hashes.
Query strings (including UTM tags), `#fragments`, page titles and full referrer URLs. Only the referrer's host is kept.
Lists of visitors, session replays, city or region, and anything that could identify one person.
Stellar secret seeds, tokens, API keys and e-mail addresses found in paths are replaced with `{redacted}` before storage.
## What is collected [#what-is-collected]
| Source | Data |
|---|---|
| Website, **standard** profile | Page path, referrer host, screen-size class, language, country (derived from a shortened IP address that is then discarded), device, browser and OS family, custom events |
| Website, **strict** profile | Page path only, plus country, device, browser and OS family |
| Wallets | Wallet type, network, outcome and a duration bucket |
| APIs | Service, route (with IDs replaced), method, status code and duration |
| Contracts | Public on-chain data about your registered contracts |
If you turn off the **visitor identifier** for a website, only page views, countries and devices are counted, with no
unique visitors.
## Visitor choices [#visitor-choices]
- **Global Privacy Control** and **Do Not Track** are honoured: the tracker sends nothing.
- **Opt-out**: `optOut()` stops sending and stores one flag in the browser.
- **Consent mode**: nothing is sent before your banner calls `grantConsent()`. See [consent mode](/web/events-and-consent#consent-mode).
## Retention [#retention]
| Data | Kept for |
|---|---|
| Individual web events | 90 days |
| Hourly figures | 25 months |
| Daily figures | As long as the project exists |
| Backups | Cleared within 56 days |
## Erasing data [#erasing-data]
Open **Data erasure** in your project. Choose one website, one API service or the whole project, narrow it down by
days, path pattern, event name or property, preview what will be deleted, then confirm. You get a completion report
when it's done.
## Where data is stored [#where-data-is-stored]
In the EU: Sweden Central (Microsoft Azure), with backups in the same region.
# Projects and team (/projects-and-team)
## Projects [#projects]
A project groups your websites, API services and contracts. You can create up to three projects. Each one has a
status:
| Status | Meaning |
|---|---|
| **Awaiting approval** | Your project is waiting for review; events are not counted yet |
| **Active** | Everything is counted |
| **Suspended** | Paused by the UsageMap team; events are refused |
| **Removed** | No longer active |
## Team and roles [#team-and-roles]
Open **Team → Invite someone** to create an invitation code (it starts with `scfi_` and is valid for 1 to 168 hours).
Send it to your teammate; they paste it at **Accept an invitation** after signing in. There is no invitation e-mail.
| Role | Can do |
|---|---|
| **owner** | Everything, including removing the project |
| **admin** | Manage members, invitations, websites, services and tokens |
| **member** | Work with websites and services, see all analytics |
| **viewer** | Read analytics only |
## Verification levels [#verification-levels]
The more you prove, the more weight your numbers carry. **Verification** shows where you are:
**L0 Registered**: you created the project. Limited to 2 websites, 1 API service and 50,000 events a day.
**L1 Domain verified**: a DNS TXT record, a `/.well-known/` file or an HTML meta tag.
**L2 Stellar account linked**: you signed with an account listed in your domain's `stellar.toml`.
**L3 Registry match**: your project matches an entry in a public Stellar project registry.
**L4 Approved**: reviewed by the UsageMap team.
## Ingest tokens [#ingest-tokens]
API services send data with an **ingest token** (`scfa_ing_…`). Create one under **Ingest tokens**. You can limit it
to some services and give it an expiry date. You can have up to 5 active tokens. A token is shown only once.
Creating or revoking one asks you to sign in again, and a revoked token stops working within a minute.
## Sign-in [#sign-in]
You sign in with a Stellar wallet signature: no password is ever stored. Under **Account** you can link more sign-in
identities and manage passkeys.
# Quickstart (/quickstart)
### Sign in [#sign-in]
Open [app.usagemap.dev](https://app.usagemap.dev) and sign in with a **Stellar wallet**: Freighter, xBull, Albedo,
LOBSTR, Hana or any wallet that can sign a message. Hardware wallets and multisig accounts can sign a transaction
instead. There is no password to create.
### Create your project [#create-your-project]
Choose **Find your SCF project** to look your project up in the public Stellar project registries and fill the form in
for you, or **Create a project** and type a name and a short name (used in links).
Some projects are reviewed before they count traffic. Until then the project shows **Awaiting approval**.
### Add your website [#add-your-website]
In the project, choose **Add a website**. Keep the defaults (profile **standard**, visitor identifier **On**) unless
you need the [strict profile](/web#profiles). Then open **Settings → Domains** and add the domain your site runs
on.
### Paste the snippet [#paste-the-snippet]
Open the website's **Snippet** tab and copy the tag. It already contains your site key and the right `integrity`
hash. Put it in the `` of every page:
```html title="index.html"
```
Using a framework? See [framework guides](/web/frameworks).
### See your first event [#see-your-first-event]
Deploy, open your site in a normal browser window, then open the website's **Installation check** tab. Within about a
minute it shows your first event and whether it was counted.
Events from `localhost` or preview URLs are only counted after you add them as a **dev origin**, and they are kept
for 24 hours, never mixed into your real numbers. Browsers with Global Privacy Control turned on (Brave does this by
default) send nothing at all, by design.
### Verify your domain [#verify-your-domain]
Back in **Settings → Domains**, choose **Verify by** DNS TXT record, a file under `/.well-known/`, or an HTML meta tag.
Until your domain is verified, its page views are marked as *suspect*.
## Next steps [#next-steps]
In the app, the project's **Set-up wizard** and **Integration kit** walk you through the same steps, with your own
site key, domain and ready-to-run `curl` tests filled in.
# Reference (/reference)
## Hosts [#hosts]
| Host | Used for |
|---|---|
| `https://app.usagemap.dev` | The app, the public stats pages and the metrics document |
| `https://e1.usagemap.dev`, `https://e2.usagemap.dev` | Tracker files and data ingest (web and OpenTelemetry). Two independent hosts; use either |
| `https://status.usagemap.dev` | Service status |
## Keys and tokens [#keys-and-tokens]
| Prefix | What it is | Where to get it | Secret? |
|---|---|---|---|
| *(22 characters)* | Site key, identifies a website in the tracker tag | Website → **Snippet** | No, it's public |
| `scfa_ing_` | Ingest token for OpenTelemetry | Project → **Ingest tokens** | **Yes** |
| `scfa_pub_` | Share key, reads one metrics document | Project → **Sharing** | Yes |
| `scfi_` | Team invitation code | Project → **Team** | Yes, until used |
## Limits [#limits]
| | Limit |
|---|---|
| Tracker batch | 10 events or 8 KiB |
| Custom event | 10 properties, each value up to 100 characters |
| OpenTelemetry request | 4 MiB compressed, 16 MiB uncompressed |
| OpenTelemetry rate | 50 requests per second per project |
| Data-point age | Up to 48 hours old, up to 5 minutes in the future |
| Paths | 12 segments, then `{rest}` |
| New projects (L0) | 2 websites, 1 API service, 50,000 events a day |
| Dev origins | 10 per website, events kept 24 hours |
| Ingest tokens | 5 active per project |
## Tracker versions [#tracker-versions]
Each version is published at a fixed URL and never changes:
`https://e1.usagemap.dev/lib//.js`. The list of versions with their hashes is at
[`/lib/manifest.json`](https://e1.usagemap.dev/lib/manifest.json).
| Version | standard.js | strict.js |
|---|---|---|
| **1.1.0** (current) | `sha384-AYjFWyBUxxvOL92oDDKxAus7EAPjONT2RDrOiuPh4XUiEJNKkMaZqGVBDw4Lqn0+` | `sha384-ttV+rR22bWKREx01kjl8WFwxw9PYYHc60cbX3fEWCbzlJikl4ERzGJiGEyNDjvhv` |
## OpenTelemetry endpoints [#opentelemetry-endpoints]
| Path | |
|---|---|
| `POST /v1/metrics` | Metrics (OTLP/HTTP, protobuf or JSON). OTLP/gRPC is also accepted |
| `POST /v1/traces` | Server spans, converted to metrics, then discarded |
| `POST /v1/logs` | Not accepted (`404`) |
# Share your numbers (/sharing)
Your numbers are private until you choose to share them. All sharing is set up under the project's **Sharing** and
**Traction snapshots** tabs.
Turn on public stats and your project gets a page at `app.usagemap.dev/p/your-short-name` that anyone can open
without signing in. It shows web and API usage, the traffic that was not counted, and your signed snapshots.
The public page offers **Embed a badge**: a live badge for your README or website.
Freeze a period into a signed document, with presets for an SCF build tranche, a campaign, a quarter or a custom
range. Anyone can check one at `app.usagemap.dev/verify`.
`GET https://app.usagemap.dev/public/v1/projects/your-short-name/metrics.json`, rebuilt hourly. Public when public
stats are on; otherwise send a share key.
## Share keys [#share-keys]
To share your metrics document without making it public, create a **share key** (`scfa_pub_…`) under **Sharing** and
send it in a header:
```sh
curl -H "Authorization: Bearer $USAGEMAP_SHARE_KEY" \
https://app.usagemap.dev/public/v1/projects/your-short-name/metrics.json
```
A share key only reads that one document. It can't see dashboards, change settings or send data. Keys in a URL are
refused, so they don't end up in logs.
## Anonymous reports [#anonymous-reports]
Under a website's **Settings**, **Anonymous reports** hides rows with fewer than 10 visitors and rounds the rest to
the nearest 10, so that small numbers can't single anyone out.
# Troubleshooting (/troubleshooting)
The website's **Installation check** tab shows every event that arrived in the last minutes and its verdict. Turn on
**Debug mode** there to see the server's reason in each response's `X-Scf-Debug` header.
## Website [#website]
- **No request at all:** the tag isn't in the served page. Check the page source and purge your CDN cache.
- **Integrity error in the console:** the `integrity` hash doesn't match the version. Copy the snippet from the app
again; never edit the version without the hash.
- **Content Security Policy error:** add `https://e1.usagemap.dev` to `script-src`.
- **`ERR_BLOCKED_BY_CLIENT`:** an ad blocker. Test without it. Don't proxy the tracker through your own server.
This is by design when the browser has **Global Privacy Control** or **Do Not Track** on (Brave turns GPC on by
default), when the visitor opted out, or when consent mode is waiting for `grantConsent()`. Test in a clean browser
profile.
If a request to `/v1/c` is blocked, your CSP's `connect-src` needs **both** `https://e1.usagemap.dev` and
`https://e2.usagemap.dev`.
| Installation check says | Fix |
|---|---|
| `origin_mismatch` | The page runs on a host that isn't one of your domains. Add the domain, or add it as a dev origin. |
| only `dev` events | You're testing on a dev origin. That's correct; those are never counted. Deploy to production. |
| `tenant_pending` | Your project is awaiting approval. |
| `404 unknown_site` | Wrong site key, or the website was archived. |
| `410 withdrawn` | That tracker version was withdrawn. Copy the current snippet. |
| `429` | Rate limit or daily quota reached. The tracker retries by itself. |
- `domain_unverified`: verify your domain under **Settings → Domains**.
- `proof_missing`: the page was closed before the proof of work finished. Normal for very short visits.
- `automation_flag`, `net_datacenter`, `multiplicity_high`: anti-inflation checks: automated browsers, cloud
networks, or many visitors from one network.
Attach the adapter once, after `init()`, with tracker 1.1.0 or later. Signing and submit events only appear as daily
counts in the **Wallets** funnel, never on a single visit.
## API [#api]
| You see | Likely cause | Fix |
|---|---|---|
| `401` | Missing, wrong or revoked token, or the header isn't `Authorization=Bearer%20scfa_ing_…` | Create a token; check the `%20` |
| `403` | The project is awaiting approval or suspended | Wait for approval |
| `404` on `/v1/logs` | Logs aren't accepted | Set `OTEL_LOGS_EXPORTER=none` |
| `429` / `503` | Over the rate limit, or a node is restarting | Nothing: SDKs retry with `Retry-After` |
| Nothing in the dashboard | The 60-second export interval hasn't passed, or the process exited before flushing | Wait a minute; add the shutdown flush from your stack's guide |
| Routes show as `{unknown}` | Your framework doesn't report the route | Express needs its instrumentation; axum needs the `axum` feature |
| Counted twice | The service sends both metrics and spans | Send one: set `OTEL_TRACES_EXPORTER=none` |
# Wallet analytics (/wallets)
The wallet adapters turn your Stellar wallet library's calls into a **wallet funnel**: dialog opened → wallet selected →
connected → sign requested → approved or rejected → transaction submitted.
The adapters send only fixed categories: wallet type, network, outcome and a duration bucket. They never send
addresses, transaction hashes, XDR, amounts, memos or error messages.
## Stellar Wallets Kit [#stellar-wallets-kit]
Attach the adapter once, after the tracker has started:
```ts title="analytics.ts"
import { init } from "@scf-analytics/tracker";
import { attachWalletsKit } from "@scf-analytics/tracker/wallets-kit";
import { StellarWalletsKit } from "@creit.tech/stellar-wallets-kit";
init({ site: "YOUR_SITE_KEY" });
const detach = attachWalletsKit(StellarWalletsKit); // call detach() to undo
```
It works with Stellar Wallets Kit 2.x, including references to `signTransaction` that your app copied before attaching
(as Scaffold Stellar does). For kit versions up to 1.9.5, use `attachWalletsKitV1`.
The adapters ship in the npm package, which is not yet on the public npm registry.
## Other wallets and passkeys [#other-wallets-and-passkeys]
If you use a wallet's own API instead of the kit, wrap it:
```ts
import { wrapFreighter } from "@scf-analytics/tracker/wallets";
```
Available: `wrapFreighter`, `wrapAlbedo`, `wrapXBull`, `wrapLobstr`, `wrapHana`, `wrapHot`, and `wrapInjected` with
`detectInjectedWallet` for other injected wallets.
```ts
import { attachPasskeyKit } from "@scf-analytics/tracker/passkey";
```
Also `attachPasskeyServer` and `attachSmartAccountKit`. They count passkey sign-ins and smart wallets created.
```ts
import { attachHorizonServer, attachRpcServer } from "@scf-analytics/tracker/wallets";
```
These count transaction submissions made through your Horizon or Soroban RPC client.
## What is recorded [#what-is-recorded]
| Event | When |
|---|---|
| `wallet_modal_opened`, `wallet_modal_closed` | The wallet dialog opens or closes |
| `wallet_selected` | The visitor picks a wallet |
| `wallet_connect`, `wallet_disconnect` | A wallet connects or disconnects |
| `sign_requested`, `sign_approved`, `sign_rejected` | A signature is asked for, given or refused |
| `tx_submitted` | A transaction is sent to the network |
| `smart_wallet_created`, `passkey_used` | Passkey and smart-wallet activity |
Signing, submission and passkey events are **counted per day only**: they are never attached to a visit, so nobody
can link a signature to a browsing session.
## Where to see it [#where-to-see-it]
Open your website and choose the **Wallets** tab. You'll see the funnel, a breakdown **By wallet type** (Freighter,
Albedo, xBull, LOBSTR, Hana, HOT, Rabet, WalletConnect, Ledger, Trezor, …) and a network filter. If you also
[register your contracts](/onchain), their on-chain counts are shown next to the funnel.
# Custom events and consent (/web/events-and-consent)
## Custom events [#custom-events]
Page views are automatic. For anything else, call `track()` with an event name and up to 10 properties.
```js
window.scf.track("signup", { plan: "free" });
window.scf.track("swap_completed", { pair: "XLM-USDC", amount_bucket: "100-1k" });
```
The script tag exposes the tracker as `window.scf`. If your code might run before the tracker has loaded, queue the
call; it is replayed in order once the tracker is ready:
```html
```
| | Rule |
|---|---|
| Event name | 1–50 characters: letters, digits and `_ . : -`, starting with a letter or digit |
| Properties | At most 10 per event |
| Property name | Lowercase, starts with a letter, up to 32 characters: `a-z`, `0-9`, `_` |
| Property value | A string of up to 100 characters, a number, or `true` / `false` |
`track()` returns `false` and sends nothing if a value looks like personal or secret data: an e-mail address, a phone
number, an IP address, a token, a Stellar address or key, or a federation address. Send buckets (`"100-1k"`) and
categories, never identifiers.
Custom events appear under **Breakdowns → Custom events** on the website dashboard, and you can use them as steps in
funnels and as goals under **Reports**.
## Consent mode [#consent-mode]
By default the tracker sets no cookies and stores nothing on the visitor's device. If your policy still requires
consent first, turn on consent mode: the tracker then sends nothing until you call `grantConsent()`.
```html
```
The **Snippet** tab has this ready to copy: choose **HTML with consent mode**.
## Opt-out [#opt-out]
Give visitors an opt-out link or toggle:
```js
window.scf.optOut(); // stops sending, and remembers it in this browser
window.scf.optIn(); // undoes it
```
The opt-out flag (`scf_optout`) is the only thing the tracker ever stores in the browser. Visitors with Global Privacy
Control or Do Not Track turned on are already opted out automatically.
## All tracker methods [#all-tracker-methods]
| Method | What it does |
|---|---|
| `track(name, props?)` | Sends a custom event. Returns `false` if it was refused. |
| `optOut()` / `optIn()` | The visitor's own choice, remembered in their browser. |
| `grantConsent()` / `revokeConsent()` | For consent mode, called from your banner. |
| `destroy()` | Stops the tracker and removes its listeners. |
## Debugging [#debugging]
There are two switches, one for each side:
In the app: website → **Installation check** → **Debug mode**, for 1 minute up to 24 hours. While it is on, every
answer to your site carries an `X-Scf-Debug` header with the verdict, for example
`class=suspect; reasons=domain_unverified`. Look for it in the browser's network tab.
With the npm package, call `debug()` from `@scf-analytics/tracker/debug` before `init()`, in development only. The
console then explains what was sent and why something wasn't, for example "Global Privacy Control is on".
# Framework guides (/web/frameworks)
The tracker works the same everywhere: put the tag in the `` of every page, once. Route changes in single-page
apps are detected automatically, so you never call anything on navigation.
In every example, replace the `src`, `integrity` and `data-site` values with the ones from your website's **Snippet**
tab.
App Router: add the tag to the root layout.
```tsx title="app/layout.tsx"
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
```ts title="nuxt.config.ts"
export default defineNuxtConfig({
app: {
head: {
script: [
{
src: "https://e1.usagemap.dev/lib/1.1.0/standard.js",
integrity: "sha384-AYjFWyBUxxvOL92oDDKxAus7EAPjONT2RDrOiuPh4XUiEJNKkMaZqGVBDw4Lqn0+",
crossorigin: "anonymous",
"data-site": "YOUR_SITE_KEY",
defer: true,
},
],
},
},
});
```
```html title="src/app.html"
%sveltekit.head%
```
`is:inline` stops Astro from bundling the tag, which would break the `integrity` check. View transitions
(``) are supported.
```astro title="src/layouts/Layout.astro"
```
```html title="index.html"
```
React Strict Mode runs effects twice in development; that is fine, the tracker starts only once.
Framework mode: add the tag to the `Layout` in `app/root.tsx`.
```tsx title="app/root.tsx"
export function Layout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
```html title="index.html"
```
Vue Router's history mode is detected automatically.
Eleventy, Hugo, Jekyll, Docusaurus, WordPress or any CMS: put the tag into the shared base template or the "code in
``" setting, so that it appears on every page.
```html
```
## Check it works [#check-it-works]
Deploy, then open your site in a normal browser window (without Global Privacy Control).
In the browser's network tab, you should see the tracker file load and a `POST` to `/v1/c`.
Open **Installation check** in the app: your event appears within about a minute, with its verdict.
Nothing showing up? See [troubleshooting](/troubleshooting).
# Add the tracker (/web)
The UsageMap tracker is a small script (about 3 KB gzipped) with no dependencies. It records a page view on load and on
every route change, and sends nothing else unless you call [`track()`](/web/events-and-consent).
## Install [#install]
Copy the tag from your website's **Snippet** tab in the app and paste it into the `` of every page:
```html
```
| Attribute | What it does |
|---|---|
| `src` | A fixed version of the tracker. Files never change once published, and there is no `latest` URL. |
| `integrity` | The file's hash. The browser refuses a file that doesn't match, so nobody can swap the code under you. |
| `data-site` | Your site key (22 characters), from the app. |
| `data-consent="required"` | Optional. Send nothing until you call `grantConsent()`. See [consent mode](/web/events-and-consent#consent-mode). |
The npm package `@scf-analytics/tracker` is not yet published on the public npm registry. Until it is, use the
script tag, which works in every framework.
```ts
import { init } from "@scf-analytics/tracker";
const usagemap = init({ site: "YOUR_SITE_KEY" });
usagemap?.track("signup", { plan: "free" }); // optional custom event
```
`init()` returns `undefined` during server-side rendering, and calling it again returns the running instance, so it is
safe in React effects and hot reload.
## Profiles [#profiles]
Each website uses one of two tracker profiles, chosen when you add the website.
| | **standard** (default) | **strict** |
|---|---|---|
| File | `standard.js` | `strict.js` |
| Page path | ✓ | ✓ |
| Referrer host (not the full URL) | ✓ | — |
| Screen size class (S, M, L, XL) | ✓ | — |
| Language (for example `en`) | ✓ | — |
| Wallets Kit detected | ✓ | — |
Use **strict** when you want the smallest possible footprint: it sends the page path and nothing else.
## Content Security Policy [#content-security-policy]
If your site sets a Content Security Policy, allow the tracker host for scripts and both ingest hosts for requests:
```text
script-src https://e1.usagemap.dev;
connect-src https://e1.usagemap.dev https://e2.usagemap.dev;
```
The tracker sends to two independent hosts and switches automatically if one is unreachable.
Serving the tracker or its requests through your own server makes every visit look like it comes from one machine,
and all of them are then counted as *suspect*.
## What happens on each page view [#what-happens-on-each-page-view]
The page loads (or the route changes) and the tracker sees a new path.
It asks UsageMap for a small challenge and solves a light proof of work in the background, which makes fake traffic expensive.
It sends the path only: never the query string, the `#fragment` or the page title.
UsageMap checks the event and counts it as **verified**, **suspect** or **rejected**. You see all three in the dashboard.
Nothing at all is sent, not even the challenge, when the visitor has Global Privacy Control or Do Not Track turned on,
has opted out, or hasn't given consent in consent mode.