Docs

In-App UI

Swift

SDK

Reference

iOS SDK API reference

The complete API reference for the Knock iOS SDK.

In this section, you'll find the documentation for the classes and methods available in the iOS SDK.

Knock

The top-level Knock class. This is a shared instance to interact with the SDK's API methods.

`Knock.shared.setup()`

Sets up the shared Knock instance. Make sure to call this as soon as you can. Preferably in your AppDelegate.

Params

publishableKeystring*

The public API key for the Knock environment.

pushChannelIdstring (optional)

The Knock APNs channel id that you plan to use within your app.

optionsKnock.KnockStartupOptions (optional)

Optional startup options to configure your Knock instance.

KnockAppDelegate

This class serves as an optional base class designed to streamline the integration of Knock into your application. By inheriting from KnockAppDelegate in your AppDelegate, you gain automatic handling of Push Notification registration and device token management, simplifying the initial setup process for Knock's functionalities.

The class also provides a set of open helper functions that are intended to facilitate the handling of different Push Notification events such as delivery in the foreground, taps, and dismissals. These helper methods offer a straightforward approach to customizing your app's response to notifications, ensuring that you can tailor the behavior to fit your specific needs.

Override any of the provided methods to achieve further customization, allowing you to control how your application processes and reacts to Push Notifications. Additionally, by leveraging this class, you ensure that your app adheres to best practices for managing device tokens and interacting with the notification system on iOS, enhancing the overall reliability and user experience of your app's notification features.

Key Features:

Automatic registration for remote notifications, ensuring your app is promptly set up to receive and handle Push Notifications.
Simplified device token management, with automatic storage of the device token, facilitating easier access and use in Push Notification payloads.
Customizable notification handling through open helper functions, allowing for bespoke responses to notification events such as foreground delivery, user taps, and dismissal actions.
Automatic message status updates, based on Push Notification interaction.

KnockInAppFeedViewModel

KnockInAppFeedViewModel manages the state and behavior of the in-app feed. It handles data fetching, user actions, state updates, and feed configuration.

This class is used with our KnockInAppFeedView component, but it can also be used independently if you would like to build your own UI.

Properties

feedKnock.Feed

Holds the current feed data.

currentTenantIdString?

Identifies the tenant associated with the current feed.

currentFilterInAppFeedFilter

The currently active filter for displaying feed items.

filterOptions[InAppFeedFilter]

Available filter options for customizing feed display.

topButtonActions[Knock.FeedTopActionButtonType]?

Actions available at the top of the feed interface, such as archiving or marking all as read. If set to nil, this view will be hidden.

feedClientOptionsKnock.FeedClientOptions

Configuration options for feed.

didTapFeedItemButtonPublisherPassthroughSubject<String, Never>()

Publisher for feed item button tap events.

didTapFeedItemRowPublisherPassthroughSubject<Knock.FeedItem, Never>()

Publisher for feed item row tap events.

Methods

connectFeedAndObserveNewMessages

Connects to the feed and subscribes to new message events.

refreshFeed(showLoadingIndicator: Bool)

Refreshes the feed using the original filter options.

fetchNewPageOfFeedItems

Loads additional feed items when the end of the list is reached.

isMoreContentAvailable

Determines if there are more pages of feed content that need to be fetched.

archiveItem(_ item: Knock.FeedItem)

Archives a specific feed item.

archiveAll(scope: Knock.FeedItemScope)

Archives all items within the specified scope.

markAllAsRead

Marks all items in the feed as read.

markAllAsSeen

Marks all unseen items as seen.

markAsInteracted

Marks message as interacted. Typically used when user taps on an item.

didSwipeRow(item: Knock.FeedItem, swipeAction: FeedNotificationRowSwipeAction)

Called when a user performs a horizontal swipe action on a row item.

topActionButtonTapped(action: Knock.FeedTopActionButtonType)

Called when a user taps on one of the action buttons at the top of the list.

Examples

Authentication

`Knock.shared.isAuthenticated()`

Convenience method to determine if a user is currently authenticated for the Knock instance.

Returns: Bool

Params

checkUserTokenBool

Whether Knock should also check to make sure user has a user token. Only required when using a Knock prod environment.

`Knock.shared.signIn()`

Sets the userId and userToken for the current Knock instance. If the device token and pushChannelId were set previously, this will also attempt to register the token to the user that is being signed in. This does not get the user from the database nor does it return the full User object. You should consider using this in areas where you update your local user's state.

Params

userIdString

The Knock user ID to make requests against.

userTokenString (optional)

A JWT that identifies the authenticated user, signed with the private key provided in the Knock dashboard. Required to secure your production environment. Learn more.

Example

`Knock.shared.signOut()`

Sets the userId and userToken for the current Knock instance back to nil. If the device token and pushChannelId were set previously, this will also attempt to unregister the token to the user that is being signed out so they don't receive pushes they shouldn't get. You should call this when your user signs out

Note: This will not clear the device token so that it can be accessed for the next user to login.

Example

User Management

`Knock.shared.getUserId()`

Fetch the userId that was set from the Knock.shared.signIn method.

Returns: String?

`Knock.shared.getUser()`

Returns the current user's profile stored in Knock. https://docs.knock.app/api-reference/users/get

Returns: Knock.User

`Knock.shared.updateUser()`

Updates the current user's profile in Knock. https://docs.knock.app/api-reference/users/get

Returns: Knock.User

Params

userKnock.User

The User object that you want to set for the current user.

Channels/Push Notifications

`Knock.shared.getUserChannelData()`

Returns the channel data for the current user on the channel specified with channelId.

Params

channelIdString

The channel ID to get channel data for

Returns: Knock.ChannelData

`Knock.shared.updateUserChannelData()`

Updates the channel data for the current user on the channel specified with channelId.

Params

channelIdString

The channel ID to update the channel data for

dataAnyEncodable

The data to update for the channel data

Returns: Knock.ChannelData

`Knock.shared.getApnsDeviceToken()`

Returns the apnsDeviceToken that was set from the Knock.shared.registerTokenForAPNS. If you use our KnockAppDelegate, the token registration will be handled for you automatically.

Returns String?

`Knock.shared.registerTokenForAPNS()`

Registers an Apple Push Notification Service token so that the device can receive remote push notifications. This is a convenience method that internally gets the channel data and searches for the token. If it exists, then it's already registered and it returns. If the data does not exists or the token is missing from the array, it's added. If the new token differs from the last token that was used on the device, the old token will be unregistered.

You can learn more about APNs here.

Params

channelIdString

The Knock APNs channel id to associate the device token to.

tokenString OR Data

the APNs device token.

Returns: Knock.ChannelData

`Knock.shared.unregisterTokenForAPNS()`

Unregisters the current deviceId associated to the user so that the device will no longer receive remote push notifications for the provided channelId.

Params

channelIdString

The Knock APNs channel id to associate the device token to.

tokenString OR Data

the APNs device token.

Returns: Knock.ChannelData

`Knock.shared.getNotificationPermissionStatus()`

Convenience method to determine whether or not the user is allowing Push Notifications for the app.

Returns: UNAuthorizationStatus

`Knock.shared.requestNotificationPermission()`

Requests push notification permissions to the user.

Params

optionsUNAuthorizationOptions

The type of push notification permissions you want. Defaults to `[.sound, .badge, .alert]`

Returns: UNAuthorizationStatus

`Knock.shared.requestAndRegisterForPushNotifications()`

Convenience method to request Push Notification permissions for the app, and then, if successful, registerForRemoteNotifications in order to get a device token.

Preferences

`Knock.shared.getAllUserPreferences()`

Returns all of the preference sets for the current user.

Returns: Knock.PreferenceSet

`Knock.shared.getUserPreferences()`

Returns a single preference set for the current user, specified by the preferenceId. For the default preference set, set the preferenceId to be default.

Params

preferenceIdString

The ID of the preference set to retrieve

Returns: Knock.PreferenceSet

`Knock.shared.setUserPreferences()`

Updates the preference set specified by the preferenceId with the new preferenceSet.

Params

preferenceIdString

The ID of the preference set

preferenceSetKnock.PreferenceSet

The preferences to update for the preference set

Returns: Knock.PreferenceSet

Messages

`Knock.shared.getMessage()`

Returns information about a single message specified by the messageId. https://docs.knock.app/api-reference/messages

Params

messageIdString

The ID of the message to retrieve

Returns Knock.KnockMessage

`Knock.shared.updateMessageStatus()`

Updates the status of a single message specified by the message or messageId. https://docs.knock.app/api-reference/messages

Params

messageIdString

The ID of the message to update

messageKnockMessage

A Knock message to update

statusKnockMessageStatusUpdateType

The status to set on the message

Returns Knock.KnockMessage

`Knock.shared.deleteMessageStatus()`

Un-marks the given status on a message specified by the message or messageId, recording an event in the process. https://docs.knock.app/api-reference/messages

Params

messageIdString

The ID of the message to update

messageKnockMessage

A Knock message to update

statusKnockMessageStatusUpdateType

The status to set on the message

Returns Knock.KnockMessage

`batchUpdateStatuses`

Updates up to 50 messages with the given status in a single request specified by messageIds or messages. https://docs.knock.app/api-reference/messages

Params

messageIds[String]

A list of message IDs

message[Knock.KnockMessage]

A list of messages

statusKnock.KnockMessageStatusBatchUpdateType

The status to set on the messages

Returns [Knock.KnockMessage]

FeedManager

`Knock.FeedManager.init()`

Creates a new instance of a FeedManager for interacting with a user's in-app notification feed.

Params

feedIdString

The UUID of your Knock in-app feed channel ID.

optionsKnock.FeedClientOptions

Feed options to apply as defaults.

Example

`Knock.shared.feedManager.connectToFeed()`

Connects the feed instance to the real-time socket so that any new items published to the feed are received over the websocket.

Params

optionsKnock.FeedClientOptions (optional)

Feed options to apply. Will override any options specified in the FeedManager constructor.

`Knock.shared.feedManager.disconnectFromFeed()`

Disconnects a connected real-time instance.

`Knock.shared.feedManager.on()`

Binds an event listener for incoming web socket events. Must have called connectToFeed first.

eventNameString

The event name to listen for. Currently only `new-message` is supported.

Example

`Knock.shared.feedManager.getUserFeedContent()`

Retrieves the user's feed content for the feed. Can be scoped by passing options, which also allows for paginating the contents of the feed using the before and after cursors.

Params

optionsKnock.FeedClientOptions*

Feed options to apply to the fetch. Will override any options specified in the FeedManager constructor.

Returns Knock.Feed

Example

`makeBulkStatusUpdate`

Updates all of the items within the feed with the given status. Can be passed options to scope the request further. Note: this method returns a BulkUpdate via the Knock API, which is an async operation.

Params

typeKnock.BulkChannelMessageStatusUpdateType

The type of update to make in bulk.

optionsKnock.FeedClientOptions

Feed options to scope the bulk update by.

Returns Knock.BulkOperation

`Knock.FeedClientOptions`

Used to scope a feed request.

Params

beforeString

A cursor to return records before, used for pagination

afterString

A cursor to return records after, used for pagination

page_sizeInt

The maximum number of items to return per page

statusFeedItemScope

One of either `all`, `unread`, `read`, `unseen`, `seen`

sourceString

Scope to a single workflow source for the feed items

tenantString

Scope to a single tenant

has_tenantBool

Scope to whether the feed items have or do not have a tenant set

archivedFeedItemArchivedScope

Scope by archive status. One of `include`, `exclude`, or `only`

trigger_data[String: AnyCodable]

Match a set of trigger data on the generated feed messages