Docs Reference

Tracking events

Use events to describe actions that matter to your application: a page view, a signup, a purchase, or a completed job.

The .NET examples on this page use an existing analytics engine. Keep that engine open while your application runs.

Record visits and business actions

var pageView = AnalyticsEvent.PageView(
    "https://example.com/pricing?utm_source=newsletter",
    "https://www.google.com/",
    "203.0.113.7",
    "Mozilla/5.0");
pageView.VisitorId = "customer-42";
analytics.Track(pageView);

bool accepted = await analytics.TrackAsync(
    new AnalyticsEvent("purchase") { VisitorId = "customer-42" }
        .WithDimension("plan", "pro")
        .WithValue("revenue", 49.0),
    cancellationToken);

Page views provide website context. Named custom events describe product activity, and numeric values provide measurements such as revenue or duration.

The example uses the same customer ID for both actions. In an application, pass the trusted identity associated with the activity. Without that consistency, the purchase may belong to a different visitor from the page view.

Use stable event names across your application so reports remain comparable over time.

Choose fields for useful reports

Question Event data
Which plan is purchased? A plan dimension on purchase events
How much revenue is generated? A numeric revenue value
Which route attracts traffic? A normalized page URL
How long does a job take? A duration value on completed-job events
Which visitors convert? Consistent visitor identity across relevant actions

Dimensions group and filter events; values are measured and aggregated. Prefer categories such as plan or region to high-cardinality identifiers that do not help the report.

Use an explicit timestamp when importing historical events. Retention determines which tiers can retain that history.

Collect browser events

Map the tracker endpoints in your ASP.NET Core host, then add the script and record a custom action:

<script defer src="/_analytics/script.js"></script>
<script>
  window.zta = window.zta || function () {
    (window.zta.q = window.zta.q || []).push(arguments);
  };
  zta('signup', { plan: 'pro' });
</script>

The browser tracker records page views automatically. Use one collection method for each visit: server middleware or automatic browser page views. See ASP.NET Core integration for the choice.

Client-event rules and tracker attributes are documented in the HTTP reference.

Identify visitors deliberately

Supply VisitorId when your application has a trusted user identity. Without it, the engine uses the configured anonymous identity policy.

Daily anonymous rotation is appropriate for website traffic; explicit or persistent identity is needed for cross-day behavior. Read privacy and identity before choosing.

Keep automated traffic separate

Bots are excluded by default. Enable BotTraffic.TrackSeparately to report automated hits alongside human traffic:

options.Web.Bots = BotTraffic.TrackSeparately;

var summary = (await analytics.Web.GetSummaryAsync(request)).Summary;   // BotHits next to PageViews
var pages   = await analytics.Web.GetPagesAsync(request);     // PageStats.BotHits per page
var bots    = await analytics.Web.GetBotsAsync(request);      // name, category, hits and share

// Which pages do AI crawlers read?
var ai = await analytics.QueryAsync(new AnalyticsQuery
{
    Event = StandardEvents.Bot,
    GroupBy = { StandardDimensions.Page },
    Filters = { Filter.Equal(StandardDimensions.BotCategory, BotCategories.AI) },
    Metrics = { Metric.Events },
});

Bot hits do not count as human visitors, sessions, or conversions. Browser tracking sees only automated clients that execute the script; server tracking can observe clients requesting HTML.

Understand submission and reporting

Track returns whether the event was accepted. TrackAsync waits asynchronously for queue space. The engine reference describes their queue behavior and outcomes.

Normal reports update automatically while collection continues. Close the engine cleanly at application shutdown to save remaining work. Use statistics to investigate rejected, dropped, or failed processing rather than adding a flush to every report request.