Skip to guide
Docs
DOCUMENTATION/USAGE & TRAFFIC
BUILD / USAGE & TRAFFIC

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.

DataHow TopPay receives itWorks without templates?
Payments and checkout emailTopPay checkout + signed Stripe eventsYes: SDK or server API
Extension installs, removals, and active useLocal SDK worker + event calls in your actual featuresYes: merge the integration kit or snippets
Email before checkoutA voluntary extension form, or authenticated backend registrationYes: identifyEmail / server customers endpoint
Web app usage countsPublic tracking snippet in your frontendYes: 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. 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. 2

    Record real use

    Call void toppay.track('app_open') when your popup or app opens. Call void toppay.track('feature_export') when that feature actually runs. Custom action names begin with feature_. Background retry alarms do not count as activity.

  3. 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#

MetricWhat it means
Recorded installsDistinct installations where Chrome reported an install event after analytics was added.
Observed installationsAll installations that have sent telemetry, including existing users receiving an update.
Developer modeUnpacked installations are labeled separately; a reload reports an update, not a new install.
Uninstall reportsA removal callback reached TopPay. Duplicate callbacks count once.
Active installationsDistinct installations that opened the app or used a feature today, in 7 days, or in 30 days.
Day 1 / Day 7 retentionNew 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.

Optional: after a user submits your email form
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. 1

    Open tracking setup

    In the dashboard, choose Usage & traffic, select your app, and open Set up tracking.

  2. 2

    Choose an event and source

    Use a label such as app_open or export_complete. Source tells you where the event originated, such as extension_popup or website.

  3. 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. 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#

EventWhen to send it
viewA page is viewed.
app_openThe app or popup opens.
feature_usedA chosen feature runs successfully.
export_completeExample of your own custom action.
tracking_testReserved 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.

tracking.js
// 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.

CONTINUE BUILDINGTest your integration

Know what to test and what success looks like before launch.