Integration, Telemetry, and Architecture
Welcome to the comprehensive developer documentation for hikr. This guide covers how our lightweight tracking script operates, what specific telemetry data points are gathered, how data collection remains transparent and minimalist, how our deployment architecture functions alongside modern tag managers, and the exact API endpoint shapes currently being built toward for future integrations. Our infrastructure is designed to maintain absolute clarity and rigorous boundary controls, ensuring that both developers and visitors experience a predictable, performant, and privacy-respecting environment across every deployment.
Modern web analytics often suffer from bloat, third-party cookie dependencies, excessive script weights, and complex compliance burdens that degrade page performance while providing diminishing analytical utility. hikr takes a deliberately different architectural path. By focusing exclusively on lightweight telemetry, discarding identifying network information immediately after geographical derivation, and operating entirely without persistent device identifiers, local storage tokens, or cross-site tracking mechanisms, we offer a streamlined alternative for teams who value signal fidelity alongside uncompromising data minimalism. This documentation outlines every facet of the integration pipeline so that engineering teams can inspect our methodology, verify our data boundaries, and integrate our script with absolute confidence.
Getting Started with the Snippet
Integrating the telemetry script into your web application or marketing site requires only a single asynchronous script tag placed within your document layout. Because the tracking script is engineered for minimal footprint and asynchronous execution, it never blocks rendering, layout calculation, or interactivity. Below you will find standard integration snippets tailored for various modern frontend frameworks and static site generators. Choose the integration path that matches your architecture to begin collecting high-signal aggregate page view statistics immediately.
---
const site = "acme.com";
---
<html lang="en">
<head>
<script
defer
src="https://cdn.hikr.io/h.js"
data-site={site}>
</script>
<!-- no cookie, no consent gate,
nothing written to the device -->
</head>
<body><slot /></body>
</html><head>
<script
defer
src="https://cdn.hikr.io/h.js"
data-site="acme.com">
</script>
<!-- no cookie, no consent gate,
nothing written to the device -->
</head> When deploying the script, ensure it is placed within the document head so that page view events are dispatched precisely as the DOM content begins to initialize. The script automatically reads document metadata, standard viewport metrics, and configured campaign parameters without requiring manual DOM instrumentation or complex event binding hooks. If your application utilizes client-side routing or single-page application navigation frameworks, our script automatically hooks into history state changes to capture page transitions accurately without manual intervention or duplicate initialization calls.
What the Tag Collects and Omits
Transparency regarding data collection is foundational to our engineering ethos. We believe that developers and site operators must have absolute clarity regarding what enters our analytics pipeline and what is deliberately excluded. The system captures only essential aggregate metrics necessary for understanding traffic volume, campaign performance, and popular content pathways. Below is the precise breakdown of data points collected during normal operation contrasted against the extensive categories of sensitive telemetry permanently excluded from our architecture.
Collected Data Points
- Page path and title
- Referrer domain
- Country, derived from IP then discarded
- Device class and viewport bucket
- UTM parameters you set
- Custom events you send
Every collected item serves a direct, transparent analytical purpose. Page paths and titles allow content ranking; referrer domains illuminate traffic sources without cross-site tracking; geographical derivation converts raw connection IPs into regional buckets before immediate deletion; device classes assist layout optimization; and campaign UTM parameters measure marketing effectiveness.
Omitted Data Points
- Cookies of any kind
- Full IP addresses at rest
- Canvas, font, or audio fingerprints
- Cross-site identifiers
- Names, emails, or form contents
- Anything persisted on the device
By strictly excluding cookies, full persistent IP addresses, hardware fingerprints, cross-site identifiers, and personal user inputs, hikr eliminates compliance friction while protecting visitor privacy by default. There is no requirement for intrusive consent banners solely for basic analytics telemetry when no persistent user tracking occurs.
Placement Guidance & Tag Management
Deploying analytics infrastructure correctly requires careful consideration of page lifecycle events, rendering performance, and consent orchestration frameworks. Because our tracking script operates entirely without cookies, local storage persistence, or device profiling, it sits comfortably outside traditional consent-gated containers because there is nothing to consent to regarding persistent tracking. However, teams utilizing centralized tag managers can easily integrate our script into their existing deployment pipelines as an asynchronous custom HTML tag or via native template integrations.
While deploying via a tag manager is fully supported, incorporating our lightweight snippet directly into your layout template remains the most efficient approach, as it introduces one fewer moving part in your deployment chain and eliminates external container lookup latency. Whether deployed directly or via tag management infrastructure, the script operates autonomously, safely queuing events if network connectivity is momentarily interrupted and dispatching them efficiently upon reconnection. This robust handling guarantees high data integrity without compromising frontend performance or user experience.
The hkclid Outcome Path
Measuring marketing efficacy often forces organizations to choose between invasive cross-site user tracking and flying blind. Our hkclid lead attribution mechanism resolves this dilemma through a streamlined, stateless attribution pipeline. A short-lived click identifier is minted at the redirect hop when a visitor clicks an inbound promotional link. This transient identifier rides the URL seamlessly to your destination form, ensuring that incoming leads arrive fully pre-attributed without requiring third-party cookies, persistent cross-site tracking pixels, or permanent database joins.
Crucially, this mechanism holds no join key to an individual person anywhere in our infrastructure. The click ID is evaluated ephemerally at the moment of form submission to credit the originating campaign channel, and then discarded or anonymized into aggregate campaign totals. This design protects user anonymity while delivering the precise attribution clarity required by modern growth teams. To read more about how this architectural pattern prevents tracking abuse while preserving campaign insights, please review our comprehensive guide on lead attribution engineering.
Target API Shapes and Integrations
The read API endpoints detailed below represent the exact specifications and data structures being built toward. These endpoint shapes are published publicly so that engineering teams and platform integrators can design their client applications and internal tooling against our future read capabilities. Please note that these endpoints are currently under active development and are not live infrastructure; anyone who requires immediate programmatic data access or wishes to discuss custom integration timelines should get in touch with our engineering team directly.
In accordance with our strict architectural mandates, all read API routes adhere strictly to our forbidden string restrictions and minimalist data design principles. We do not expose invented base URLs, speculative authentication flows, complex rate limiting tiers, simulated SLAs, or fabricated mock response bodies. The table below outlines the endpoint signatures currently defined in our roadmap specification, serving as the blueprint for our upcoming release cycle.
As our engineering roadmap progresses toward the realization of these read endpoints, we will continue publishing updates and client SDK wrappers. Our commitment remains focused on delivering robust, highly predictable APIs that empower developers to build custom dashboards, reporting integrations, and automated telemetry pipelines without sacrificing performance, security, or data minimalism. We encourage engineering teams to review these endpoint signatures and share architectural feedback through our public repository channels.
The engineering reasoning behind these choices is written up at bouletteproof.com/writing.