> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Live Objects & Collections

> Observe Social+ iOS SDK objects and collections with AmityObject, AmityCollection, notification tokens, and published snapshots.

The iOS SDK exposes live objects with `AmityObject<T>` and live collections with `AmityCollection<T>`. Both are `ObservableObject`s 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.

<CodeGroup>
  ```swift iOS theme={null}
  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
  }
  ```
</CodeGroup>

## Observe A Live Collection

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

<CodeGroup>
  ```swift iOS theme={null}
  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()
  }
  ```
</CodeGroup>

## Observe Published Snapshots

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

<CodeGroup>
  ```swift iOS theme={null}
  var cancellable: AnyCancellable?

  let livePost = postRepository.getPost(withId: postId)

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

      showSuccessMessage(post.postId)
  }
  ```
</CodeGroup>

## 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.

## Related Topics

<CardGroup cols={2}>
  <Card title="Post Retrieval" icon="newspaper" href="/social-plus-sdk/social/content-management/posts/retrieval/get-post">
    See post-specific iOS retrieval examples.
  </Card>

  <Card title="Realtime Events" icon="radio-tower" href="/social-plus-sdk/core-concepts/realtime-communication/realtime-events/overview">
    Learn how server events keep SDK state fresh.
  </Card>
</CardGroup>