Providers

A provider is an adapter that delivers analytics events to a specific backend (Amplitude, Mixpanel, PostHog, etc.). Providers implement a stable interface so your application code never depends on a vendor SDK directly.

The Provider interface

Go

type Provider interface {
    Metadata() ProviderMetadata
    Hooks() []hooks.Hook

    Track(ctx context.Context, event TrackMessage) error
    Identify(ctx context.Context, msg IdentifyMessage) error
    Group(ctx context.Context, msg GroupMessage) error
    Page(ctx context.Context, msg PageMessage) error
    Alias(ctx context.Context, msg AliasMessage) error

    Flush(ctx context.Context) error
    Shutdown(ctx context.Context) error
}

TypeScript

interface Provider {
  metadata(): ProviderMetadata;
  hooks(): Hook[];

  track(msg: TrackMessage): Promise<void>;
  identify(msg: IdentifyMessage): Promise<void>;
  group(msg: GroupMessage): Promise<void>;
  page(msg: PageMessage): Promise<void>;
  alias(msg: AliasMessage): Promise<void>;

  flush(): Promise<void>;
  shutdown(): Promise<void>;
}

Kotlin

interface Provider {
  fun metadata(): ProviderMetadata
  fun hooks(): List<Hook>

  suspend fun track(msg: TrackMessage)
  suspend fun identify(msg: IdentifyMessage)
  suspend fun group(msg: GroupMessage)
  suspend fun page(msg: PageMessage)
  suspend fun alias(msg: AliasMessage)

  suspend fun flush()
  suspend fun shutdown()
}

Providers that don't support a given operation return ErrUnsupportedOperation rather than silently no-op — preventing silent data loss.

Message types

Every call to the runtime dispatches a typed message struct to the provider:

Method	Message type	Key fields
Track	TrackMessage	EventName, Properties, UserId, AnonymousId, Context
Identify	IdentifyMessage	UserId, AnonymousId, Traits, Context
Group	GroupMessage	UserId, GroupId, Traits, Context
Page	PageMessage	UserId, Name, Properties, Context
Alias	AliasMessage	UserId, PreviousId

MessageContext carries structured environment metadata: UserAgent, Locale, IP, App, Device, OS, Screen, Campaign, and an Extra map for custom keys.

Provider capabilities

Go

type ProviderCapabilities struct {
    Track    bool
    Identify bool
    Group    bool
    Page     bool
    Alias    bool
}

TypeScript

interface ProviderCapabilities {
  track: boolean;
  identify: boolean;
  group: boolean;
  page: boolean;
  alias: boolean;
}

Kotlin

data class ProviderCapabilities(
    val track: Boolean = true,
    val identify: Boolean = true,
    val group: Boolean = true,
    val page: Boolean = true,
    val alias: Boolean = true,
)

The runtime checks capabilities before dispatch and records Dropped outcomes for unsupported operations.

Multi-provider dispatch

The client sends events to all registered providers simultaneously:

Go

client := analytics.NewClient(
    analytics.WithProviders(amplitudeProvider, posthogProvider),
)

// Both providers receive the event concurrently.
// Per-provider outcomes accessible via TrackDetailed:
result, err := client.TrackDetailed(ctx, event)
// result.Success  — providers that succeeded
// result.Failed   — providers that failed (permanent)

TypeScript

const client = new Client({
  providers: [amplitudeProvider, posthogProvider],
});

// Both providers receive the event concurrently via Promise.allSettled.
// Per-provider outcomes accessible via trackDetailed:
const result = await client.trackDetailed(event);
// result.success  — providers that succeeded
// result.failed   — providers that failed (permanent)

Kotlin

val client = Client(ClientOptions(
    providers = listOf(amplitudeProvider, posthogProvider),
))

// Both providers receive the event concurrently via coroutines.
// Per-provider outcomes accessible via trackDetailed:
val result = client.trackDetailed(event)
// result.success  — providers that succeeded
// result.failed   — providers that failed (permanent)

Delivery states

State	Meaning
Delivered	Provider confirmed receipt
Failed	Permanently rejected after max retries
Dropped	Discarded by sampling, queue overflow, schema violation, or unsupported operation

Built-in providers

Provider	Language	Status
Amplitude	Go, TypeScript, Kotlin	✅ Available
event-spec server	Go, TypeScript, Kotlin	✅ Available
Noop	Go	✅ Available
PostHog	Go	❌ Planned
Mixpanel	Go	❌ Planned
Segment	Go	❌ Planned
GA4	Go	❌ Planned

Writing a custom provider

See Providers — Custom for a full walkthrough.