Honch SDKs

Honch is product analytics for connected hardware. Its SDKs run inside your firmware or app, capture events with typed properties, queue them locally, and upload them to Honch over HTTPS when the device is connected. One small C core defines the behavior; each platform port adapts storage, transport, timing, and packaging around it.

Every SDK reports the same SDK version on the wire — 0.3.0 — because the four device ports share a single source of truth in the core. Maturity differs by platform, which is what the status column below reflects.

Start Here

If this is your first integration, read in this order:

1. Quickstart — pick an SDK, send one event, and confirm it reaches Honch.
2. Your SDK guide — install, configure, track, and verify on your target.
3. Shared Concepts — identity, queueing, retries, lifecycle events, and the upload contract.
4. Troubleshooting and the FAQ — when something does not behave as expected.

Resist adding every product event on day one. First prove that a single event queues and either uploads or stays pending for a reason you understand.

Choose Your SDK

No SDK for your platform? Send events straight to the HTTP API — see Build Your Own Integration.

What Every SDK Does

Each event carries an event name, an on-device timestamp, a distinct_id, and typed properties. The SDK attaches its own context properties to every event automatically:

• $device_id, $device_model, $firmware_version
• $sdk_platform, $sdk_version, $environment
• $session_id while a session is active; $battery_level and $wifi_rssi when your integration supplies them

These keys are reserved. If you pass a property that reuses a reserved key, the call is rejected with an invalid-argument error — reserved keys are never silently overwritten.

The SDK is not silent on the wire. Initializing it queues a $device_boot event on its own, and these lifecycle events are emitted automatically as the relevant calls happen:

• $device_boot — at init
• $device_shutdown — at shutdown
• $firmware_update — when the stored firmware version changes
• $battery_low — when battery crosses your low threshold (edge-triggered)
• $session_start / $session_end — around sessions
• $identify — when you set a distinct_id

The Upload Contract

Device SDKs upload the compact binary chunk format:

POST /capture
Content-Type: application/vnd.honch.chunk
X-Honch-Project-Key: <project_api_key>
X-Honch-Stream-Id: <stream_id>

Uploads are cooperative: nothing happens on a background thread. Your code pumps delivery by calling tick() periodically (and flush() when you want to force a send). Initialization does its work synchronously and performs no network I/O. The default endpoint is https://i.honch.io; use HTTPS in production and reserve plain HTTP for intentional local testing.

If you are integrating without an SDK, send JSON to the same endpoint instead — the HTTP JSON API is the simplest path.

Where To Go Next