Query Notification Tray Item

Flexible Filtering

Query notifications with advanced filtering options for targeted retrieval

Pagination Support

Efficiently handle large notification sets with built-in pagination

Real-time Updates

Live collection updates for dynamic notification experiences

Multi-platform SDK

Consistent querying across iOS, Android, and Web platforms

Overview

The Query Notification Tray Item feature allows you to retrieve and filter notification tray items with powerful querying capabilities. This functionality is essential for building dynamic notification interfaces that can display relevant notifications based on user preferences, seen status, and notification types.

Architecture Overview

Key Features

Advanced Filtering Options

Live Collection Features

Performance Optimizations

Query Configuration

Basic Query Options

Filter Parameters

Advanced Options

Pagination Implementation

class NotificationListViewController: UIViewController, UITableViewDataSource {
    private var notifications: [AmityNotificationTrayItem] = []
    private var liveCollection: AmityCollection<AmityNotificationTrayItem>?
    private var isLoading = false
    
    func loadMoreIfNeeded(at indexPath: IndexPath) {
        guard !isLoading,
              indexPath.row >= notifications.count - 5, // Load more when 5 items from end
              liveCollection?.hasNext == true else { return }
        
        isLoading = true
        liveCollection?.nextPage { [weak self] result in
            DispatchQueue.main.async {
                self?.isLoading = false
                switch result {
                case .success:
                    // Collection will update automatically through observer
                    break
                case .failure(let error):
                    self?.handlePaginationError(error)
                }
            }
        }
    }
    
    // MARK: - UITableViewDataSource
    func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        return notifications.count + (liveCollection?.hasNext == true ? 1 : 0) // +1 for loading cell
    }
    
    func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        if indexPath.row >= notifications.count {
            // Return loading cell
            return tableView.dequeueReusableCell(withIdentifier: "LoadingCell", for: indexPath)
        }
        
        let cell = tableView.dequeueReusableCell(withIdentifier: "NotificationCell", for: indexPath)
        configureCell(cell, with: notifications[indexPath.row])
        return cell
    }
}

Best Practices

Query Optimization

Efficient Querying Strategies

Reasonable Page Sizes

Use page sizes between 20-50 items to balance performance and user experience

Targeted Filtering

Apply specific filters to reduce data transfer and improve response times

Smart Caching

Leverage built-in caching mechanisms to minimize unnecessary network requests

Progressive Loading

Implement progressive loading for better perceived performance

Performance Guidelines

// ✅ Good: Reasonable page size with specific filtering
const optimizedQuery = {
    limit: 25,
    seenStatus: 'unseen',
    categories: ['post', 'reaction'],
    startDate: new Date(Date.now() - 86400000) // Last 24 hours
};

// ❌ Avoid: Too large page size without filtering
const inefficientQuery = {
    limit: 200, // Too large
    seenStatus: 'all', // Too broad
    // No time filtering - queries all historical data
};

Error Handling Strategies

Robust Error Management

Network Failures

Implement retry logic with exponential backoff for network-related errors

Rate Limiting

Handle rate limiting gracefully with appropriate user feedback

Data Validation

Validate query parameters before sending requests

Graceful Degradation

Provide fallback experiences when queries fail

Implementation Pattern

class NotificationErrorHandler {
    func handleQueryError(_ error: Error, retryAction: @escaping () -> Void) {
        switch error {
        case AmityError.networkError:
            showRetryOption(retryAction)
        case AmityError.rateLimited:
            showRateLimitMessage()
        case AmityError.invalidQuery:
            logQueryValidationError(error)
            showGenericError()
        default:
            showGenericError()
        }
    }
    
    private func showRetryOption(_ retryAction: @escaping () -> Void) {
        let alert = UIAlertController(
            title: "Connection Error",
            message: "Unable to load notifications. Try again?",
            preferredStyle: .alert
        )
        
        alert.addAction(UIAlertAction(title: "Retry", style: .default) { _ in
            retryAction()
        })
        
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
        
        // Present alert
    }
}

Memory Management

Lifecycle Best Practices

Proper Disposal: Always dispose live collections when views are destroyed
Weak References: Use weak references to prevent retain cycles
Background Processing: Handle collection updates on appropriate threads
Resource Cleanup: Clean up observers and subscriptions appropriately

Implementation Examples

class NotificationViewController: UIViewController {
    private var liveCollection: AmityCollection<AmityNotificationTrayItem>?
    private var collectionToken: AmityNotificationToken?
    
    deinit {
        // Clean up resources
        collectionToken?.invalidate()
        liveCollection = nil
    }
    
    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        
        // Pause updates when view is not visible
        if isMovingFromParent {
            collectionToken?.invalidate()
        }
    }
}

Use Cases

Notification Feed

Display a chronological list of all user notifications with filtering optionsImplementation:

Use basic query with time-based sorting
Enable real-time updates for live experience
Implement pagination for performance

Unread Badge Counter

Show count of unseen notifications for UI badge indicatorsImplementation:

Query with seenStatus: 'unseen'
Use count from collection metadata
Refresh on app foreground/resume

Category-specific Views

Create separate views for different notification typesImplementation:

Filter by specific categories
Create dedicated UI for each type
Optimize queries for targeted content

User Activity Timeline

Show notifications from specific users or user groupsImplementation:

Use actor-based filtering
Combine with time range filters
Enable cross-referencing with user profiles

Error Handling

Common Error Scenarios

Error Recovery Patterns

class NotificationQueryService {
    private let maxRetryAttempts = 3
    private var retryCount = 0
    
    func executeQueryWithRetry(query: AmityNotificationTrayQuery, completion: @escaping (Result<AmityCollection<AmityNotificationTrayItem>, Error>) -> Void) {
        
        let executeQuery = { [weak self] in
            self?.repository.getNotificationTrayItems(query: query) { result in
                switch result {
                case .success(let collection):
                    self?.retryCount = 0 // Reset on success
                    completion(.success(collection))
                case .failure(let error):
                    self?.handleQueryFailure(error, query: query, completion: completion)
                }
            }
        }
        
        executeQuery()
    }
    
    private func handleQueryFailure(_ error: Error, query: AmityNotificationTrayQuery, completion: @escaping (Result<AmityCollection<AmityNotificationTrayItem>, Error>) -> Void) {
        
        retryCount += 1
        
        if retryCount <= maxRetryAttempts && shouldRetry(error) {
            let delay = pow(2.0, Double(retryCount)) // Exponential backoff
            
            DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
                self?.executeQueryWithRetry(query: query, completion: completion)
            }
        } else {
            retryCount = 0
            completion(.failure(error))
        }
    }
    
    private func shouldRetry(_ error: Error) -> Bool {
        // Determine if error is retryable
        if case AmityError.networkError = error {
            return true
        }
        return false
    }
}

Mark Item as Seen

Update seen status for individual notification items

Global Tray Status

Manage overall notification tray seen state

Mark Tray as Seen

Update global tray seen timestamp

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Support

​Query Notification Tray Item

Flexible Filtering

Pagination Support

Real-time Updates

Multi-platform SDK

​Overview

​Architecture Overview

​Key Features

​Query Configuration

​Pagination Implementation

​Best Practices

​Use Cases