NexusClient & options

INexusClientCopy Anchor Link

interface Inverge.Nexus.INexusClient

A configured connection to one Nexus environment.

Register it as a singleton and share it. It is thread-safe, it owns the background buffers, and building one per request would both leak buffers and lose the batching that keeps telemetry cheap.

DroppedCopy Anchor Link

long Dropped { get; }

How many buffered items have been dropped because a buffer was full.

Non-zero means telemetry is being lost — either the backend is unreachable or the process is producing more than MaxQueue can hold. Worth exposing as a metric.

ErrorsCopy Anchor Link

ErrorsResource Errors { get; }

Error monitoring.

EventsCopy Anchor Link

EventsResource Events { get; }

Product analytics.

FlagsCopy Anchor Link

FlagsResource Flags { get; }

Feature flags.

InAppCopy Anchor Link

InAppResource InApp { get; }

In-app messages.

LinksCopy Anchor Link

LinksResource Links { get; }

Deep links and attribution.

LiveActivitiesCopy Anchor Link

LiveActivitiesResource LiveActivities { get; }

Live Activities.

LogsCopy Anchor Link

LogsResource Logs { get; }

Structured logging.

OptionsCopy Anchor Link

NexusOptions Options { get; }

The options this client was built with.

PendingCopy Anchor Link

int Pending { get; }

How many buffered telemetry items are waiting to be sent.

PushCopy Anchor Link

PushResource Push { get; }

Push notifications.

RealtimeCopy Anchor Link

RealtimeResource Realtime { get; }

Realtime rooms.

RemoteConfigCopy Anchor Link

RemoteConfigResource RemoteConfig { get; }

Remote Config.

ReplayCopy Anchor Link

ReplayResource Replay { get; }

Session replay ingestion.

SessionsCopy Anchor Link

SessionsResource Sessions { get; }

People and journey sessions.

SurveysCopy Anchor Link

SurveysResource Surveys { get; }

In-product surveys.

VoiceCopy Anchor Link

VoiceResource Voice { get; }

Voice (CPaaS) call control.

Background()Copy Anchor Link

INexusClient Background(int workers = 1)

A sibling client on which every call is fire-and-forget.

Calls that need a response cannot work through it — there is nothing to return. Use the normal client for flags and Remote Config.

Parameters

Returns INexusClient

CaptureExceptionAsync()Copy Anchor Link

Task<ErrorCaptureResult> CaptureExceptionAsync(Exception exception, bool handled = true, object? errorContext = null, CancellationToken cancellationToken = default)

Reports a caught exception.

Parameters

Returns Task<ErrorCaptureResult>

EmitAsync()Copy Anchor Link

Task<EmitResult> EmitAsync(string room, string eventName, object? payload = null, CancellationToken cancellationToken = default)

Emits a named event to a realtime room.

Parameters

Returns Task<EmitResult>

FlushAsync()Copy Anchor Link

Task FlushAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Ships every buffered event and log line.

Call it before a short-lived process exits. A console app or a function that returns without flushing loses whatever is still buffered.

Parameters

IdentifyAsync()Copy Anchor Link

Task<IdentifyResult> IdentifyAsync(string distinctId, string? email = null, string? name = null, string? phone = null, object? traits = null, CancellationToken cancellationToken = default)

Sets the current person locally and creates or updates them server-side.

Parameters

Returns Task<IdentifyResult>

IsEnabledAsync()Copy Anchor Link

Task<bool> IsEnabledAsync(string key, string? distinctId = null, object? properties = null, bool fallback = false, CancellationToken cancellationToken = default)

Whether a feature flag is on for a person.

Parameters

Returns Task<bool>

Reset()Copy Anchor Link

void Reset()

Forgets the person and starts a new session — what you want on logout.

ResolveContext()Copy Anchor Link

NexusTelemetryContext ResolveContext(NexusTelemetryContext? contextOverrides = null)

Client options, ambient context and per-call overrides, resolved in that order of increasing precedence.

Parameters

Returns NexusTelemetryContext

SendAsync()Copy Anchor Link

Task<JsonNode?> SendAsync(NexusRequest request, CancellationToken cancellationToken = default)

Executes a request against an endpoint the typed surface does not cover.

Parameters

Returns Task<JsonNode?>

Track()Copy Anchor Link

void Track(string name, object? properties = null, DateTimeOffset? timestamp = null, NexusTelemetryContext? context = null)

Captures one event. Returns as soon as it is buffered.

Parameters

NexusClientCopy Anchor Link

class Inverge.Nexus.NexusClient

One object, every Nexus product.

Build one per process and share it — see INexusClient. In an ASP.NET Core or worker app, prefer services.AddNexus(...) from Inverge.Nexus.Extensions.Logging, which registers it correctly and flushes it on shutdown.

NexusClientCopy Anchor Link

new NexusClient(string apiKey, Action<NexusOptions>? configure = null)

Creates a client for an API key, layered over the NEXUS_* environment.

Parameters

NexusClientCopy Anchor Link

new NexusClient(NexusOptions options)

Creates a client from options.

Parameters

NexusClientCopy Anchor Link

new NexusClient(NexusOptions options, HttpClient httpClient)

Creates a client that sends through a caller-supplied HttpClient.

This is the IHttpClientFactory path: the app's own handler pipeline, resilience policies and connection lifetime apply, and the client is not disposed here.

Parameters

NexusClientCopy Anchor Link

new NexusClient(NexusOptions options, INexusTransport transport)

Creates a client that sends through a custom transport.

Parameters

DistinctIdCopy Anchor Link

string? DistinctId { get; }

The person bound to the current execution flow, if any.

DroppedCopy Anchor Link

long Dropped { get; }

ErrorsCopy Anchor Link

ErrorsResource Errors { get; }

EventsCopy Anchor Link

EventsResource Events { get; }

FlagsCopy Anchor Link

FlagsResource Flags { get; }

InAppCopy Anchor Link

InAppResource InApp { get; }

IsDisposedCopy Anchor Link

bool IsDisposed { get; }

Whether the client has been disposed.

LinksCopy Anchor Link

LinksResource Links { get; }

LiveActivitiesCopy Anchor Link

LiveActivitiesResource LiveActivities { get; }

LogsCopy Anchor Link

LogsResource Logs { get; }

OptionsCopy Anchor Link

NexusOptions Options { get; }

PendingCopy Anchor Link

int Pending { get; }

PushCopy Anchor Link

PushResource Push { get; }

RealtimeCopy Anchor Link

RealtimeResource Realtime { get; }

RemoteConfigCopy Anchor Link

RemoteConfigResource RemoteConfig { get; }

ReplayCopy Anchor Link

ReplayResource Replay { get; }

SessionsCopy Anchor Link

SessionsResource Sessions { get; }

SurveysCopy Anchor Link

SurveysResource Surveys { get; }

VoiceCopy Anchor Link

VoiceResource Voice { get; }

Background()Copy Anchor Link

INexusClient Background(int workers = 1)

Parameters

Returns INexusClient

CaptureExceptionAsync()Copy Anchor Link

Task<ErrorCaptureResult> CaptureExceptionAsync(Exception exception, bool handled = true, object? errorContext = null, CancellationToken cancellationToken = default)

Parameters

Returns Task<ErrorCaptureResult>

Dispose()Copy Anchor Link

void Dispose()

Flushes and releases everything. Prefer DisposeAsync.

The flush is genuinely asynchronous, so this runs it on the thread pool and waits. Doing it inline would deadlock under a synchronization context that still has one thread. Hosts that support IAsyncDisposable — which includes the ASP.NET Core and Generic Host containers — take the async path and never reach this.

DisposeAsync()Copy Anchor Link

ValueTask DisposeAsync()

Returns ValueTask

EmitAsync()Copy Anchor Link

Task<EmitResult> EmitAsync(string room, string eventName, object? payload = null, CancellationToken cancellationToken = default)

Parameters

Returns Task<EmitResult>

FlushAsync()Copy Anchor Link

Task FlushAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

IdentifyAsync()Copy Anchor Link

Task<IdentifyResult> IdentifyAsync(string distinctId, string? email = null, string? name = null, string? phone = null, object? traits = null, CancellationToken cancellationToken = default)

Parameters

Returns Task<IdentifyResult>

IsEnabledAsync()Copy Anchor Link

Task<bool> IsEnabledAsync(string key, string? distinctId = null, object? properties = null, bool fallback = false, CancellationToken cancellationToken = default)

Parameters

Returns Task<bool>

IsServiceEnabled()Copy Anchor Link

bool IsServiceEnabled(string service)

Whether a product is on — Enabled, Services and the NEXUS_<SERVICE>_ENABLED environment, off wins. Every service is on by default.

Parameters

Returns bool

Reset()Copy Anchor Link

void Reset()

ResolveContext()Copy Anchor Link

NexusTelemetryContext ResolveContext(NexusTelemetryContext? contextOverrides = null)

Parameters

Returns NexusTelemetryContext

SendAsync()Copy Anchor Link

Task<JsonNode?> SendAsync(NexusRequest request, CancellationToken cancellationToken = default)

Parameters

Returns Task<JsonNode?>

Track()Copy Anchor Link

void Track(string name, object? properties = null, DateTimeOffset? timestamp = null, NexusTelemetryContext? context = null)

Parameters

NexusContextCopy Anchor Link

static class Inverge.Nexus.NexusContext

The ambient telemetry context: bind identity once at the edge of a request, and everything captured underneath inherits it.

Backed by AsyncLocal1, so the context is correct per request and flows across await` boundaries into whatever the handler calls — including work started on the thread pool.

One AsyncLocal1caveat worth knowing: a value set inside anasyncmethod does not flow back out to its caller. Bind at the level that should own the context — the middleware, the job handler — rather than deep inside a helper, or useScope`, whose lifetime is explicit.

Bind()Copy Anchor Link

static void Bind(NexusTelemetryContext context)

Merges values into the current context for the current flow.

Parameters

Clear()Copy Anchor Link

static void Clear()

Drops the whole context: no person, no session, no device.

Identify()Copy Anchor Link

static void Identify(string? distinctId, IReadOnlyDictionary<string, object?>? properties = null)

Sets the current person for this flow.

This binds local context only. To also create or update the person server-side, call client.IdentifyAsync(...).

Parameters

NewDeviceKey()Copy Anchor Link

static string NewDeviceKey()

A fresh opaque device key.

Returns string

NewSessionKey()Copy Anchor Link

static string NewSessionKey()

A fresh opaque session key.

Returns string

Reset()Copy Anchor Link

static void Reset(bool keepDevice = true)

Forgets the person and starts a new session — what you want on logout.

Parameters

Scope()Copy Anchor Link

static IDisposable Scope(NexusTelemetryContext context)

Binds values for the lifetime of the returned scope, restoring the previous context when it is disposed.

Parameters

Returns IDisposable

Scope()Copy Anchor Link

static IDisposable Scope(string? distinctId = null, string? sessionKey = null, string? deviceKey = null, string? release = null, string? appVersion = null, string? osType = null, string? osVersion = null, string? browser = null, string? country = null, string? url = null, IReadOnlyDictionary<string, object?>? properties = null)

Binds the fields you name for the lifetime of the returned scope.

Parameters

Returns IDisposable

Set()Copy Anchor Link

static void Set(NexusTelemetryContext? context)

Replaces the context for the current execution flow.

Parameters

CurrentCopy Anchor Link

NexusTelemetryContext Current { get; }

The context in force for the current execution flow.

NexusOptionsCopy Anchor Link

class Inverge.Nexus.NexusOptions

Everything the client needs to talk to one Nexus environment.

An API key belongs to a single environment, so one client writes to one environment. The type is mutable so it works with the options pattern (services.AddNexus(o => ...)); the client copies it at construction, which means mutating it afterwards changes nothing already running.

NexusOptionsCopy Anchor Link

new NexusOptions()

FromEnvironment()Copy Anchor Link

static NexusOptions FromEnvironment(Action<NexusOptions>? configure = null)

Builds options from the NEXUS_* environment, then applies configure on top.

The ordering matters and is the whole point: explicit code wins over the environment for the values it sets, while the values it leaves alone stay environment-driven, so a deployment can change settings such as NEXUS_TIMEOUT or the API key without a rebuild.

Parameters

Returns NexusOptions

ApiKeyCopy Anchor Link

string ApiKey { get; set; }

The tenant API key (nxs_...). Required.

AppVersionCopy Anchor Link

string? AppVersion { get; set; }

Default appVersion for telemetry that does not set one.

BaseUrlCopy Anchor Link

string BaseUrl { get; set; }

The API origin. Point it at a local backend while developing.

BatchCopy Anchor Link

bool Batch { get; set; }

Buffer events and log lines and ship them in the background, keeping telemetry off the request's hot path. Turn it off in a short-lived process if you prefer explicit sends; FlushAsync works either way.

DebugCopy Anchor Link

bool Debug { get; set; }

Verbose SDK diagnostics.

DefaultHeadersCopy Anchor Link

IDictionary<string, string> DefaultHeaders { get; }

Headers merged into every request.

DefaultPropertiesCopy Anchor Link

IDictionary<string, object?> DefaultProperties { get; }

Properties merged into every captured event.

DiagnosticSinkCopy Anchor Link

NexusDiagnosticSink? DiagnosticSink { get; set; }

Where the SDK reports on itself — dropped batches, retries, delivery failures. Left unset, those messages go nowhere.

Inverge.Nexus.Extensions.Logging wires this to ILogger automatically. Set it yourself when you are not using Microsoft.Extensions.

EnabledCopy Anchor Link

bool Enabled { get; set; }

false switches every Nexus service off without removing any code. Defaults to true: every service is on. Also NEXUS_ENABLED=false.

EnvironmentVariablesCopy Anchor Link

IReadOnlyDictionary<string, string> EnvironmentVariables { get; }

Environment variable names, by the option each one fills.

FlushIntervalCopy Anchor Link

TimeSpan FlushInterval { get; set; }

How long a partial batch waits before it is sent anyway.

HttpBaseCopy Anchor Link

string HttpBase { get; }

The API origin without a trailing slash.

MaxBatchCopy Anchor Link

int MaxBatch { get; set; }

Maximum items per batched request. The ingest endpoints accept 1000; the default of 50 keeps individual requests small and failures cheap.

MaxQueueCopy Anchor Link

int MaxQueue { get; set; }

Buffer capacity. Items beyond it are dropped and counted rather than growing memory without bound — a backend outage costs the memory you chose, not all of it.

MaxRetriesCopy Anchor Link

int MaxRetries { get; set; }

How many times to retry a safe request — telemetry ingest and reads — on a network error, 429, or 5xx. Calls with a side effect a user would notice twice are never retried, whatever this is set to.

OsTypeCopy Anchor Link

string? OsType { get; set; }

Default osType for telemetry that does not set one.

OsVersionCopy Anchor Link

string? OsVersion { get; set; }

Default osVersion for telemetry that does not set one.

RealtimeUrlCopy Anchor Link

string? RealtimeUrl { get; set; }

The Socket.IO origin for the realtime listener. Defaults to BaseUrl.

ReleaseCopy Anchor Link

string? Release { get; set; }

Default release for telemetry that does not set one.

RemoteConfigCacheTtlCopy Anchor Link

TimeSpan RemoteConfigCacheTtl { get; set; }

How long a resolved Remote Config template is reused in-process before it is revalidated. Defaults to 30 seconds.

ResolvedUserAgentCopy Anchor Link

string ResolvedUserAgent { get; }

The user agent actually sent.

RetryBackoffCopy Anchor Link

TimeSpan RetryBackoff { get; set; }

Base backoff delay; it doubles per attempt and carries jitter.

ServicesCopy Anchor Link

IDictionary<string, bool> Services { get; }

Per-service switches, keyed by NexusServices names, e.g. Services[NexusServices.LiveActivities] = false. Empty by default — every service is on unless switched off here or by its NEXUS_<SERVICE>_ENABLED environment variable (off wins).

SilentCopy Anchor Link

bool Silent { get; set; }

Never let a Nexus failure reach your code: calls return a default instead of throwing, and the failure goes to diagnostics. Background delivery is always silent regardless.

SocketBaseCopy Anchor Link

string SocketBase { get; }

The Socket.IO origin: RealtimeUrl, or the API origin.

TimeoutCopy Anchor Link

TimeSpan Timeout { get; set; }

Per-request timeout. Defaults to 10 seconds.

UserAgentCopy Anchor Link

string? UserAgent { get; set; }

Overrides the default Inverge.Nexus.NET/<version> user agent.

ApplyEnvironment()Copy Anchor Link

void ApplyEnvironment(Func<string, string?>? read = null)

Overlays any NEXUS_* variables that are set.

Parameters

Clone()Copy Anchor Link

NexusOptions Clone()

A deep copy, so the client is immune to later mutation.

Returns NexusOptions

IsServiceEnabled()Copy Anchor Link

bool IsServiceEnabled(string service)

Whether a service is on: not switched off by Enabled, Services or the environment. Unknown names count as on.

Parameters

Returns bool

ServiceOffReason()Copy Anchor Link

string? ServiceOffReason(string service)

Why a service is off (for diagnostics), or null when it is on.

Parameters

Returns string?

UrlFor()Copy Anchor Link

string UrlFor(string path)

The absolute URL for a request path.

Parameters

Returns string

Validate()Copy Anchor Link

void Validate()

Throws when the options cannot produce a working client.

NexusRequestCopy Anchor Link

class Inverge.Nexus.NexusRequest

One call to the Nexus partner API.

Resources build these; the client executes them. Pass one to SendAsync to reach an endpoint the typed surface does not cover yet.

NexusRequestCopy Anchor Link

new NexusRequest(string method, string path, JsonObject? body = null, IReadOnlyDictionary<string, string>? headers = null, bool retryable = false)

Creates a request.

Parameters

BodyCopy Anchor Link

JsonObject? Body { get; }

The JSON body, or null.

HeadersCopy Anchor Link

IReadOnlyDictionary<string, string>? Headers { get; }

Headers for this request only, merged over the configured defaults.

MethodCopy Anchor Link

string Method { get; }

The HTTP method, upper-cased.

PathCopy Anchor Link

string Path { get; }

The path, rooted at the configured API origin.

RetryableCopy Anchor Link

bool Retryable { get; }

Whether a failed attempt may be repeated.

BodyJson()Copy Anchor Link

string BodyJson()

The body as compact JSON — useful in assertions and logs.

Returns string

NexusServicesCopy Anchor Link

static class Inverge.Nexus.NexusServices

The Nexus products that can be switched off without removing the code that uses them. Every service is on by default.

From the environment (read by FromEnvironment): NEXUS_LIVE_ACTIVITIES_ENABLED=false switches only Live Activities off; NEXUS_ENABLED=false switches everything off. false, 0, off and no mean off; anything else, or unset, means on.

In code: options.Services[NexusServices.Push] = false or options.Enabled = false. Off wins — a service is on only if neither the code nor the environment turns it off, so operations can always switch one off with an environment variable.

A switched-off service makes no request and never throws: calls return their neutral result (flags → your fallback, Remote Config → your default, counts → zero), and events / logs are not even buffered.

ForPath()Copy Anchor Link

static string? ForPath(string? path)

The service a /partner/... path belongs to, or null for unswitched paths.

Parameters

Returns string?

IsOn()Copy Anchor Link

static bool IsOn(string? value)

false / 0 / off / no = off; anything else, or unset, = on.

Parameters

Returns bool

Normalize()Copy Anchor Link

static string? Normalize(string? service)

The canonical service name (accepts liveActivities etc.), or null if unknown.

Parameters

Returns string?

EnvironmentVariablesCopy Anchor Link

IReadOnlyDictionary<string, string> EnvironmentVariables { get; }

Service → the environment variable that switches it.

NexusTelemetryContextCopy Anchor Link

class Inverge.Nexus.NexusTelemetryContext

Who and what a piece of telemetry belongs to.

The same type serves two jobs: it is the ambient context bound by NexusContext, and it is the per-call override every resource method accepts. That is why none of the capture methods carry ten identity parameters.

Resolution order, lowest first: client options → ambient context → the context argument passed to the call.

NexusTelemetryContextCopy Anchor Link

new NexusTelemetryContext()

AppVersionCopy Anchor Link

string? AppVersion { get; init; }

The application version.

BrowserCopy Anchor Link

string? Browser { get; init; }

The browser, for web traffic.

CountryCopy Anchor Link

string? Country { get; init; }

Two-letter country code.

DeviceKeyCopy Anchor Link

string? DeviceKey { get; init; }

The device this belongs to.

DistinctIdCopy Anchor Link

string? DistinctId { get; init; }

The person this belongs to — your own user id.

IsEmptyCopy Anchor Link

bool IsEmpty { get; }

Whether every field is unset.

OsTypeCopy Anchor Link

string? OsType { get; init; }

The platform: ios, android, web, server.

OsVersionCopy Anchor Link

string? OsVersion { get; init; }

The OS version.

PropertiesCopy Anchor Link

IReadOnlyDictionary<string, object?>? Properties { get; init; }

Properties merged into every event captured in this scope — a request id, a tenant, whatever every event in the scope should carry.

ReleaseCopy Anchor Link

string? Release { get; init; }

The build/release that produced it.

SessionKeyCopy Anchor Link

string? SessionKey { get; init; }

The journey session this belongs to.

UrlCopy Anchor Link

string? Url { get; init; }

The URL or route in play.

EmptyCopy Anchor Link

static NexusTelemetryContext Empty

A context with nothing set.

Merge()Copy Anchor Link

NexusTelemetryContext Merge(NexusTelemetryContext? other)

This context with every value set on other applied over it. Properties are merged key by key, not replaced wholesale.

Parameters

Returns NexusTelemetryContext

NexusVersionCopy Anchor Link

static class Inverge.Nexus.NexusVersion

The SDK's own version, as reported to the API.

CurrentCopy Anchor Link

string Current { get; }

The package version, e.g. 1.0.0.

UserAgentCopy Anchor Link

string UserAgent { get; }

The User-Agent the SDK sends.

RoomMessageCopy Anchor Link

class Inverge.Nexus.RoomMessage

One realtime message: the room, the event name or names, and the payload.

RoomMessageCopy Anchor Link

new RoomMessage(string room, string event, object? payload = null)

Creates a message carrying one event name.

Parameters

RoomMessageCopy Anchor Link

new RoomMessage(string room, IEnumerable<string> events, object? payload = null)

Creates a message carrying several event names.

Parameters

EventsCopy Anchor Link

IReadOnlyList<string> Events { get; }

The event names to emit.

PayloadCopy Anchor Link

object? Payload { get; }

The payload delivered to subscribers.

RoomCopy Anchor Link

string Room { get; }

The room name, as joined by subscribers.