Flutter API reference
The complete API reference for the Knock Flutter SDK.
In this section, you'll find the documentation for the classes and methods available in the Flutter SDK.
Knock
#The top-level Knock class. Create an authenticated Knock client instance for interacting with Knock.
Params
The public API key for the Knock environment.
Any additional options to instantiate your Knock instance with.
Returns
Knock
authenticate
#Authenticates the current user.
Params
The ID of the user to authenticate against.
Optional second positional argument. The signed user token, required when using enhanced security mode in the environment.
Returns
void
logout
#Clears any user authentication and disposes of any created clients.
Returns
void
isAuthenticated
#Returns whether or this Knock instance is authenticated. Passing true will check the presence of the userToken as well.
Returns
bool
dispose
#Disposes the cached KnockApiClient, which closes the Phoenix socket and ends the client status stream. Call this when the Knock instance is no longer needed (for example on logout or app teardown). Call it alongside (or before) FeedClient.dispose() for any feed clients you created.
Returns
void
Push tokens
#The SDK does not read FCM or APNs tokens. Obtain tokens in your app (for example with firebase_messaging), then register them with registerTokenForChannel. See the README section on push notifications.
client
#Returns the shared KnockApiClient used for HTTP and Phoenix traffic. Most apps do not need this; it is cached lazily and is useful for advanced integration or debugging.
Returns
KnockApiClient
messages
#Returns the MessagesClient for the authenticated user.
Returns
MessagesClient
user
#Returns the current user client.
Returns
UserClient
preferences
#Returns the current preferences client.
Returns
PreferencesClient
feed
#Returns a new feed client for the channel ID specified.
Params
The channel ID from Knock for the in-app feed.
Any additional options to instantiate your feed instance with.
Returns
FeedClient
Types
#These types appear throughout the public API. In 1.0.0, several were renamed with a Knock prefix.
KnockApiClient
#HTTP client and Phoenix connection manager (formerly ApiClient). You usually access it only via Knock.client() if at all.
KnockApiResponse
#Wrapper for successful API payloads (formerly ApiResponse).
KnockApiClientStatus
#Status values for the shared API client connection (formerly ApiClientStatus).
KnockApiException
#Thrown when the API returns an error response (formerly ApiError). It implements Exception, not Error, so use on KnockApiException catch (e) (not on Error). Inspect fields such as response.status for HTTP details.
NetworkStatus
#Enum describing feed load state: initial, loading, fetchMore, ready, and error. Feed.initialState() uses NetworkStatus.initial. Prefer checking feed.requestInFlight (and related flags) instead of comparing to NetworkStatus.ready only. See the feed stream on FeedClient.
KnockOptions
#Optional configuration for Knock. Fields include host to override the API base URL (for example for staging).
UserClient
#Methods for interacting with the current user resource in Knock. You access this under knock.user().
get
#Returns the current authenticated user from Knock.
Returns
Future<User>
identify
#Upserts the current authenticated user properties in Knock.
Named parameters (email, name, phoneNumber, avatar, locale) use a sentinel default: omitting a parameter leaves that field unchanged in Knock; passing null clears it.
Returns
Future<User>
getChannelData
#Returns any channel data set for the channelId given for the current authenticated user.
The channel ID from Knock.
Returns
Future<ChannelData>
setChannelData
#Updates the channel data for the current user on the channel specified with channelId.
Params
The channel ID to update the channel data for.
The data to update for the channel data.
Returns
Future<ChannelData>
registerTokenForChannel
#Registers the current device's token for the user in Knock.
Failed HTTP responses (4xx/5xx) throw KnockApiException.
Params
The push channel ID from Knock.
The device token to register.
Optional. BCP 47 language tag for the device locale. When omitted, the SDK uses PlatformDispatcher.instance.locale.toLanguageTag().
Returns
Future<ChannelData>
deregisterTokenForChannel
#De-registers the current device's token for the user in Knock.
Failed HTTP responses (4xx/5xx) throw KnockApiException.
Params
The push channel ID from Knock.
The device token to remove.
Returns
Future<ChannelData>
PreferencesClient
#Access via knock.preferences() or knock.preferences(options: ...).
PreferencesOptions
#Constructor options for the preferences client.
Params
Which preference set to use. Defaults to 'default'. Example: knock.preferences(options: PreferencesOptions(preferenceSetId: 'tenant-x')).
getAll
#Returns all preference sets for the current user.
Returns
Future<List<PreferenceSet>>
get
#Returns a single preference set for the current user.
Returns
Future<PreferenceSet>
set
#The preference set to upsert.
Returns
Future<PreferenceSet>
FeedClient
#Returned from knock.feed(...). Each call returns a new client; you own its lifetime.
The in-app channel ID from Knock.
Default options to apply to the feed instance.
Returns
FeedClient
FeedClient lifecycle
#Each knock.feed(...) returns a distinct FeedClient. Pair creation with feedClient.dispose() when you tear down the corresponding UI (typically in State.dispose()). Knock.dispose() does not dispose feed clients; it only disposes the shared KnockApiClient.
dispose
#Releases resources for this feed: Phoenix channel subscription, socket lifecycle listeners, status subscription, and broadcast event stream. Call when navigating away or in dispose(). Safe to call more than once (idempotent).
Returns
void
feed
#Stream of Feed snapshots. Subscribing triggers an initial HTTP fetch on listen (not gated on a replayed Phoenix open event). Expect Feed.initialState() with NetworkStatus.initial immediately, then a transition through loading toward ready.
Returns
Stream<Feed>
fetchNextPage
#Fetches the next page when pageInfo.after is non-null. If pageInfo.after is null, this is a no-op.
Returns
void
on
#Binds an event listener to the feed.
The event stream ends when the underlying KnockApiClient is disposed (knock.dispose() / knock.logout()) or when this FeedClient.dispose() runs. Calling markAs* after disposal throws StateError.
Params
The type of event to listen to.
Returns
Stream<FeedEvent>
markAsSeen
#Marks the given set of items as seen. Will optimistically update the feed.
Params
One or more feed items to mark.
Returns
Future<void>
markAsUnseen
#Marks the given set of items as unseen. Will optimistically update the feed.
Params
One or more feed items to mark.
Returns
Future<void>
markAsRead
#Marks the given set of items as read. Will optimistically update the feed.
Params
One or more feed items to mark.
Returns
Future<void>
markAsUnread
#Marks the given set of items as unread. Will optimistically update the feed.
Params
One or more feed items to mark.
Returns
Future<void>
markAsArchived
#Marks the given set of items as archived. Will optimistically update the feed.
Params
One or more feed items to mark.
Returns
Future<void>
markAsUnarchived
#Marks the given set of items as unarchived. Will optimistically update the feed.
Params
One or more feed items to mark.
Returns
Future<void>
markAsInteracted
#Marks the given set of items as interacted. Will optimistically update the feed.
Params
One or more feed items to mark.
Returns
Future<void>
markAllAsSeen
#Marks all items in the user's feed as seen. Will optimistically update the items currently in the feed.
Returns
Future<void>
markAllAsRead
#Marks all items in the user's feed as read. Will optimistically update the items currently in the feed.
Returns
Future<void>
markAllAsArchived
#Marks all items in the user's feed as archived. Will optimistically update the items currently in the feed.
Returns
Future<void>
MessagesClient
#Returned by knock.messages(). Reads and updates individual messages for the authenticated user. API failures throw KnockApiException.
get
#Params
The Knock message ID.
Returns
Future<KnockMessage>
updateStatus
#Sets engagement status on a message. The SDK method also accepts optional named request parameters.
Params
The Knock message ID.
Engagement status to set.
Returns
Future<KnockMessage>
removeStatus
#Params
The Knock message ID.
Status to remove from the message.
Returns
Future<KnockMessage>
batchUpdateStatuses
#Applies a batch status change. The SDK method also accepts optional named request parameters.
Params
Message IDs to update.
Batch status operation to apply.
Returns
Future<List<KnockMessage>>
bulkUpdateAllStatusesInChannel
#Runs a bulk status update for messages in a channel. See the SDK signature for the full set of named parameters (including optional request options).
Params
In-app channel ID for the bulk operation.
Status to apply in bulk.
Returns
Future<BulkOperation>
Convenience helpers
#markAsSeen, markAsRead, markAsArchived, markAsInteracted, markAsUnseen, markAsUnread, and markAsUnarchived each take a messageId and delegate to updateStatus or removeStatus.