hubfly analytics
Web Analytics is coming soon
hubfly analytics sites create and sites enable are refused.hubfly analytics manages Web Analytics: cookieless website analytics billed per event. It adds sites for domains your projects serve on Hubfly space or for websites hosted anywhere, prints the install snippet, reads stats and realtime visitors, exports raw data, reports usage and manages the ingest keys of the server-side events API.
Basics
- A site belongs to a project, which pays for its events: a Cell or Box project for a domain that project serves on Hubfly space, or a standalone Analytics project for a website hosted anywhere.
<site>is a site id, public id (hfa_…), name or domain. You can leave it out when you have exactly one site. When a name matches sites in several projects, add--project <id|name>(or-p).- Dates are
YYYY-MM-DDin the site's time zone. - Commands that print data accept
--json. An ingest key is printed once, when it is created. - Run
hubfly analytics helpfor the full usage text.
terminal
Add A Site
hubfly analytics sites enable --domain <hostname> [--name <name>] [--no-inject] [--project <p>] [--json]
hubfly analytics verify <domain> [--project <p>] [--json]
hubfly analytics sites create <domain> [--name <name>] [--domain <domain>]... [--include-subdomains]
[--timezone <tz>] [--retention <days>] [--project <p>|new] [--region <id|name>]
[--yes] [--json]
hubfly analytics snippet <site> [--project <p>] [--json]| Command | What it does |
|---|---|
sites enable | Tracks a hostname that one of your Cell or Box projects serves on Hubfly space. The CLI finds the project that serves it and turns on script injection, so HubProxy adds the script to its HTML pages with no code change. --no-inject leaves the script to you and prints the snippet. Use --project when several projects serve the hostname. A hostname that already has a site is refused. |
verify | Proves that you own a domain hosted elsewhere. The first run prints a DNS TXT record; add it at your DNS provider and run the command again until it reports verified. A verified example.com also covers its subdomains. It verifies in an existing project, never --project new. |
sites create | Tracks a website hosted anywhere. Each domain must be covered by a verified domain of yours. --domain adds more domains (repeat it or separate them with commas), --include-subdomains counts every subdomain too, --timezone takes a zone such as Europe/Berlin for daily reports, and --retention keeps raw events for 30 to 365 days (30 by default). The name defaults to the first domain. It prints the snippet when it is done. |
snippet | Prints the <script> tag for the <head> of every page and the URL of the server-side events API. For a Hubfly space domain with injection on, it says that Hubfly space adds the script and that you need the tag only for pages served elsewhere. --json prints scriptUrl, snippet, eventsApiUrl and autoInjected. |
sites create puts the site in --project <p> (a Cell, Box or Analytics project). --project new creates a standalone Analytics project named after the site, after you confirm (--yes in scripts), in the region you pass with --region; in a terminal you can pick one of the regions that offer Web Analytics. Without --project, the site goes into your only Analytics project; when you have none or several, a terminal lets you pick one or create a new one, and scripts must pass --project. Raw events kept longer than 30 days add a storage charge.
terminal
Manage Sites
hubfly analytics sites [list] [--project <p>] [--json]
hubfly analytics sites info <site> [--project <p>] [--json]
hubfly analytics sites status <site> [--project <p>] [--json]
hubfly analytics sites pause|resume <site> [--project <p>] [--json]
hubfly analytics sites delete <site> [--yes] [--project <p>]| Command | What it does |
|---|---|
sites, sites list | Your sites in every Cell, Box and Analytics project you can read, with domain, state, source (hubfly for a domain a project serves, external otherwise), last event, project and id. A state ends in (syncing) or (sync error) while a change has not reached the analytics region or HubProxy yet. hubfly analytics list is the same command. |
sites info | Ids, project, state, domains, whether Hubfly space serves the site and injects the script, time zone, raw retention, visitor identity mode, last event, stored size and any sync error. |
sites status | Whether events arrive: the last event, events today and stored size, or a reminder to add the snippet when nothing has arrived yet. It also says when the site's region cannot be reached. |
sites pause, resume | Pausing stops collection until you resume; the site's data is kept. |
sites delete | Deletes the site and all of its data after you confirm (or pass --yes). When the region is still removing the data, the CLI says so; Hubfly space finishes it shortly. |
Stats And Filters
hubfly analytics stats <site> [--period today|7d|30d|month|6mo|12mo | --from <date> --to <date>]
[--by <dimension>] [--limit <n>] [--filter <dim>=<value>]... [--compare]
[--project <p>] [--json]stats prints visitors, visits, pageviews, views per visit, bounce rate and visit duration, then the top 5 pages and sources by visitors. The default range is the last 30 days. --from and --to go together and replace --period.
| Flag | Meaning |
|---|---|
--by <dimension> | One breakdown instead of pages and sources, with up to --limit rows (10 by default, at most 1,000). When more values exist, the CLI says how many. |
--filter | <dimension>=<value> (* matches anything), <dimension>!=<value> or <dimension>~<text> for contains. Repeat it to combine filters; they apply to every number. |
--compare | Adds the change against the previous period of the same length: a percentage, or percentage points for the bounce rate. |
--json | Prints the site id, the totals and each breakdown as returned by the analytics API. |
Dimensions are those of the analytics API: page, entry_page, exit_page, source, referrer, channel, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country, region, city, browser, browser_version, os, os_version, device, language, hostname, event, goal, and prop:<key> for a custom prop. Filtered reports read raw events, which are kept for the site's retention; when the range starts earlier, the CLI notes the date the data starts.
terminal
Realtime
hubfly analytics realtime <site> [--watch] [--project <p>] [--json]Visitors in the last 5 minutes and pageviews in the last 30 minutes, the top pages, sources and countries, and the 10 most recent events with their page, country, device and source. --watch (-w) refreshes every 10 seconds until you press Ctrl+C; it does not combine with --json.
Export
hubfly analytics export <site> --from <date> --to <date> [--kind events|sessions|summaries]
[--format csv|ndjson] [--output <file>|-] [--force] [--project <p>]--kindisevents(raw events, the default),sessions(one row per visit) orsummaries(daily summaries).--formatiscsv(the default) orndjson.- The file is named
<public id>-<kind>-<from>-to-<to>.<format>unless you pass--output(-o);-o -writes to standard output. An existing file is kept unless you pass--force. - One export returns at most 8 MB. When it stops there, the CLI says so on standard error: split the date range to get the rest.
- Raw events and visits go back as far as the site's retention; daily summaries are kept for 2 years.
terminal
Usage
hubfly analytics usage [<project>] [--json]A project's events this month: billable, filtered and not collected, the last 24 hours and the projection to month end, how much of the free allowance is left (it is shared by every project of your account or organization), the monthly event cap, and the billable events of each site. Members who can view billing also see the cost so far and the projected cost. When collection is limited, it says why: paid events paused by the spend cap or a low balance, or every event stopped by the monthly event cap. Without a project, it uses the project of your sites when they are all in one.
Ingest Keys
hubfly analytics keys [list] <site> [--project <p>] [--json]
hubfly analytics keys create <site> <name> [--project <p>] [--json]
hubfly analytics keys revoke <site> <keyId> [--yes] [--project <p>]| Command | What it does |
|---|---|
keys, keys list | The site's ingest keys with name, prefix, status (active or revoked), last use, creation date and id. |
keys create | Creates an hfak_… key and prints it once, with the events API URL to send to (in "key" with --json). The key works once it reaches the site's region, usually within a few minutes. A site can have up to 20 active keys. |
keys revoke | Revokes a key, named by its id, name or prefix, after you confirm. Servers that use it can no longer send events. |
terminal
Scripting And Errors
- JSON output. With
--json, standard output carries only JSON, and commands never stop to ask you to pick a project or region. - Confirmations.
sites delete,keys revokeandsites create --project newask first. Without a terminal they stop withconfirmation required; re-run with --yes. - Hints. Errors you can act on come with the next step: verify the domain first, a region that does not take new sites yet (existing sites keep collecting), a region that cannot be reached, a query that timed out (narrow the dates or filters), or a role that does not allow the action. Managing sites and ingest keys needs edit access to the project;
sites enablealso needs network access. - Not in the CLI. Goals, funnels, segments, shared dashboards and the monthly event cap are managed in Dashboard or with the SDK (
hubfly.analyticsin TypeScript,client.Analyticsin Go); see the analytics API reference. - Exit codes. Non-zero on failure, with distinct codes for usage errors, authentication, conflicts and timeouts. See exit codes.
Keep ingest keys on your servers
HUBFLY_ANALYTICS_INGEST_KEY and never ship it to browsers; the script needs no key.