Product adoption and usage

GainTrace turns raw product events into adoption facts: which Companies use which features, how heavily, and where activation stalls. This article covers how usage data gets in, how to define the features you track, how to read the adoption views, and how usage feeds health scores and signals.

​

How usage data reaches GainTrace

Everything on the adoption surfaces is computed from product events: one row per action a user took in your product, such as report_export or Report Exported. GainTrace resolves each event to a person and rolls it up to their Company, so adoption is always read per customer, not per anonymous user. You can send events through any of these paths. They all land in the same event stream, so you can mix them. Analytics connectors are read-only: GainTrace reads your data and changes nothing on the other side.

​

How events attach to People and Companies

• An event’s user identifier is matched against your People by email or external ID. The match is exact (case-insensitive); there is no fuzzy matching.
• Events sent through the API can also carry a Company ID directly, which skips person matching.
• Attribution happens once, when the event is stored. An event whose identifier matches no Person, or whose Person has no Company link yet, stays unattributed - it is not re-linked later. Sync your People and their Company links before sending usage events.

​

Send events with the snippet or API

Use this path if you do not run a product analytics tool, or you want events in GainTrace without another vendor in between. API facts worth knowing:

• One request can carry up to 1,000 events.
• Events from the snippet and SDK must include a stable event ID, which GainTrace uses to deduplicate retries. A resent event is never counted twice.
• Events sent through the API update adoption and health shortly after they arrive, without waiting for a sync cycle.

​

Define the features you track

Adoption is computed against feature definitions you create. A feature is a name plus one or more event patterns; any event matching a pattern counts as a use of that feature. A pattern matches an event whose name equals it exactly, or starts with it followed by a dot, so reports matches both reports and reports.export. Matching is case-insensitive. Each feature row on the page has a menu to View reality, Edit definition, Recompute adoption, Deprecate, or Delete it. Renaming a feature or changing its patterns recomputes its adoption right away, and rename keeps the feature’s usage history.

​

Read the adoption matrix

The matrix on Data > Feature adoption shows one row per Company and one column per feature. Each cell is a status dot; hover it for the exact use count. The stat strip above summarizes features, Companies with usage, and average adoption, where a Company counts as adopted for a feature at Adopted or Power. The threshold is per feature: the Adoption threshold (min uses) you set on its definition.

​

Track activation

The Activation section on the same page shows a funnel of milestones: how many Companies reached each step and where they drop off. You do not build the funnel by hand. The first time you open the Activation section with key features marked, the default funnel builds itself: one milestone per key feature, in the order you created them, using each feature’s first event pattern. The funnel is seeded once - marking or unmarking key features afterward does not change the existing funnel. Completion fills in as new Companies hit each milestone, and the summary line names the biggest drop-off step.

​

See usage on a Company record

Open any Company and stay on its overview. Once a usage source has synced events for it, the record shows an active-users chart, a Main features table with per-feature adoption, use counts, unique users, and top user, and a per-person activity grid. Until then, the record shows a No product usage yet empty state with a link to connect a source. GainTrace never fills these sections with sample data.

​

How usage feeds health and signals

Product usage drives two of the six health dimensions:

• Usage (25% default weight) measures how actively the Company uses the product: utilization of committed seats or quota where available, otherwise how consistently its users are active.
• Adoption (20% default weight) is the share of your active feature definitions the Company has at Adopted or Power.

A dimension with no data is skipped and the remaining weights renormalize, so connecting a usage source deepens the score rather than unlocking it. See Health scores for the full model. Usage also powers signals:

• Usage drop fires when a Company’s activity in the trailing 14 days falls at least 50% below the prior 14 days (critical at 80%), with a floor of 5 baseline events so quiet Companies do not produce noise. Activity here is the Company’s combined stream - product events plus CRM and email activity - and the 50%/80%/5-event numbers are defaults you can tune under Setup > Signals.
• First value fires when a brand-new Company (up to 14 days old) records its first activity - its first product event or CRM activity.
• Feature adoption fires on adoption moments, and its per-feature rules can trigger on first use, on crossing an adoption threshold, or when a tagged champion adopts a feature.

​

What stays empty without a usage source

GainTrace shows honest empty states instead of estimates. With no product events in the workspace:

• Feature adoption shows “No adoption data yet”, and the Define Feature dialog has no observed events to pick from.
• Company records show the No product usage yet state in place of usage charts and the features table.
• The Usage and Adoption health dimensions are skipped; health can still compute from other dimensions such as engagement, sentiment, and revenue.
• Usage-based signals such as Usage drop are shown as unavailable until an activity source is connected, so they never fire on guesses.
• The live event inspector is empty.

​

Limits and timing

Each plan includes a monthly event allowance and a connector sync frequency: When the allowance is used up, the events API rejects new events until the month resets, you upgrade, or you enable overage billing. Overage billing requires a paid plan, so on Free the cap is hard until the month resets or you upgrade. Events arriving through connectors follow the sync schedule above; events sent through the API are processed as they arrive. Adoption rollups also refresh on a periodic cycle, so rolling 7-day and 30-day counts stay current even for quiet Companies.

​

FAQ

Do I need PostHog or Mixpanel to use adoption? No. Any path works: an analytics connector, Segment, a warehouse sync, or sending events directly to the events API. The adoption views read the same event stream regardless of source. Why is an event not attributed to a Company? Its user identifier did not exactly match any Person’s email or external ID, or the matched Person is not linked to a Company yet. Send the same identifier your CRM or analytics source uses, or pass the Company ID directly on API events. Attribution is set when the event arrives and is not revisited, so fix the identifier or Company link before sending more events. Can I rename a feature without losing its history? Yes. Renaming keeps the feature’s adoption history and recomputes adoption under the new name right away. Why does a feature show no adoption right after I create it? The rollup runs immediately after create but can take a moment; the row shows “Computing adoption…” until it lands. If it still looks wrong later, use Recompute adoption in the feature’s menu. Does defining a feature backfill history? Yes. Adoption is computed from all matching events already in GainTrace, not only events that arrive after you define the feature.

​

Good to know

• Event-name matching is case-insensitive, and a pattern also matches names prefixed with it plus a dot (reports matches reports.export).
• The adoption threshold is per feature, and threshold edits recompute adoption right away.
• The event picker in the Define Feature dialog lists the most frequent event names observed in your workspace, up to 200.
• The adoption surfaces render only what product events recorded. If a number looks low, check that your sources are syncing and your identifiers match, not the math.

​

Related articles