Message Receipt Sync

Manage real-time message receipt synchronization infrastructure for accurate read and delivery tracking with optimized resource usage and lifecycle management.

Start receipt sync on a channel to receive real-time read and delivery status updates; stop it when the user leaves the channel to conserve real-time event topic quota.

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 channels

Implement basic receipt sync lifecycle management to track message status in real-time while users are actively viewing conversations.

Core Operations

Operation	Purpose	When to Use
startMessageReceiptSync	Begin tracking receipts for a channel	User enters chat screen
stopMessageReceiptSync	End receipt tracking	User leaves chat screen

Code Examples

Getting the subChannelId: Pass channel.defaultSubChannelId (iOS/TypeScript) or channel.getDefaultSubChannelId() (Android), retrieved from the channel object you already have. You do not need to query or manage SubChannel objects separately.

iOS

import AmitySDK

let subChannelRepository = AmitySubChannelRepository()

class ChatViewController: UIViewController {
    // Obtain from your channel object: channel.defaultSubChannelId
    private let subChannelId: String

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        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)
        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) {
        DispatchQueue.main.async {
            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

Lifecycle-Aware Activation

Optimize sync activation based on user context

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

Resource Optimization

Manage system resources efficiently

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

Error Recovery Patterns

Build resilient sync systems

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

Performance Monitoring

Track sync performance and reliability

Monitor 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

Efficient Lifecycle Management

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.

Error Handling Strategy

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.

Performance Optimization

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.

Related Features

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.