Analytics

Good decisions start with knowing exactly what each number means. This page defines SparkleTree’s metrics first, then tours the dashboards, then covers how to read them without fooling yourself.

Metric definitions

These definitions apply everywhere in the product.

• Impressions — the raw delivery count: one per ad load. If a visitor reloads the page five times, that’s five impressions. Reload inflation is real, and it’s the industry-standard way to count. A screen that switches to another campaign or variant without reloading counts one impression for each variant it shows.
• Reach — distinct sessions that saw the campaign. A session is per-tab and cleared when the tab closes. Reach answers “how many separate visits saw this?”
• CTR (raw) — clicks divided by impressions. Inherits impression inflation: heavy reloading pushes raw CTR down without anything changing for real visitors.
• CTR (sessions) — of sessions reached, how many clicked. Because both sides count sessions, reloads can’t inflate or deflate it. This is the number to trust when comparing creatives.
• Conversion rate — conversions divided by clicks.
• Engagement rate — clicks, product views, and add-to-carts, divided by impressions.

Dwell time and QR taps are engagement telemetry. They show up in engagement views but are excluded from CTR math — a long look or a scan is not a click.

The dashboards

Analytics

Dashboard → Analytics is the main view. It shows one time window at a time: the last 24 hours, the last 7 days (the default), the last 30 days, or a custom range. The bar at the top gives Impressions, Sessions (the Reach figure: distinct sessions that saw a campaign), Conversions and Revenue for that window, and Meta reach when Meta Ads are included. Below it, a chart shows Impressions and Clicks over the window, followed by the breakdown panels and a day-by-hour heatmap, which always covers the last 7 days. The export menu downloads the figures as CSV.

Meta Ads in the totals

If you run campaigns on Meta through SparkleTree (see Automatic ad management), their figures count in the Analytics totals, under the creative that ran them:

• Every figure belongs to a creative and a channel. A creative is a campaign variant (a squid when it shows a custom design). The channels are Signage, Web, Brand pages, Socials and QR scans. Meta Ads is a platform under Socials; other social platforms will be listed there as they are added.
• By creative lists each creative with its Impressions, Clicks and Conversions per channel. A Meta ad counts for the variant SparkleTree created it for, including when someone copies that ad in Ads Manager.
• Socials, not linked to a creative. Meta delivery of an ad whose variant was deleted is shown on its own row. It is never shared out across creatives. Ads made by hand in Ads Manager, which SparkleTree did not create, are not counted in Analytics at all. The same applies to SparkleTree events that did not record which creative was shown (“Web, not linked to a creative” and so on).
• Every figure says where it came from. Socials figures are Reported by Meta; the other channels are Measured by SparkleTree. Hover a figure, or open its details, to see the source.
• Impressions, Clicks and Conversions in the headline are SparkleTree plus Meta Ads. Meta Clicks are all clicks Meta reports. Meta Conversions are purchases, add-to-carts, leads, registrations and subscriptions, and each conversion is counted once even when Meta reports it under several names.
• Rates are per channel. Click-through (Clicks / Impressions) and conversion rate (Conversions / Clicks) are worked out for each channel. Where an all-channels rate is shown, it sits next to the per-channel rates, because a few Meta clicks on many Meta impressions and a busy web embed are different things.
• Reach is never added up. Sessions is SparkleTree’s own figure. Meta reach is a separate figure that SparkleTree asks Meta for, for the whole window, so a person Meta reached on several days counts once. It is shown on the Socials row only, and only when Meta returned it. There is no reach per creative.
• Spend is shown in your Meta ad account’s currency (for example SEK), on the Verified revenue card, in the CSV and for agents. Spend in two currencies is listed per currency and never added together; ROAS and CPA are then left out.
• Hourly views leave Meta out. Meta reports by day, so the 24-hour window and the day-by-hour heatmap show SparkleTree only and say “Meta reports daily and is not included in hourly views.”
• Some filters leave Meta out. Filtering by product, surface, zone, event type or segment shows SparkleTree only, and the page says why. Filtering by campaign keeps Meta in.
• Engagement rate and the session-based rates (such as CTR (sessions)) use SparkleTree data only.

The CSV export has a By channel section and a By creative section with the same rows, including the rows not linked to a creative. The phone app shows the same headline numbers.

Agents get the same view from query_analytics with the creatives section: creatives.channels (the channels, with Socials platforms, sources and per-channel rates) and creatives.creatives (the creatives and the rows not linked to a creative). The REST endpoint /api/analytics/metrics/v2 returns it with includeCreatives=true. The older summary.totals.channels and summary.meta fields (which include Meta reach) are still returned.

Where visitors came from, including AI assistants

The Acquisition panel groups visits to your brand page and campaign pages by source: ChatGPT, Perplexity, Claude, Gemini, Copilot and other AI assistants first, then email, paid, search, social, direct and other. A visit counts toward an AI assistant when the assistant sent the visitor (its link carried a recognisable referrer or a utm_source such as chatgpt.com). The source sticks for the visitor’s whole session, so someone who arrives from ChatGPT on your brand page and then opens a campaign page is still counted as ChatGPT on that page. Embedded campaigns on other sites are not classified this way, because the embedding site is what the browser reports as the referrer.

Site activity

The Site activity panel shows what people do on your own sites: a custom brand page, a site built with the SparkleTree SDK, and pages where a campaign is embedded. Each kind of event is one row (for example “Directions” or “Search”), with its count, the sessions it came from and the site it happened on. Pick a property under Break down to see the event’s values, for example which search terms people used. A search that reports a number of results also shows how many searches found nothing.

Views by page lists your brand page’s pages by path, with views and sessions. Brand page views are recorded for you; you add nothing to the page.

Everything else on the panel comes from your site, so the site has to send it:

• Impressions and clicks on campaign creative are recorded for you by the embed script and by the SDK’s components.

• Your own buttons, links and searches appear once the site sends them with the SDK’s track. On a custom brand page, load /api/embed/v1/sdk/core.js and call SparkleTree.track; on your own site, use track from @sparkletree/core. Send a tap on a link or button as "click" and anything else (a search, a filter) as "custom". Put the event’s name in context.kind and its details as other context keys:

  SparkleTree.track(
    { apiBase: location.origin, organizationId: "<your organization id>", campaignId: "<a campaign id>" },
    "custom",
    { context: { kind: "search", q: "tacos", results: 4, path: location.pathname } },
  );

  track needs the id of one of your campaigns. Keys outside context are not stored. Property names start with a letter and use letters, digits and _. Values are text, numbers, true or false, or lists of those. Taps sent as "click" are counted as site clicks, separate from campaign clicks, and are not part of a campaign’s click-through rate. Never send personal data such as names, emails or phone numbers.

• The session, device, country and site are added by SparkleTree. The site is the page’s own address, or your registered site when there is only one.

If you ask an agent to build a page or a site, ask it to record the actions you care about. The brand page instructions agents read (query_brand action=get_page) and the SparkleTree plugin skills tell it how.

Agents read the same figures with query_analytics (action snapshot, section siteActivity): each kind of event with its key, count, sessions, site and properties, brand page views by page, and views by traffic source. To see one property’s values, they add siteActivityBreakdown with the kind’s key and the property, for example { kind: "sdk:custom:search", property: "q" } for the search terms. So an agent that added track to a site can check that the events arrive, and include them in a report. The figures are whole UTC days over the dates asked for, up to a year back. Site activity is not split by campaign, product, surface or event type, so with those filters the section says it is not available.

Agent visibility

The Agent visibility panel shows which AI crawlers and agents read your machine-readable surfaces: llms.txt, the agent card, /ask, the markdown and JSON-LD versions of your pages, the API catalog, skills, OAuth metadata, robots.txt and the sitemap. Counts are per bot family (OpenAI, Anthropic, Perplexity and so on), split by purpose (training, search index, or a user’s live fetch), with unidentified clients listed last.

Two caveats are printed on the panel and worth repeating here. The counts are origin fetches: your pages are cached at the edge, and a fetch answered from the cache is not seen, so hot pages are undercounted. And the counts are as claimed: a crawler identifies itself with its User-Agent string, which anyone can imitate, so treat the numbers as a strong signal rather than an audit.

CVG

Dashboard → CVG shows variant performance and winner detection — this is where Adaptive selection shows its work. SparkleTree learns which variant performs and shows winners more often; the CVG dashboard lets you see which variant is winning, by how much, and on what evidence, so the system’s choices are never a black box.

Live

Dashboard → Live is the real-time activity feed: deliveries, clicks, and conversions as they happen. Useful in the first hours after a launch or a screen deployment, when you want confirmation that traffic is flowing.

Reports

Dashboard → Reports is for exports — take the data out when you need it in a deck or a spreadsheet.

How to read the numbers honestly

Compare variants on CTR (sessions), not raw CTR. Two variants can serve on pages with very different reload behavior — a kiosk that refreshes on a timer versus a product page people visit once. Raw CTR punishes the kiosk unfairly. CTR (sessions) asks the same question of both: of the visits that saw it, how many acted?

Give new variants time. A variant with 40 impressions and one click is not a 2.5% performer; it’s a coin that’s been flipped a few times. Adaptive CVG keeps exploring precisely because early numbers are noisy. Resist retiring a variant in its first days unless the gap is dramatic and sustained. See Tips and tricks for more on when to trust Adaptive CVG.

Expect Impressions and Reach to diverge. A high Impressions-to-Reach ratio isn’t a problem to fix — it usually just means surfaces that reload, like screens. It’s a reason to prefer session-based rates when you evaluate creative.

Treat engagement telemetry as color, not verdict. Dwell time and QR taps tell you people lingered or bridged to their phone. That’s valuable context, but it doesn’t move CTR, and it shouldn’t override click and conversion evidence when you decide what to keep.

Follow the funnel before judging a step. A low conversion rate with a healthy CTR points at what happens after the click, not at the creative. The funnel tab shows where sessions drop off; fix the step that’s actually leaking.

For what the variants themselves can do, see Capabilities and use cases.