> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-feat-user-history-moderation-detail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Live Objects & Collections

> Observe social.plus 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.