> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Analytics Events

> Learn how to use the link.analytics_event_emitted webhook event to understand user activity during the Link flow.

## What are Link analytics events?

Link analytics events let you track the steps a user takes while connecting their telematics account through Terminal Link. Terminal emits a `link.analytics_event_emitted` webhook when a user performs a tracked action, such as starting Link, searching for a provider, opening a help guide, starting OAuth, or completing a connection.

This is useful when you need insight into the user journey prior to connection creation. You can use these events to understand where users drop off, which providers they search for, which unsupported providers they request, and which errors they encounter while connecting.

## Common use cases

* Build a funnel from `link_started` to `create_connection_completed` to understand and optimize conversion rates.
* Track provider search and selection with `provider_searched`, `provider_selected`, and `unsupported_provider_selected`.
* Identify sessions encountering connection failures, including invalid credentials, insufficient permissions, and internal errors.

## Event structure

All Link analytics events use the same webhook event type:

```json theme={null}
{
  "id": "evt_01GV12VR4DJP70GD1ZBK0SDWFH",
  "type": "link.analytics_event_emitted",
  "timestamp": "2026-06-07T13:51:06.059Z",
  "detail": {
    "event": "provider_selected",
    "sessionId": "019cda63-4d78-77bc-8a68-0b7ce4b48d19",
    "externalId": "fleet_456",
    "language": "en",
    "tags": ["app-4567"],
    "properties": {
      "provider": "geotab"
    }
  }
}
```

The `detail.event` field identifies the specific Link event. Fields like `sessionId`, `externalId`, `language`, `tags`, and `connectionId` apply across events, while the `properties` object depends on the event type. For example, search events include the user's `query` and `resultCount`, provider events include a `provider`, OAuth redirect events include a `result`, and failed connection events include a failure `reason`.

See the [`link.analytics_event_emitted` API reference](/api-reference/webhook-events/link-analytics-event-emitted) for the full schema, including every supported event name and property shape.

## Correlating events

Use `sessionId` to group activity from a single Link user session. A session represents one pass through the Link flow. If the same user opens Link again later or on a different device, Terminal assigns a new `sessionId`.

Use `externalId` and `tags` to connect Link activity back to your own systems. `externalId` is the identifier you pass when initializing Link. `tags` are the connection tags passed into Link. These fields are useful for joining Link analytics events to a customer, quote, workflow, or other internal identifier.

`connectionId` is present when Terminal knows the related connection, such as after a connection is created or when the session was started from a reconnection URL.

## Interpreting the funnel

A typical successful flow includes events like:

```text theme={null}
link_started
agreement_accepted
provider_searched
provider_selected
create_connection_attempted
create_connection_completed
```

Users do not always move linearly through Link. They may search multiple times, select the wrong provider, go back, open help guides, retry credentials, or leave before completing the flow.

There is no explicit abandonment event. To model abandonment, choose a timeout that fits your workflow and look for sessions where `create_connection_completed` has not occurred and the latest event is older than that threshold.

## Subscribing

Subscribe to `link.analytics_event_emitted` in the Terminal dashboard. One subscription covers all Link analytics events. In your webhook handler, branch on `detail.event`.

Terminal webhooks use at-least-once delivery. Deduplicate events by the top-level `id` field and handle events that arrive out of order. See [Webhooks](/terminal-platform/webhooks) for setup, request verification, retries, and replay behavior.

## Related docs

* [Link Component](/link-component)
* [Webhooks](/terminal-platform/webhooks)
* [`link.analytics_event_emitted`](/api-reference/webhook-events/link-analytics-event-emitted)