Send product events

Product events are who your users are and what they do in your app. They power activation milestones, the health score, and lifecycle playbooks. The shape follows the Segment spec (identify, track, page, group), so if you already use Segment you can connect Airhop without code.

Your write key

Events are authenticated with your write key. It starts with wk_ and is write-only, so it is safe in client-side code. You will find it on the Install onboarding step and the Activation page.

There are two distinct keys:

• The widget public key (pk_...) identifies your widget. See Install the widget.
• The events write key (wk_...) authorizes event ingestion. It is the one used on this page.

Option A: the browser SDK

Add the SDK script the same way as the widget, then call identify and track:

<script src="https://app.airhop.ai/airhop.js" data-key="wk_your_write_key" async></script>
<script>
  // Right after a user logs in or signs up:
  airhop.identify(USER_ID, { email: USER_EMAIL, name: USER_NAME, plan: USER_PLAN });

  // When they do something meaningful:
  airhop.track('project_created', { projectId: '...' });
</script>

The SDK exposes four methods on window.airhop:

• airhop.identify(userId, traits): tie events to a known user and set traits like email, name, and plan.
• airhop.track(event, properties): record an action. Use clear, stable snake_case names.
• airhop.page(name, properties): record a page view.
• airhop.reset(): clear the current user (for example, on logout).

The SDK keeps a persistent anonymous id in localStorage and attaches it to every call, so events fired before a user logs in are merged onto their profile once you call identify. Calls are batched and flushed shortly after (and on page hide), sent to the ingest API with your write key.

Option B: the ingest batch API

For server-side events, or any non-browser source, POST directly to the ingest API. Authenticate with your write key as a Bearer token.

curl https://app.airhop.ai/ingest/v1/batch \
  -H "Authorization: Bearer wk_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "type": "identify",
        "userId": "user_123",
        "traits": { "email": "jo@acme.com", "name": "Jo Diaz", "plan": "pro" }
      },
      {
        "type": "track",
        "userId": "user_123",
        "event": "project_created",
        "properties": { "projectId": "p_1" }
      }
    ]
  }'

The API accepts the Segment call shape. The endpoints under /ingest/v1 are:

A single call can also be posted to its typed endpoint without a type field. The batch endpoint takes any mix of call types. Ingestion is processed asynchronously, so the API returns quickly with the number of calls received.

Authentication

Use the write key as a Bearer token:

Authorization: Bearer wk_your_write_key

Segment's HTTP API style is also accepted: HTTP Basic auth with the write key as the username, or a writeKey field in the body.

A Segment destination

If you already send events through Segment, you do not need to write any code. Add Airhop as a destination using Webhooks (Actions), and point it at:

https://app.airhop.ai/ingest/v1/segment

Set the Authorization header to Bearer wk_your_write_key. Segment forwards your identify, track, page, and group calls to Airhop unchanged, either one at a time or as a { "batch": [ ... ] } payload, and they flow into the same pipeline as the native SDK.

PostHog and Intercom can be wired up the same way, against /ingest/v1/posthog and /ingest/v1/intercom; Airhop normalizes each source's event shape into the same canonical events.

Grouping users into accounts

A group call links a user to an account (company), which is authoritative over Airhop's automatic domain grouping:

airhop.identify('user_123', { email: 'jo@acme.com' });
// then, with the account id and any account traits:
// (sent server-side or via a group call)

{
  "type": "group",
  "userId": "user_123",
  "groupId": "acme_inc",
  "traits": { "name": "Acme Inc" }
}

See Accounts and health for how accounts form and what feeds the health score.