User Inbox

The User Inbox feature allows your application to provide authenticated users with a personalized in-app message center, ensuring that notifications remain accessible even after they are dismissed from the system tray. By implementing a user-level inbox, you can significantly increase engagement by keeping all messages synchronized across multiple devices for the same user.

This module provides all the APIs required to parse, open, and manage user-specific inbox messages.

Requirements

Before getting started with this module, ensure that the following steps have been completed:

• You have successfully completed the Getting Started guide and included the ActitoUserInboxKit dependency
• You have implemented user authentication in your app and assigned a userId through the API-level user registration process

Overview

The User Inbox is tied to the authenticated user, rather than the device. This design ensures that all messages are synchronized across any devices where the same user is logged in.

The User Inbox must be retrieved from the Actito REST API by your backend. Because it contains user-specific data, access to the user inbox requires a server-side integration capable of performing authenticated requests using your Master Secret.

Your backend should handle the user’s authentication, securely query the User Inbox API endpoints, and expose the results to your app through your own protected API layer.

For details on the available endpoints and expected payloads, refer to the User Inbox API documentation.

Important

You should not use both the ActitoInboxKit and ActitoUserInboxKit modules within the same application. Each module provides its own independent implementation of the inbox feature — ActitoInboxKit manages messages at the device level, while ActitoUserInboxKit manages them at the user level. Using both simultaneously can cause synchronization issues, and unexpected behavior. Choose the module that best fits your use case and integrate only one inbox type per app.

If your application requires a simpler inbox mechanism, refer to the Inbox documentation for implementation details.

Parsing User Inbox items

Once your backend retrieves the User Inbox data from the Actito REST API, your application can easily parse that response using the SDK’s helper method. This allows your app to transform the raw JSON payload returned by your backend proxy into strongly typed inbox items managed by the SDK.

Use the parseResponse() method to convert the API response into an object composed of three properties:

• items - A list of ActitoUserInboxItem objects
• count - The total number of inbox items
• unread - The total number of unread messages

let data = /* The response Data retrieved from your backend */
let userInboxResponse = try Actito.shared.userInbox().parseResponse(data: data)

// Update your UI with the parsed items contained in response

This approach ensures that your app can display and manage user-level inbox messages securely, without directly calling the Actito REST API or exposing sensitive credentials.

note

The response provided to parseResponse() should match the JSON format returned by the User Inbox API endpoints, as retrieved by your backend. Make sure your backend acts as a proxy to the Actito REST API, handling authentication using your Master Secret and enforcing your own access controls.

Opening User Inbox items

Once you hold a reference to an inbox item, you can open it by invoking the following method:

let controller: UIViewController
let item: ActitoUserInboxItem

do {
    let notification = try await Actito.shared.userInbox().open(item)
    Actito.shared.pushUI().presentNotification(notification, in: controller)
} catch {
    // Handle error
}

Managing User Inbox items

You can manage the inbox contents through a variety of operations provided by the SDK.

Marking messages as read

To mark a specific message as read:

let item: ActitoUserInboxItem

do {
    try await Actito.shared.userInbox().markAsRead(item)
} catch {
    // Handle error
}

Removing messages

To remove a single message from the inbox:

let item: ActitoUserInboxItem

do {
    try await Actito.shared.userInbox().remove(item)
} catch {
    // Handle error
}