Flutter SDK API

Functions, options, parameters, futures, and native behavior for the Teml Flutter SDK.

teml_flutter bridges Dart to the native iOS and Android SDKs. Native code owns identity, sessions, persistence, transport, and native crashes; Dart adds Flutter framework and uncaught async error capture. Public calls swallow channel failures so telemetry cannot crash the app.

Use a project key with ingest:write and analytics:write. Flutter replay is not supported.

Configure and shut down

await Teml.configure(
  const TemlOptions(
    apiKey: 'tm_...',
    environment: 'production',
    serviceVersion: '1.4.0',
  ),
);

API	Parameters	Returns	Behavior
`Teml.configure(options)`	`TemlOptions`	`Future<void>`	Configures native state and installs Dart handlers unless disabled.
`Teml.flush()`	—	`Future<void>`	Flushes the native event queue.
`Teml.shutdown()`	—	`Future<void>`	Removes Dart/native hooks, flushes, and releases resources.
`Teml.isConfigured`	property	`bool`	Dart-side view of whether configure completed. Diagnostic use only.
`TemlFlutter.installErrorCapture()`	—	`void`	Installs and chains `FlutterError.onError` and `PlatformDispatcher.onError`.
`TemlFlutter.uninstallErrorCapture()`	—	`void`	Restores prior handlers when they are still owned by Teml.
`TemlFlutter.isErrorCaptureInstalled`	property	`bool`	Whether Dart hooks are currently installed.

`TemlOptions`

Only apiKey is required. Null fields are omitted across the channel so native defaults apply.

Option	Type/default	Purpose
`apiKey`	`String`; required	Error/event API key.
`endpoint`	`String?`; native `https://api.teml.io`	API base URL.
`environment`	`String?`; native `development`	Deployment environment.
`release`, `dist`	`String?`	Release and artifact identifiers.
`serviceName`, `serviceVersion`	`String?`	Native resource identity; defaults from the app.
`flushAt`	`int?`; native `20`	Event-count flush threshold.
`flushIntervalMs`	`int?`; native `5000`	Periodic flush; zero disables it.
`maxStackTraceFrames`	`int?`; native `50`	Dart/native frame cap.
`breadcrumbCapacity`	`int?`; native `100`	Native breadcrumb capacity.
`maxQueueSize`	`int?`; native `10000`	Native event queue cap.
`errorSampleRate`	`double?`; native `1`	Non-fatal error sampling from 0–1.
`enableCrashReporting`	`bool?`; native `true`	Install native crash handlers.
`debug`	`bool?`; native `false`	Native diagnostic logging.
`enableDartErrorCapture`	`bool`; `true`	Dart-only automatic error handlers.

Identity, accounts, and events

Method	Parameters	Returns	Behavior
`Teml.identify(distinctId, {set})`	stable ID; person properties	`Future<void>`	Links anonymous and known identity.
`Teml.group(type, key, {set})`	account type/key; properties	`Future<void>`	Records membership and `$groupidentify`.
`Teml.capture(event, {properties})`	event; properties	`Future<void>`	Queues a durable diagnostic event.
`Teml.screen(name, {properties})`	screen; properties	`Future<void>`	Queues `$screen` and `$screen_name`.
`Teml.reset()`	—	`Future<void>`	Logout: rotates native identity/session and clears groups.
`Teml.getDistinctId()`	—	`Future<String>`	Current identity or empty string.
`Teml.getSessionId()`	—	`Future<String>`	Current session without extending idle lifetime, or empty string.

Errors, messages, users, and breadcrumbs

Method	Parameters	Returns	Behavior
`Teml.captureError(error, stackTrace, {options})`	object; optional stack; options	`Future<String?>`	Parses Dart frames and forwards a caught error to native. Only `options.tags` applies to this bridge path.
`Teml.captureMessage(message, {level, options})`	text; level default `info`; options	`Future<String?>`	Native message capture with full options fidelity.
`Teml.addBreadcrumb(category, message, {level, data})`	fields	`Future<void>`	Adds native trail context for the next error.
`Teml.setUser(user)`	`TemlUser`	`Future<void>`	Sets global error user context.
`Teml.clearUser()`	—	`Future<void>`	Clears error user context.

CaptureOptions fields are tags, extra, user, level, and fingerprint. Only tags is used by captureError; all fields can be used by captureMessage. TemlUser fields are id, email, username, ipAddress, and segment. Breadcrumb constants live in TemlBreadcrumbLevel.

Automatic handlers use mechanisms TemlMechanism.frameworkError and TemlMechanism.platformDispatcher. They forward to the prior handler afterward, preserving normal Flutter behavior. Native fatal crashes are handled by the underlying SDK.

Backend propagation

Teml.propagationHeaders(): Future<Map<String,String>> returns a fresh W3C traceparent and current identity baggage. Send it only to a trusted application backend. The backend must authenticate the request independently.

Stack utility exports

The package exports TemlFrame, parseStackTrace, parseStackString, framesToJson, and maxDartFrames for custom error integrations. Normal application code should call Teml.captureError, which uses those helpers automatically.

Teml does not currently symbolicate Dart frames obfuscated with --obfuscate. Retain Flutter debug information and use flutter symbolize outside Teml for those builds.