iOS Live Objects & Collections

The iOS SDK exposes live objects with AmityObject<T> and live collections with AmityCollection<T>. Both are ObservableObjects and expose published state for SwiftUI or Combine. Block observation is tied to AmityNotificationToken; retain the token while you need updates.

Platform Surface

Surface	Public API	Notes
Live object	`AmityObject<T>`	Exposes `snapshot`, `dataStatus`, `loadingStatus`, and `error`.
Live collection	`AmityCollection<T>`	Exposes `snapshots`, `dataStatus`, `loadingStatus`, and `error`.
Block observer	`observe { ... }`	Can emit multiple times while the token is retained.
One-time observer	`observeOnce { ... }`	Invalidates after one notification.
Cleanup	`AmityNotificationToken.invalidate()`	Releasing the token also ends observation.
Collection pagination	`nextPage()`, `previousPage()`, `resetPage()`	Check `hasNext` or `hasPrevious` before requesting more pages.

Parameters And State

Name	Applies to	Description
`AmityNotificationToken`	Object and collection observers	Retain it strongly for the lifetime of the observation. Invalidate it when the view no longer needs updates.
`snapshot`	`AmityObject<T>`	The current object snapshot, or `nil` if the object is not available.
`snapshots`	`AmityCollection<T>`	The current collection snapshot array.
`dataStatus`	Object and collection	`notExist`, `local`, `fresh`, or `error`. Use this when freshness matters.
`loadingStatus`	Object and collection	`notLoading`, `loading`, `loaded`, or `error`.
`hasNext` / `hasPrevious`	Collection	Indicates whether another page can be requested.

Observe A Live Object

This example observes one post. Keep token in view-controller, view-model, or view scope; invalidate it when the screen disappears.

let livePost = postRepository.getPost(withId: postId)

token = livePost.observe { observedPost, error in
    if let error = error {
        handleError(error)
        return
    }

    guard let post = observedPost.snapshot else {
        return
    }

    showSuccessMessage(post.postId)
}

func stopObservingPost() {
    token?.invalidate()
    token = nil
}

Observe A Live Collection

AmityCollection emits through snapshots. Use pagination methods on the collection instance, not array indexing helpers from older SDK generations.

let options = AmityPostQueryOptions(
    targetType: .community,
    targetId: communityId,
    sortBy: .lastCreated,
    deletedOption: .notDeleted,
    dataTypes: nil
)

let livePosts = postRepository.getPosts(options)

token = livePosts.observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let posts = collection.snapshots
    let isFresh = collection.dataStatus == .fresh

    showSuccessMessage(posts.count)
    showSuccessMessage(isFresh)
}

if livePosts.hasNext {
    livePosts.nextPage()
}

Observe Published Snapshots

AmityObject and AmityCollection are also observable from SwiftUI or Combine through published properties.

var cancellable: AnyCancellable?

let livePost = postRepository.getPost(withId: postId)

cancellable = livePost.$snapshot.sink { post in
    guard let post = post else {
        return
    }

    showSuccessMessage(post.postId)
}

Notes

Current iOS SDK live objects expose snapshot; live collections expose snapshots.
Do not use older object, object(at:), or count() patterns with current live objects and collections.
Observer callbacks are dispatched on the main thread.
If an object has local data, the SDK can emit local state before fresh server state.
For fresh-only flows, wait until dataStatus == .fresh, then invalidate the token if you do not need future updates.
For SwiftUI, pass the live object or collection directly into the view that observes it. Nested ObservableObject containers can hide changes from SwiftUI.

Post Retrieval

See post-specific iOS retrieval examples.

Realtime Events

Learn how server events keep SDK state fresh.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

iOS Live Objects & Collections

Platform Surface

Parameters And State

Observe A Live Object

Observe A Live Collection

Observe Published Snapshots

Notes

Post Retrieval

Realtime Events

​Platform Surface

​Parameters And State

​Observe A Live Object

​Observe A Live Collection

​Observe Published Snapshots

​Notes

​Related Topics

Post Retrieval

Realtime Events

Platform Surface

Parameters And State

Observe A Live Object

Observe A Live Collection

Observe Published Snapshots

Notes

Related Topics