From first install to repeat use.
Track installations, removal reports, active use, and collected emails. Keep SDK telemetry separate from confirmed Stripe payments.
Works with your own code. Templates are optional.#
Every product needs integration code in its actual source. Creating a TopPay app or connecting Stripe cannot observe installs or feature use by itself. Start at My apps → your app → Setup → Connect usage tracking for configured snippets, a template-free extension kit, and received-event checks.
| Data | How TopPay receives it | Works without templates? |
|---|---|---|
| Payments and checkout email | TopPay checkout + signed Stripe events | Yes: SDK or server API |
| Extension installs, removals, and active use | Local SDK worker + event calls in your actual features | Yes: merge the integration kit or snippets |
| Email before checkout | A voluntary extension form, or authenticated backend registration | Yes: identifyEmail / server customers endpoint |
| Web app usage counts | Public tracking snippet in your frontend | Yes: copy the configured code |
New starter downloads include example tracking calls. Existing or custom code must integrate the SDK/snippet and ship an update. Do not add duplicate handlers when your product already includes them.
Add advanced extension analytics#
Open your extension’s Setup → Connect usage tracking (also available under Usage & traffic → Add analytics). Download the integration kit or use the complete manual snippets; your app ID and public key are already included. Newly downloaded extension templates and ready-to-test extensions include the analytics worker automatically.
- 1
Merge the background worker
Add the local SDK/config files and merge the manifest fragment. Preserve your existing worker and permissions. Call
toppay.startAnalytics()synchronously at worker top level. The SDK needs storage, alarms, and TopPay host access; it does not request management or identity permissions. - 2
Record real use
Call
void toppay.track('app_open')when your popup or app opens. Callvoid toppay.track('feature_export')when that feature actually runs. Custom action names begin withfeature_. Background retry alarms do not count as activity. - 3
Publish an update
Existing installations begin reporting when they run your updated code. Their original installation date is unknown. A newly observed existing installation is not counted as a new install. Data from earlier versions cannot be reconstructed.
The SDK keeps up to 100 pending events for retries. Event times reflect server receipt, including delayed retries. Describe installation IDs, usage events, and optional email collection in your extension’s privacy notice.
Understand installs and uninstall reports#
| Metric | What it means |
|---|---|
| Recorded installs | Distinct installations where Chrome reported an install event after analytics was added. |
| Observed installations | All installations that have sent telemetry, including existing users receiving an update. |
| Developer mode | Unpacked installations are labeled separately; a reload reports an update, not a new install. |
| Uninstall reports | A removal callback reached TopPay. Duplicate callbacks count once. |
| Active installations | Distinct installations that opened the app or used a feature today, in 7 days, or in 30 days. |
| Day 1 / Day 7 retention | New installations with recorded activity exactly 1 or 7 UTC calendar days later; only completed return days qualify. |
Installations are browser profiles, not unique people or official Chrome Web Store totals. Reinstalling can create another installation. Standard install type does not prove the extension came from the Web Store.
See emails without reading Chrome account details#
The installation directory joins checkout emails to the same SDK customer identity. The customer enters email on Stripe’s checkout form before paying or confirming a trial. TopPay saves that email from a signed, mapped completed-checkout event; this is not a live feed of typing in an abandoned Stripe form. An unpaid customer can share an address earlier through your own optional form. Completing a trial signup does not require a successful charge to associate its email. TopPay does not read their Google or Chrome account email.
await toppay.identifyEmail(emailFromYourForm, { consent: true });Self-reported addresses are labeled unverified. An email does not authenticate a customer or grant paid access. Search collected emails, inspect first/last seen and removal reports, and export the current page as CSV. Checkout customers who have not installed the updated SDK remain visible in Customers.
Pick an action worth measuring#
- 1
Open tracking setup
In the dashboard, choose Usage & traffic, select your app, and open Set up tracking.
- 2
Choose an event and source
Use a label such as
app_openorexport_complete. Source tells you where the event originated, such asextension_popuporwebsite. - 3
Install the generated code
Use JavaScript for repeated app actions. Use an image pixel for a page load. Call the event once when the action happens, not on every component render.
- 4
Confirm both sides
Send test event confirms that the tracking service records an event. Then trigger the real action inside your product and refresh the report to verify your installation.
Keep events consistent#
| Event | When to send it |
|---|---|
view | A page is viewed. |
app_open | The app or popup opens. |
feature_used | A chosen feature runs successfully. |
export_complete | Example of your own custom action. |
tracking_test | Reserved for diagnostics. Excluded from usage totals. |
JavaScript tracking example#
Copy your real public tracking key from the dashboard. Events and sources accept 1–40 letters, numbers, underscores, or hyphens and are normalized to lowercase. Keep the code local in Chrome and add the API origin to host permissions.
// Use your public tracking key, never a server API key.
function trackUsage(event) {
if (!/^[a-z0-9_-]{1,40}$/i.test(event)) return;
const url = new URL("https://toppayext.com/api/v1/pixel.gif");
url.search = new URLSearchParams({
key: "YOUR_PUBLIC_TRACKING_KEY",
event: event.toLowerCase(),
source: "extension_popup",
t: String(Date.now())
});
return fetch(url, {
mode: "no-cors", credentials: "omit", cache: "no-store",
referrerPolicy: "no-referrer", keepalive: true
}).catch(() => {});
}
trackUsage("app_open"); // Once when the app opens.
// After a feature succeeds: trackUsage("feature_used");For a plain webpage, the image-pixel option records a load. Prefer JavaScript for repeat actions and cache-busting. Your website’s content policy may also need to permit the TopPay origin.
Read the report accurately#
Use the 7-, 30-, or 90-day window, event filters, daily table, source breakdowns, and CSV export. Counts are grouped by UTC day. The aggregate pixel section shows event counts. Installation counts and retention appear separately in Advanced analytics when the extension SDK is installed. Neither section records browsing sessions.
Know what to test and what success looks like before launch.
