Browse documentation

Instrument

Identify customers

Use one stable customer identity across errors, traces, logs, replay, events, and AI calls.

Identity is what turns separate telemetry into a customer story. Anectico attaches a distinct_id to each relevant signal and resolves aliases to one canonical customer at query time.

Choose a stable ID

Use an application-owned identifier that does not change when someone updates their email or display name. A database user ID is usually the right choice.

good: user_8842
avoid: [email protected]

Email and name belong in customer properties. They remain searchable without becoming the primary identity key.

Identify after authentication

Call the SDK’s identify method after your application knows who the customer is.

The API key needs analytics:write for identify and group calls. If the same SDK also sends traces, logs, metrics, or errors, it needs ingest:write as well.

JavaScript / TypeScript

anectico.identify('user_8842', {
  email: '[email protected]',
  plan: 'pro',
});

Python

client.identify('user_8842', properties={
    'email': '[email protected]',
    'plan': 'pro',
})

Go

if err := client.Identify(ctx, "user_8842", map[string]any{
	"email": "[email protected]",
	"plan":  "pro",
}); err != nil {
	return err
}

Swift (iOS)

Anectico.identify("user_8842", set: [
    "email": "[email protected]",
    "plan": "pro",
])

Kotlin (Android)

Anectico.identify(
    "user_8842",
    mapOf("email" to "[email protected]", "plan" to "pro"),
)

React Native

await Anectico.identify('user_8842', {
  email: '[email protected]',
  plan: 'pro',
});

Flutter

await Anectico.identify('user_8842', set: {
  'email': '[email protected]',
  'plan': 'pro',
});

The browser and mobile SDKs keep an anonymous ID before login. Identifying a customer carries that prior ID so Anectico can attach the pre-login activity to the known customer.

Anectico only promotes that prior ID while it still belongs to an anonymous person. If a new stable ID arrives with a prior ID that already belongs to another identified customer, Anectico keeps the two customers separate and leaves the existing alias with its original owner. This conservative boundary prevents recycled identifiers or stale shared-device state from combining unrelated customer histories.

Out-of-order profile sources

Anectico resolves customer-property conflicts independently per key using the capture event’s source timestamp, with message_id as the deterministic equal-time tie-break. A delayed older CRM update therefore cannot overwrite a newer browser or server update. JSON null is stored as an explicit value; deletion requires the raw capture wire’s unset field.

High-level identify() methods send ordinary set updates at the SDK’s current time. For a batch importer that must preserve an external source timestamp, use the direct customer-property capture contract. Send an ordinary named event when its source payload should be visible in the customer timeline; the reserved identify event links identity and mutates the profile but does not create a timeline event.

Reset on logout

Always reset identity when a user logs out or when a shared device changes users.

JavaScript / TypeScript

anectico.reset();

Python

client.reset()

Go

if err := client.Reset(ctx); err != nil {
	return err
}

Swift (iOS)

Anectico.reset()

Kotlin (Android)

Anectico.reset()

React Native

await Anectico.reset();

Flutter

await Anectico.reset();

Resetting establishes a new user boundary: it rotates the SDK’s anonymous identity/session where applicable and clears groups, global error-user context, and uncaptured breadcrumbs. In the JavaScript browser SDK, it first stops active replay recorders and flushes their buffered prior-user tail; call startReplay() again after identifying the next user if recording should resume. Other already-captured telemetry remains queued with its original attribution; only mutable context that could otherwise attach to a later user’s signals is discarded.

Scope identity per request on servers

A backend handles many customers concurrently. Do not switch a process-wide identity for every request. Use request context or framework middleware instead.

JavaScript / TypeScript

import { context } from '@opentelemetry/api';
import { contextWithDistinctId } from '@anectico/sdk';

const requestContext = contextWithDistinctId(context.active(), user.id);
await context.with(requestContext, () => handleRequest());

Python

from anectico import reset_context_distinct_id, set_context_distinct_id

token = set_context_distinct_id(user.id)
try:
    handle_request()
finally:
    reset_context_distinct_id(token)

Go

requestContext := anectico.ContextWithDistinctID(r.Context(), user.ID)

The request-scoped identity should be active before creating spans, capturing errors, or writing logs.

Propagate only across trusted boundaries

Anectico uses W3C traceparent and baggage to continue a trace and customer identity across services. Treat incoming baggage from the public internet as untrusted. Enable identity extraction only behind a gateway that removes client-supplied baggage and recreates it from the authenticated session.

Allow outbound propagation only to services you control. Do not send customer identity baggage to arbitrary third-party URLs.

Associate customers with accounts

For B2B applications, add group membership after identifying the customer:

JavaScript / TypeScript

anectico.group('company', 'acme', { name: 'Acme Inc' });

Python

client.group('company', 'acme', {'name': 'Acme Inc'})

Go

if err := client.Group(ctx, "company", "acme", map[string]any{
	"name": "Acme Inc",
}); err != nil {
	return err
}

Swift (iOS)

Anectico.group(type: "company", key: "acme", set: ["name": "Acme Inc"])

Kotlin (Android)

Anectico.group("company", "acme", mapOf("name" to "Acme Inc"))

React Native

await Anectico.group('company', 'acme', { name: 'Acme Inc' });

Flutter

await Anectico.group('company', 'acme', set: {'name': 'Acme Inc'});

This records that the current customer belongs to the account. Use an immutable account ID for the group key and a human-readable name as a property.

Verify identity

Open Customers, search by ID or email, and confirm that the timeline contains activity from the expected browser, mobile application, and backend services. If signals are present elsewhere but missing from the timeline, follow Customer activity is not connecting.