iOS Live Objects/Collections

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

Local Cache

Data present in local storage

Server Queries

Data queried from the server

Real-time Events

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.

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.

Observer Implementation

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  
    }
}

Invalidate Token

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.

Basic Object Access

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
    }
}

Fresh Data Only

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()
    }
}

Direct Object Access

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.

Basic Collection Access

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
            }
        }
    }
}

Pagination

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

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.

Live Object - SwiftUI

struct LiveCommunityView: View {
    @ObservedObject var liveObject: AmityObject<AmityCommunity>
    
    var body: some View {
        VStack(alignment: .leading) {
            Text(liveObject.snapshot?.displayName ?? "")
        }
    }
}

Live Collection - SwiftUI

struct CommunityListView: View {
    @ObservedObject var communityCollection: AmityCollection<AmityCommunity>
    
    var body: some View {
        List(communityCollection.snapshots, id: \.communityId) { item in
            CommunityRowItemView(community: item)
        }
    }
}

Live Object - Combine

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"
    }
}

Live Collection - Combine

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

#1: LiveCollection is not updated when used from inside of another observable class

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

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

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.

#2: Published property still returns old values

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.

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

Token Management

Observer Selection

Data Status Verification

SwiftUI Integration

Combine Subscriptions

SwiftUI Documentation

Learn more about SwiftUI and ObservableObject

Combine Framework

Explore Apple’s reactive programming framework

Powered by

Getting Started

Fundamentals

Social

Chat

iOS Live Objects/Collections

How it Works

Data Sources

Local Cache

Server Queries

Real-time Events

AmityNotificationToken

AmityObject

Observer

Accessing Objects

AmityLoadingStatus

AmityCollection

Observer

Accessing Collection

SwiftUI Support

Access AmityObject & AmityCollection in SwiftUI views

FAQ’s

Best Practices

SwiftUI Documentation

Combine Framework

Powered by

Getting Started

Fundamentals

Social

Chat

​How it Works

​Data Sources

Local Cache

Server Queries

Real-time Events

​AmityNotificationToken

​AmityObject

​Observer

​Accessing Objects

​AmityLoadingStatus

​AmityCollection

​Observer

​Accessing Collection

​SwiftUI Support

​Access AmityObject & AmityCollection in SwiftUI views

​FAQ’s

​Best Practices

​Related Resources

SwiftUI Documentation

Combine Framework

How it Works

Data Sources

AmityNotificationToken

AmityObject

Observer

Accessing Objects

AmityLoadingStatus

AmityCollection

Observer

Accessing Collection

SwiftUI Support

Access AmityObject & AmityCollection in SwiftUI views

FAQ’s

Best Practices

Related Resources