@amityco/social-plus-vise 0.14.28 → 1.0.0

package/docs-cache/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/ios.mdx

@@ -0,0 +1,452 @@
+# iOS Live Objects/Collections
+
+> Live Objects are supported in the iOS SDK with AmityObject and AmityCollection for real-time data synchronization
+
+In iOS social.plus SDK, we have two core concepts for real-time data synchronization: **Live Object** and **Live Collection**. 
+
+Live Object is represented by `AmityObject` instance for observing changes in a single object whereas Live Collection is represented by `AmityCollection` instance for observing changes in a list of objects.
+
+These generic classes encapsulate any other object and notify observers whenever any property of the encapsulated object changes.
+
+Examples: `AmityObject<AmityPost>`, `AmityCollection<AmityMessage>`, or `AmityObject<AmityChannel>`.
+
+## How it Works
+
+SDK handles lots of data received from various sources. Data can be present in local cache. It might also be queried from the server or received from some real-time events. What this means is that same data is constantly updating. The data that you are accessing at the moment can get updated by other sources and becomes out of sync.
+
+Live Object and Live Collection help in syncing these constantly updating data, so you will always get the most recent one. Whenever the data gets updated, you will be notified through helper methods in live objects and live collection classes.
+
+New data gets automatically collected every time when there is an updation and the user need not refresh to get the recent data.
+
+### Data Sources
+
+    Data present in local storage
+    Data queried from the server
+    Data received from real-time events
+
+Both `AmityObject` and `AmityCollection` provide methods for observing changes in objects. The life cycle of observation is tied to its token. As soon as the token is invalidated or deallocated, observation ends.
+
+## AmityNotificationToken
+
+`AmityNotificationToken` is a simple object which keeps track of what is being observed. Each Live Object or Live Collection observation is tied to its respective token. As soon as the token is invalidated or deallocated, observation ends. The token is declared within the scope of the class.
+
+```swift
+class MyClass {
+    var token: AmityNotificationToken?
+
+    func doSomething() {
+        // AmityNotification is alive in MyClass scope
+    }
+}
+```
+
+The token is used in combination with AmityObject or AmityCollection. We will explore it more in AmityObject and AmityCollection concepts.
+
+## AmityObject
+
+`AmityObject` is a generic class that keeps track of a single object. It is a live object. In iOS AmitySDK, any object which is encapsulated by AmityObject is a live object.
+
+Examples: `AmityObject<AmityMessage>`, `AmityObject<AmityChannel>`
+
+AmityObject class exposes the following methods: `observe` and `observeOnce`. These methods help observe a live object. Whenever any property for the observed object changes, the observer is triggered.
+
+Please make sure that the user is logged in before observing AmityObject. You can also refer to the session state section for more details.
+
+### Observer
+
+`observe` method can be triggered multiple times throughout the lifetime of the application as long as its associated AmityNotificationToken is retained in memory. `observeOnce` method, on the other hand, can only be triggered once.
+
+Both `observe` and `observeOnce` methods will be called from the main thread so you can perform any UI update-related tasks from within the observed block itself.
+
+If the requested object data is stored locally on the device, the block will be called immediately with the local version of the data. This can be verified through the dataStatus property of AmityObject.
+
+In parallel, a request is made to the server to fetch the latest version of the data. Once the data is returned, the observed block will be triggered again.
+
+Any future changes to that data from any sources can trigger an observer.
+
+**Lifecycle**: The life cycle of the observer is tied to its token. If the token is not retained, then the observer can get deallocated at any time and will not be called.
+
+```swift
+var token1: AmityNotificationToken?
+var token2: AmityNotificationToken?
+
+func example() {
+    let liveObject: AmityObject<AmityChannel> = channelRepository.getChannel("1234")
+
+    // observe block
+    token1 = liveObject.observe { liveObject, error in
+        // Handle updates
+    }
+
+    // observeOnce block
+    token2 = liveObject.observeOnce { liveObject, error in
+        // Handle single update  
+    }
+}
+```
+
+```swift
+// Manually invalidate the token tied to observer
+token1?.invalidate()
+
+// Alternatively, you can invalidate a token by deallocate it
+token1 = nil
+```
+
+### Accessing Objects
+
+There are multiple ways to access data from AmityObject. AmityObject exposes the following properties:
+
+- **dataStatus**: Indicates whether the data is fresh or local
+- **loadingStatus**: Indicates if the data is being loaded from server or not  
+- **object**: The actual object that is being tracked or encapsulated by this AmityObject
+
+Once you add an observer block, you can access both local or fresh data as shown below.
+
+```swift
+var token: AmityNotificationToken?
+
+func example() {
+    let liveObject: AmityObject<AmityChannel> = channelRepository.getChannel("1234")
+
+    token = liveObject.observe { liveObject, error in
+        // This helps us to determine if the data is fresh or local
+        let dataStatus: AmityDataStatus = liveObject.dataStatus
+
+        // Here we access channel from this live object. This gives us with `AmityChannel` object.
+        guard let channel = liveObject.object else {
+            return
+        }
+
+        // Access channel object property as normal
+        let channelId = channel.channelId
+        let channelDisplayName = channel.displayName
+    }
+}
+```
+
+```swift
+var token: AmityNotificationToken?
+
+func example() {
+    let liveObject = channelRepository.getChannel("1234")
+
+    token = liveObject.observe { [weak self] liveObject, error in
+        // We want to get fresh data only.
+        guard liveObject.dataStatus == .fresh else {
+            return
+        }
+
+        guard let channel = liveObject.object else {
+            return
+        }
+
+        // Access channel object property as normal
+        let channelId = channel.channelId
+        let channelDisplayName = channel.displayName
+
+        // We don't want to observe future changes. So we stop observing by invaliding token
+        self?.token?.invalidate()
+    }
+}
+```
+
+```swift
+let liveObject: AmityObject<AmityChannel> = channelRepository.getChannel("1234")
+
+// If local data is present, you can also access it as...
+if let channel = liveObject.object {
+    // Access channel properties
+}
+```
+
+    While this is possible, we recommend accessing object from within the `observe` or `observeOnce` block depending on your requirement.
+
+For `observeOnce` method, if data is present locally, this observer will be triggered only once with that local data. If you are looking for fresh data, use the `observe` block and invalidate the token once fresh data is received as shown above.
+
+### AmityLoadingStatus
+
+AmityObject can be tracked for their loading status by accessing the `loadingStatus` property, which is of type `AmityLoadingStatus` and it can have one of four possible values.
+
+- **0 (notLoading)**: Indicates that the data is already fresh locally and does not need to be loaded.
+- **1 (loading)**: Indicates that the client is currently loading the data from the server.
+- **2 (loaded)**: Indicates that the client has successfully loaded fresh data from the server and is up to date.
+- **3 (error)**: Indicates that the data is unable to load due from a specific error.
+
+## AmityCollection
+
+`AmityCollection` is a generic class that keeps track of a collection of objects. It is a live collection. In iOS SDK, any object which is encapsulated by AmityCollection class is a live collection.
+
+Examples: `AmityCollection<AmityMessage>`, `AmityCollection<AmityChannel>`
+
+AmityCollection exposes these methods: `observe` and `observeOnce`. These methods help to observe a live collection. Whenever any property for any object within the collection changes, the observer is triggered.
+
+Please make sure that the user is logged in before observing AmityCollection. You can also refer to session state section for more details.
+
+### Observer
+
+`observe` method can get triggered multiple times throughout the lifetime of the application as long as it's associated AmityNotificationToken is retained in memory. `observeOnce`, on the other hand, can only be triggered once.
+
+Both `observe` and `observeOnce` method will be called from the main thread so you can perform any UI update related task within the observe block itself.
+
+If the requested data collection is stored locally on the device, the block will be called immediately with the local version of the data. This can be verified through the dataStatus property of AmityCollection.
+
+In parallel, a request is made to the server to fetch the latest version of the data. Once the data is returned, the observe block will be triggered again.
+
+Any future changes to the data from any sources can trigger observer.
+
+**Lifecycle**: The life cycle of the observer for AmityCollection is also tied to its token. If the token is not retained, the observer can get deallocated at any time and will not be called.
+
+### Accessing Collection
+
+Unlike most databases, AmityCollection does not return all data in an array. Instead, data is fetched one by one using the `objectAtIndex:` method. This allows the framework to store most of the actual result on disk, and load them in memory only when necessary.
+
+AmityCollection also exposes a `count` property which determines the number of objects present in a collection.
+
+With these two public interfaces, you can create a robust list UI for your use case. Similar to AmityObject, AmityCollection also exposes `dataStatus` and `loadingStatus` property.
+
+```swift
+var token: AmityNotificationToken?
+
+func example() {
+    // Fetching live collection of channels...
+    let query = AmityChannelQuery()
+    query.types = [AmityChannelQueryType.live]
+    query.includeDeleted = false
+    let liveCollection = channelRepository.getChannels(with: query)
+
+    // observe block
+    token = liveCollection.observe { liveCollection, change, error in
+        // Determine if data is local or fresh
+        let dataStatus: AmityDataStatus = liveCollection.dataStatus
+
+        // Using the count property we loop through collection data
+        for i in 0..<liveCollection.count() {
+            // We access individual data
+            if let channel = liveCollection.object(at: i) {
+                // Access channel object property as normal object i.e AmityChannel
+                let channelId = channel.channelId
+                let channelDisplayName = channel.displayName
+            }
+        }
+    }
+}
+```
+
+```swift
+// AmityCollection returns a maximum of 20 items per page
+// For example, when user scrolls to the bottom of the list; fetch next page
+if liveCollection.hasNext {
+    liveCollection.nextPage()
+}
+
+// If you want to shrink the collection to the original first page
+liveCollection.resetPage()
+```
+
+    AmityCollection has `nextPage()` and `previousPage()` method to fetch more data. It also exposes `hasNext` and `hasPrevious` property to check if next page or previous page is present.
+
+One typical usage of Live Collection is in UITableView. Below is an example of fetching a collection and displaying it in a tableview.
+
+```swift
+class ExampleViewController: UITableViewController {
+
+    var liveCollection: AmityCollection<AmityChannel>!
+    var token: AmityNotificationToken?
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        tableView.register(UITableViewCell.self, forCellReuseIdentifier: "cell")
+        setupDataSource()
+    }
+
+    func setupDataSource() {
+        let query = AmityChannelQuery()
+        query.types = [AmityChannelQueryType.live]
+        query.includeDeleted = false
+        // Get live collection
+        liveCollection = App.shared.channelRepository.getChannels(with: query)
+        // Observe live collection
+        token = liveCollection.observe { [weak self] liveCollection, changes, error in
+            self?.tableView.reloadData()
+        }
+    }
+
+    override func numberOfSections(in tableView: UITableView) -> Int {
+        1
+    }
+
+    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
+        Int(liveCollection.count())
+    }
+
+    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
+        let cell = tableView.dequeueReusableCell(withIdentifier: "cell")!
+        // build your cell here with AmityChannel object.
+        if let channel = liveCollection.object(at: indexPath.row) {
+            cell.textLabel?.text = channel.displayName
+        }
+        return cell
+    }
+}
+```
+
+## SwiftUI Support
+
+AmityObject and AmityCollection are now observable object with its properties marked with @Published annotation. Now you can use live object & live collection directly within your SwiftUI views.
+
+**Live Object @Published**: dataStatus ✅, loadingStatus ✅, snapshot ✅, error ✅, object ❌
+
+**Live Collection @Published**: dataStatus ✅, loadingStatus ✅, snapshot ✅, error ✅
+
+### Access AmityObject & AmityCollection in SwiftUI views
+
+Since AmityObject & AmityCollection are observable object, it can be used as an ObservedObject within SwiftUI views. We recommend to create small view which observes AmityCollection & AmityObject as ObservedObject as shown in code sample below.
+
+```swift
+struct LiveCommunityView: View {
+    @ObservedObject var liveObject: AmityObject<AmityCommunity>
+
+    var body: some View {
+        VStack(alignment: .leading) {
+            Text(liveObject.snapshot?.displayName ?? "")
+        }
+    }
+}
+```
+
+```swift
+struct CommunityListView: View {
+    @ObservedObject var communityCollection: AmityCollection<AmityCommunity>
+
+    var body: some View {
+        List(communityCollection.snapshots, id: \.communityId) { item in
+            CommunityRowItemView(community: item)
+        }
+    }
+}
+```
+
+```swift
+func observeChangesInLiveObject() {
+    var cancellable: AnyCancellable?
+
+    var liveObject: AmityObject<AmityCommunity> = communityRepository.getCommunity(withId: "abcd")
+    cancellable = liveObject.$snapshot.sink { community in
+        // Observe changes to AmityCommunity
+        let displayName = community?.displayName ?? "Unknown"
+    }
+}
+```
+
+```swift
+func observeChangesInLiveCollection() {
+    var cancellable1: AnyCancellable?
+    var cancellable2: AnyCancellable?
+
+    var liveCollection: AmityCollection<AmityCommunity> = communityRepository.getTrendingCommunities()
+    cancellable1 = liveCollection.$snapshots.sink { communities in
+        // Observe changes to [AmityCommunity]
+        let communitiesCount = communities.count
+    }
+
+    cancellable2 = liveCollection.$error.sink { communities in
+        // Some error occurred
+    }
+}
+```
+
+Since the properties are published, If you are using Combine Framework, you can also subscribe to changes on those properties.
+
+States of live collection & live object are published before snapshots so that you can compare the state from within subscriber.
+
+## FAQ's
+
+    AmityCollection & AmityObject is an ObservableObject. When this live collection or live object is embedded inside another Observable Object, SwiftUI cannot observe the changes in snapshot occurring within Live collection & Live object. As a result, there might be a situation where you see your view is not getting updated even when snapshot(s) are updated. This is a common problem with nested observable object in SwiftUI.
+
+    **❌ Error: View where list does not update**
+```swift
+class MyViewModel: ObservableObject {
+    var commentRepo: AmityCommentRepository!
+    @Published var liveCollection: AmityCollection<AmityComment>!
+
+    init() {
+        let commentQuery = AmityCommentQueryOptions(referenceId: "", referenceType: .post, filterByParentId: false, orderBy: .descending, includeDeleted: false)
+        liveCollection = commentRepo.getComments(with: commentQuery)
+    }
+}
+
+struct MyView1: View {
+    @StateObject var viewModel = MyViewModel()
+
+    var body: some View {
+        // List does not update
+        List(viewModel.liveCollection.snapshots, id: \.commentId) { item in
+            Text("Comment: \(item.commentId)")
+        }
+    }
+}
+```
+
+    **✅ Success: View where list updates successfully**
+```swift
+struct MyView2: View {
+    @StateObject var viewModel = MyViewModel()
+
+    var body: some View {
+        // List updates
+        CommentListView(commentCollection: viewModel.liveCollection)
+    }
+}
+
+struct CommentListView: View {
+    @ObservedObject var commentCollection: AmityCollection<AmityComment>
+
+    var body: some View {
+        List(commentCollection.snapshots, id: \.commentId) { item in
+            Text("Comment: \(item.commentId)")
+        }
+    }
+}
+```
+
+    To solve this issue we recommend to create a specific view which observes AmityCollection & AmityObject as @ObservedObject as shown in code example.
+
+    Since the properties of AmityCollection & AmityObject are marked with @Published annotation, the publishing of changes occurs in the property's willSet block, meaning that any subscribers will receive an update before the property is changed. This behaviour can easily lead to unexpected bugs.
+
+```swift
+var cancellable: AnyCancellable?
+func publishedPropertiesBugs() {
+    var liveObject: AmityObject<AmityComment>!
+
+    cancellable = liveObject.$snapshot.sink(receiveValue: { newComment in
+
+        var snapshot: AmityComment?
+
+        // Incorrect:
+        snapshot = liveObject.snapshot
+
+        // Correct:
+        snapshot = newComment
+    })
+}
+```
+
+## Best Practices
+
+    **Proper Retention**: Always retain `AmityNotificationToken` in appropriate scope to maintain observations. Store tokens as instance variables to prevent deallocation.
+
+    **Choose Appropriate Method**: Use `observe` for ongoing updates throughout the application lifecycle, and `observeOnce` for single-time data retrieval.
+
+    **Check Freshness**: Always verify `dataStatus` to determine if data is fresh or local before processing, especially when you need the most recent data.
+
+    **Dedicated Views**: Create dedicated views that observe live objects as `@ObservedObject` to avoid nested ObservableObject issues in SwiftUI.
+
+    **Parameter Usage**: When using Combine framework, always use parameter values in sink closures rather than accessing properties directly to avoid timing issues.
+
+## Related Resources
+
+    Learn more about SwiftUI and ObservableObject
+    Explore Apple's reactive programming framework
+
+---

package/docs-cache/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview.mdx

@@ -0,0 +1,133 @@
+# Live Objects & Collections
+
+> Learn about observable data holders that provide real-time updates from local cache and server events
+
+Live Objects and Live Collections are observable data holders. The observer gets updated when there is a change of data in the local cache.
+
+There are two main sources that can make changes to the object and collection:
+
+1. **When data get updated by an action from the current device**
+2. **Real-time events of the subscribed data from the server**
+
+Refer to the platform-specific subpages in this section for an in-depth explanation of how your SDK handles live objects and live collections.
+
+By subscribing to a specific topic in the Real-time event system, users can ensure that they are receiving the most up-to-date information and notifications related to the observed object across devices.
+
+## Data Sources
+
+    Updates from user interactions within your current device
+    Live changes from subscribed objects on the server
+
+## Live Object
+
+Live Object allows users to observe the states of a single object within the app, such as a post, message, or channel. With Live Object, users can automatically receive notifications of any data updates related to the observed object, whether from the network or locally.
+
+### Key Features
+
+    Live Object API is designed around the observer design pattern, allowing users to subscribe to an object, receive notifications of any data updates, and unsubscribe when necessary.
+
+    Live Object also provides additional states, such as `isLoading` and `error`, which can help understand the status of the observed object and any potential issues that may arise.
+
+    These updates are delivered via Snapshot, a captured state that is frozen and cannot be changed. Users can own and access these snapshots to stay up-to-date with the latest data within the app.
+
+    It's worth noting that while data updates may occur internally within the SDK, these updates will not affect previous snapshots. The only way for users to see the latest data is by getting new snapshots delivered via Live Object updates.
+
+### Use Cases
+
+Live Object is ideal for monitoring individual entities such as:
+
+- **Posts**: Track likes, comments, and content updates
+- **Messages**: Monitor delivery status, read receipts, and reactions  
+- **Channels**: Observe member count changes and channel metadata
+- **User Profiles**: Watch status updates, avatar changes, and online presence
+
+### Live Object Architecture
+
+```mermaid
+graph TD
+    A[Your App UI] --> B[Live Object Observer]
+    B --> C[Snapshot Data]
+    C --> D[Local Cache]
+    C --> E[Real-time Events]
+    C --> F[Server Updates]
+
+    D --> G[User Actions]
+    E --> H[Other Users]
+    F --> I[Background Sync]
+```
+
+## Live Collection
+
+Live Collection allows users to observe changes to an entire collection of data within their app in real-time. Live Collection works similarly to Live Object, with the main difference being that Live Collection notifies changes related to the entire collection rather than just a single object.
+
+### How It Works
+
+To use Live Collection, users can observe changes in a specific collection within the SDK. The collection handler then receives a snapshot of changes since the last result, which includes three possible events:
+
+    The indices of the objects that were deleted
+    The indices of the objects that were inserted
+    The indices of the objects that were modified
+
+### Change Detection
+
+Live Collections provide granular change notifications instead of replacing entire datasets:
+
+| Change Type | Description | Benefit |
+|-------------|-------------|---------|
+| **Insertions** | New items added to collection | Efficient UI updates for new content |
+| **Deletions** | Items removed from collection | Smooth removal animations |
+| **Modifications** | Existing items updated | Targeted updates without full refresh |
+
+### Use Cases
+
+By subscribing to changes on a specific collection using Live Collection, users can stay up-to-date with the latest changes and updates to important collections within the app. This can be particularly helpful for:
+
+- **Managing large amounts of data**: Efficiently handle extensive datasets without performance impact
+- **Monitoring frequently updated collections**: Track changes to dynamic content like messages or posts
+- **Real-time social feeds**: Display new posts, comments, and reactions as they happen
+- **Chat message lists**: Show new messages instantly with typing indicators
+- **Member lists**: Track community or channel membership changes
+
+### Live Collection Architecture
+
+```mermaid
+graph TD
+    A[Collection UI] --> B[Live Collection Observer]
+    B --> C[Change Snapshot]
+    C --> D[Insertions]
+    C --> E[Deletions] 
+    C --> F[Modifications]
+
+    G[Data Sources] --> B
+    H[Paginated API] --> G
+    I[Real-time Events] --> G
+    J[Local Cache] --> G
+    K[User Actions] --> G
+```
+\
+## Best Practices
+
+    **Proper Cleanup**: Always unsubscribe from observers to prevent memory leaks when components unmount or views disappear.
+
+    **Efficient Updates**: Use collection change indices for targeted UI updates instead of full re-renders. Only update the specific items that changed.
+
+    **Graceful Degradation**: Handle network errors and loading states appropriately using the built-in `isLoading` and `error` states.
+
+    **Topic Management**: Subscribe to relevant real-time topics for automatic updates. Ensure proper cleanup when no longer needed.
+
+## Platform Implementation
+
+Each platform has its own specific implementation patterns for Live Objects and Collections:
+
+    Learn iOS-specific patterns for observers and delegates
+    Discover Android LiveData and RxJava integration
+    Understand Dart streams and reactive widgets
+
+## Related Concepts
+
+    Learn how Live Objects connect to real-time updates
+    Explore event channels powering live updates
+
+**Development Tip**: Use platform-specific debugging tools to monitor subscription status and data flow in your Live Objects and Collections during development.
+
+---