Skip to main content
Key Benefit: Enable real-time read and delivery receipt tracking with efficient resource management, ensuring accurate message status updates while optimizing performance and network usage.

​
Feature Overview

Message Receipt Sync provides the essential infrastructure for real-time tracking of message read and delivery status within channels. This system ensures that read counts, delivery confirmations, and user interaction data remain current and accurate across your chat application.

Real-time Synchronization

Live receipt tracking
  • Start/stop receipt sync control
  • Automatic status updates
  • Real-time event processing
  • Connection state management

Resource Optimization

Efficient system management
  • Lifecycle-aware activation
  • Automatic cleanup processes
  • Network resource conservation
  • Performance optimization
Resource Consumption: Receipt sync consumes real-time event topics and should only be active when users are viewing channels. Always stop sync when leaving channels to optimize resource usage and prevent quota limits.

​
Implementation Guide

  • Basic Receipt Sync
Start and stop receipt synchronization for channelsImplement basic receipt sync lifecycle management to track message status in real-time while users are actively viewing conversations.

​
Core Operations

OperationPurposeWhen to Use
startMessageReceiptSyncBegin tracking receipts for a channelUser enters chat screen
stopMessageReceiptSyncEnd receipt trackingUser leaves chat screen

​
Code Examples

import AmitySDK

let subChannelRepository = AmitySubChannelRepository(client: client)

class ChatViewController: UIViewController {
    private let subChannelId: String
    
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        
        // Start receipt sync when user enters chat
        Task {
            do {
                try await subChannelRepository.startMessageReceiptSync(subChannelId: subChannelId)
                print("Receipt sync started for channel: \(subChannelId)")
            } catch {
                print("Failed to start receipt sync: \(error)")
                handleReceiptSyncError(error)
            }
        }
    }
    
    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        
        // Stop receipt sync when user leaves chat
        Task {
            do {
                try await subChannelRepository.stopMessageReceiptSync(subChannelId: subChannelId)
                print("Receipt sync stopped for channel: \(subChannelId)")
            } catch {
                print("Failed to stop receipt sync: \(error)")
            }
        }
    }
    
    private func handleReceiptSyncError(_ error: Error) {
        // Graceful error handling
        DispatchQueue.main.async {
            // Show user-friendly error message
            self.showErrorAlert("Unable to sync message status. Some features may be limited.")
        }
    }
}
Automatic Cleanup: Receipt sync automatically stops after one minute of network disconnection. When connection is re-established, sync resumes automatically.

​
Sync Management Strategies

Optimize sync activation based on user contextImplement smart sync activation patterns that respond to user behavior and app lifecycle:
  • View-Based Activation: Start sync only when users enter chat screens
  • Background Handling: Pause sync when app goes to background to conserve resources
  • Network Awareness: Automatically pause/resume sync based on connection status
  • Tab Management: Sync only the active channel when using tabbed interfaces
Lifecycle-aware activation ensures optimal resource usage while maintaining accurate status tracking.
Manage system resources efficientlyBalance functionality with performance through strategic resource management:
  • Concurrent Sync Limits: Monitor and limit the number of simultaneous syncs
  • Priority-Based Sync: Prioritize sync for active or high-priority channels
  • Graceful Degradation: Reduce sync frequency under resource constraints
  • Memory Management: Properly clean up sync resources when no longer needed
Effective resource optimization prevents performance degradation and quota exhaustion.
Build resilient sync systemsImplement robust error handling for reliable sync operation:
  • Exponential Backoff: Use progressive delays for retry attempts
  • Error Categorization: Handle different error types with appropriate strategies
  • Circuit Breaker: Temporarily disable sync for repeatedly failing channels
  • Fallback Mechanisms: Provide alternative status tracking when sync fails
Well-designed error recovery ensures consistent user experience even during network issues.
Track sync performance and reliabilityMonitor sync operations to maintain optimal performance:
  • Success Rate Tracking: Monitor sync start/stop success rates
  • Latency Measurement: Track sync activation and response times
  • Resource Usage: Monitor memory and network consumption
  • Error Pattern Analysis: Identify and address common failure scenarios
Comprehensive monitoring enables proactive optimization and issue resolution.

​
Best Practices

Implement optimal sync lifecycle patterns
  • Start sync immediately when users enter active chat views
  • Stop sync promptly when users leave chat screens to conserve resources
  • Use app lifecycle observers to handle background/foreground transitions
  • Implement proper cleanup in component destructors and view controllers
Proper lifecycle management prevents resource leaks and ensures optimal performance.
Build resilient sync systems
  • Implement exponential backoff for transient errors
  • Categorize errors to determine appropriate retry strategies
  • Provide user-friendly error messages without exposing technical details
  • Log errors with sufficient context for debugging and monitoring
Robust error handling maintains user trust and enables effective troubleshooting.
Optimize sync performance for scale
  • Monitor active sync count to prevent quota exhaustion
  • Use efficient data structures for tracking sync state
  • Implement lazy sync activation for better startup performance
  • Consider sync priority based on channel importance and user activity
Performance optimization ensures smooth operation even with many active channels.

Channel Unread Count

Unread Tracking Monitor channel-level unread counts with real-time updates

Message Read Status

Read Tracking Mark individual messages as read to update counts

Message Delivery Status

Delivery Tracking Track message delivery and user interaction
Implementation Strategy: Start with basic lifecycle management (start sync on enter, stop on exit), then add advanced error handling and monitoring. Focus on resource efficiency to prevent quota issues and ensure scalable operation.