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. Each notification tray item represents a specific event in your social network, with properties likeeventType, actionType, and templatedText that define what triggered the notification and how it should be displayed to users.
For a complete reference of all event types, triggers, and message templates, see the Event Types & Message Templates section below.
Architecture Overview
Key Features
Advanced Filtering Options
Advanced Filtering Options
Seen Status Filtering
Filter notifications based on whether they have been seen or remain unread
Category-based Filtering
Query specific notification types such as posts, reactions, comments, or replies
Time-based Filtering
Retrieve notifications within specific date ranges or time periods
Actor-based Filtering
Filter notifications by specific users or user groups
Live Collection Features
Live Collection Features
- Real-time Updates: Automatic UI refresh when new notifications arrive
- Efficient Pagination: Built-in support for loading additional items
- Smart Caching: Optimized data retrieval and local storage
- State Management: Automatic handling of loading and error states
Performance Optimizations
Performance Optimizations
- Lazy Loading: Load notifications on-demand to improve performance
- Batch Operations: Efficient handling of multiple notification updates
- Memory Management: Automatic cleanup of unused notification data
- Network Optimization: Minimal API calls with intelligent caching
Query Configuration
- Query Builder
- Usage Examples
Basic Query Options
Basic Query Options
Required Parameters:
limit: Maximum number of items to retrieve per page (default: 20, max: 100)
includeDeleted: Include soft-deleted notifications (default: false)sortBy: Sort order -lastOccurredAtorcreatedAt(default:lastOccurredAt)sortDirection:ascordesc(default:desc)
Filter Parameters
Filter Parameters
Seen Status Filter:
seenStatus:seen,unseen, orall(default:all)
categories: Array of notification categories to include- Available categories:
post,poll,reaction,comment,reply,mention,follow
startDate: Filter notifications after this timestampendDate: Filter notifications before this timestamp
actorIds: Array of user IDs to filter notifications by
Advanced Options
Advanced Options
Performance Settings:
enableRealTimeUpdates: Enable live collection updates (default: true)cacheTimeout: Cache expiration time in seconds (default: 300)
loadingBehavior:immediateorlazy(default:immediate)errorRetryCount: Number of retry attempts on failure (default: 3)
Pagination Implementation
- Load More Pattern
- React Hook Implementation
Best Practices
Query Optimization
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
Error Handling Strategies
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
Memory Management
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
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
Event Types
This section provides a comprehensive reference of all supported notification event types, their triggers, and the message templates displayed in the notification tray.Understanding these event types and message templates is essential for properly rendering and handling notifications in your application. Each event has specific conditions that trigger it and corresponding message formats.
Complete Event Reference Table
- Content Creation Events
- Engagement Events
- Detailed Event Breakdown
| Event Type | Trigger Condition | Message Template |
|---|---|---|
| Post (Text, Image, Video) | Bob & Alice are members of the same community Bob creates a post in that community → Alice sees notification | Single notification:Bob posted in {{communityDisplayName}}Grouped (2 actors): {{displayName_1}} and {{displayName_2}} posted in {{communityDisplayName}}Grouped (3+ actors): {{displayName_1}} and {{number}} others posted in {{communityDisplayName}}Note: Posts in the same community within the same day are grouped |
| Poll | Bob & Alice are members of the same community Bob starts a poll in that community → Alice sees notification | Bob started a poll in {{communityDisplayName}} |
| Comment | Bob comments on Alice’s post → Alice sees notification | Community Post:Bob commented on your post in {{communityDisplayName}}Alice’s User Feed: Bob commented on your post on your feedAnother User’s Feed: Bob commented on your post on {{targetUserDisplayName}} feed |
| Reply | Bob replies to Alice’s comment → Alice sees notification | Community Comment:Bob replied to your comment in {{communityDisplayName}}Alice’s Feed: Bob replied to your comment on your feedBob’s Feed: Bob replied to your comment on their feedCharlie’s Feed: Bob replied to your comment on Charlie feed |
Error Handling
Common Error Scenarios
Common Error Scenarios
Network Connectivity Issues:
- Error: Connection timeout or network unavailable
- Response: Show offline indicator and retry options
- Recovery: Implement exponential backoff retry strategy
- Error: Malformed query or invalid filter values
- Response: Log validation errors and use fallback query
- Recovery: Validate parameters before query execution
- Error: Too many requests in short time period
- Response: Display rate limit message to user
- Recovery: Implement request throttling and queue management
- Error: Internal server errors or maintenance
- Response: Show maintenance message with status updates
- Recovery: Implement graceful degradation and status checking
Error Recovery Patterns
Error Recovery Patterns