feat: Add participant idle event callbacks to iOS example app #292

xiajon · 2025-08-01T18:47:39Z

Summary

This PR adds support for participant idle event callbacks to the iOS example app, demonstrating how to use the new participant idle events from the Amazon Connect Chat iOS SDK.

Changes

ChatManager.swift

Add callback implementation with display name logging
Add callback implementation with display name logging
Add callback implementation with display name logging
Add comprehensive transcript logging for debugging participant events

CommonUtils.swift

Add event text customization for participant idle events:
- : 'Agent has gone idle'
- : 'Agent has returned'
- : 'Agent was automatically disconnected'

Features

Participant Idle Event Callbacks

The app now demonstrates how to use the new participant idle event callbacks:

ChatSession.shared.onParticipantIdle = { displayName in
    print("\(displayName) has gone idle.")
    // Custom idle handling logic
}

ChatSession.shared.onParticipantReturned = { displayName in
    print("\(displayName) has returned from idle.")
    // Custom return handling logic
}

ChatSession.shared.onAutoDisconnection = { displayName in
    print("\(displayName) was automatically disconnected.")
    // Custom disconnection handling logic
}

Enhanced Transcript Logging

Added comprehensive logging to help developers understand the event flow:

Logs all transcript items with event types and display names
Special logging for idle-related events with 🚨 IDLE_EVENT prefix
Helps developers debug and understand participant state changes

Event Text Customization

Events now appear in the chat transcript as user-friendly system messages:

"Customer has gone idle" instead of raw event data
"Agent has returned" with proper participant identification
"Customer was automatically disconnected" for timeout scenarios

Benefits

Display Name Context: Callbacks now provide specific participant information instead of generic events
Better UX: Developers can implement participant-specific UI logic and notifications
Debugging Support: Enhanced logging helps developers understand event flow
ChatJS Compatibility: Follows the same pattern as the ChatJS web SDK

Testing

✅ Callbacks fire correctly when participant idle events are received
✅ Display names are properly extracted and passed to callbacks
✅ Events appear in transcript with customized text
✅ Logging helps with debugging and development
✅ No breaking changes to existing functionality

Usage Example

After integrating this change, developers can:

Handle idle events: Show notifications when participants go idle
Track participant state: Implement UI indicators for participant status
Custom logic: Build participant-specific features based on idle/return events
Debug easily: Use the enhanced logging to understand event flow

The events automatically appear in the chat transcript as system messages, providing a complete participant state experience.

- Add ChatManager callback implementations: - onParticipantIdle: receives display name, logs idle events - onParticipantReturned: receives display name, logs return events - onAutoDisconnection: receives display name, logs disconnection events - Add CommonUtils event text customization: - participantIdle: 'Agent has gone idle' - participantReturned: 'Agent has returned' - autoDisconnection: 'Agent was automatically disconnected' - Add transcript logging for debugging: - Logs all transcript items with event types and display names - Special logging for idle-related events with 🚨 IDLE_EVENT prefix - Helps developers understand event flow and data structure Example app now demonstrates: - How to use participant idle event callbacks - How to access display name information - How events appear in chat transcript as system messages Usage: ChatSession.shared.onParticipantIdle = { displayName in print('\(displayName) has gone idle.') // Custom idle handling logic }

…ndling ENHANCED EXAMPLE APP: ✅ EventData Usage - All callbacks now receive complete event information ✅ Rich Event Handling - Access to participantRole, participantId, timestamps, etc. ✅ Practical Examples - Real-world usage patterns demonstrated UPDATED CALLBACK IMPLEMENTATIONS: - onParticipantIdle: Uses eventData.displayName, eventData.participantRole - onParticipantReturned: Enhanced with participant role checking - onAutoDisconnection: Role-specific handling (CUSTOMER vs AGENT) EXAMPLE USAGE PATTERNS: �[1;38;5;196mWelcome to Swift!�[0m �[1mSubcommands:�[0m �[1mswift build�[0m Build Swift packages �[1mswift package�[0m Create and work on packages �[1mswift run�[0m Run a program from a package �[1mswift test�[0m Run package tests �[1mswift repl�[0m Experiment with Swift code interactively Use �[1m`swift --version`�[0m for Swift version information. Use �[1m`swift --help`�[0m for descriptions of available options and flags. Use �[1m`swift help <subcommand>`�[0m for more information about a subcommand. BENEFITS FOR DEVELOPERS: - Complete event context available in callbacks - Role-based conditional logic possible - Participant identification for multi-participant chats - Timestamp information for event ordering - Content type for event categorization The example app now demonstrates the full capabilities of the enhanced event system with EventData structure.

COMPLETE EVENT LOGGING SYSTEM: ✅ All 9 Events - Comprehensive print statements with emojis and context ✅ Rich Information - Display names, roles, IDs, timestamps for each event ✅ Practical Examples - Real-world UI handling suggestions ✅ Role-Based Logic - Different handling for AGENT, CUSTOMER, SUPERVISOR EVENT CATEGORIES WITH DETAILED LOGGING: 🔄 PARTICIPANT STATE EVENTS (3 events): 😴 ParticipantIdle - Participant went idle with idle handling suggestions 🔄 ParticipantReturned - Participant returned with status restoration 🚪 AutoDisconnection - Automatic disconnection with reconnection options 💬 COMMUNICATION EVENTS (3 events): 🔤 Typing - Typing indicators with UI suggestions ✅ ReadReceipt - Message read confirmations with status updates 📬 DeliveredReceipt - Message delivery confirmations 👥 PARTICIPANT MANAGEMENT EVENTS (2 events): 👋 ParticipantInvited - New participants joining (Agent/Supervisor/Customer) ✏️ ParticipantDisplayNameUpdated - Name changes with UI refresh suggestions 🔄 ADVANCED EVENTS (1 event): 🔄 ChatRehydrated - Chat session restoration with history loading ENHANCED LOGGING FEATURES: - 📊 Event Type Icons - Visual identification of event categories - 🏷️ Participant Context - Role, ID, display name for each event - ⏰ Timestamp Information - When events occurred - 💡 UI Suggestions - Practical implementation guidance - 🎯 Role-Specific Logic - Different handling based on participant type EXAMPLE OUTPUT: DEVELOPER BENEFITS: - Complete event visibility during development and testing - Real-world implementation guidance for each event type - Easy debugging with detailed event context - Role-based conditional logic examples - UI/UX implementation suggestions The example app now provides comprehensive logging for all supported ChatJS events with practical implementation guidance.

🔄 Event Callback Updates: - Update all event callbacks to use Event instead of EventData - Fix property mappings: participantRole → participant, absoluteTime → timeStamp - Handle optional serializedContent access properly 📬 Receipt Callback Enhancements: - Improve receipt callback logging with better participant information - Extract role information from serializedContent when available - Show participant ID alongside role for better debugging - Handle cases where participant role cannot be determined ✅ Property Mapping Fixed: - eventData.participantRole → event.participant - eventData.absoluteTime → event.timeStamp - eventData.messageId → event.id - eventData.initialContactId → event.serializedContent?["InitialContactId"] 🎯 Better Receipt Display: - Show participant role and ID: 'AGENT [participant-id]' - Fallback to partial ID when role cannot be determined - More informative logging for debugging receipt events All callbacks now work with unified Event-based architecture!

📬 Receipt Callback Updates: - Simplify receipt callbacks to use actual participant IDs - Remove complex role determination logic (was ineffective with UUIDs) - Clean up callback logging to show essential information - Focus on participant ID as primary identifier 🗑️ Removed Unused Features: - Remove onParticipantDisplayNameUpdated callback implementation - Clean up example code to focus on essential callbacks - Remove misleading role-based logic from receipt handling ✅ Improved Developer Experience: - Clear, simple receipt callback examples - Actual participant IDs available for mapping to user systems - Cleaner logging output for debugging - Focused on practical implementation patterns Example app now demonstrates clean, effective usage of the optimized event system.

…xamples 🎯 Simplified Event Callbacks: - Remove complex conditional logic and verbose explanations - Use clean, one-line print statements with force unwrapping - Focus on showing property access patterns, not edge cases 📝 Updated Event Logging: - onParticipantIdle: Simple participant and timestamp logging - onParticipantReturned: Clean return event logging - onAutoDisconnection: Straightforward disconnection logging - onTyping: Basic typing indicator logging - onReadReceipt: Simple receipt logging with participant ID - onDeliveredReceipt: Clean delivery confirmation logging - onParticipantInvited: Basic participant join logging - onChatRehydrated: Simple rehydration event logging ✅ Benefits: - Reference-style examples that are easy to copy and understand - Consistent logging format across all event types - Focus on API usage rather than implementation details - Clean, scannable code for developers to reference Example app now demonstrates the same clean logging patterns shown in the README documentation.

🧹 Logging Cleanup: - Remove emoji icons from all event callback logs - Remove verbose transcript debugging logs - Simplify onTranscriptUpdated to essential functionality only 📝 Event Logging Changes: - PARTICIPANT IDLE (removed 😴) - PARTICIPANT RETURNED (removed 🔄) - AUTO DISCONNECTION (removed 🚪) - TYPING (removed 🔤) - READ RECEIPT (removed ✅) - DELIVERED RECEIPT (removed 📬) - PARTICIPANT INVITED (removed 👋) - CHAT REHYDRATED (removed 🔄) 🗑️ Removed Transcript Debugging: - Remove TRANSCRIPT_LOG verbose output - Remove special IDLE_EVENT logging - Remove detailed item enumeration logging - Keep only essential transcript processing ✅ Benefits: - Cleaner, professional log output - Reduced console noise for debugging - Focus on essential information only - Better performance with less logging overhead Example app now has clean, minimal logging suitable for production use.

🔀 Transfer Event Integration: - Add onTransferSucceeded callback with clean logging - Add onTransferFailed callback with clean logging 📝 Event Logging: - TRANSFER SUCCEEDED: Clean success message with timestamp - TRANSFER FAILED: Clean failure message with timestamp 🎯 Consistent Pattern: - Follows same clean logging pattern as other events - No emojis, simple reference-style examples - Force unwrapping for demonstration purposes Example output: - 'TRANSFER SUCCEEDED: Transfer completed successfully at 2024-01-15T10:30:00Z' - 'TRANSFER FAILED: Transfer failed at 2024-01-15T10:30:00Z' Completes the comprehensive event handling demonstration in the example app.

🔄 Optional Event Handling: - Update all event callbacks to handle Event? parameter - Add graceful fallback messages when event data is nil - Maintain detailed logging when event data is available 📝 Enhanced Event Logging: - With event data: Full details including participant, timestamp, message ID - Without event data: Clean fallback messages for basic notifications 🎯 Updated Callbacks: - onParticipantIdle: Handles both detailed and simple idle notifications - onParticipantReturned: Supports detailed and basic return notifications - onAutoDisconnection: Covers detailed and simple disconnection alerts - onTyping: Shows participant details or generic typing indicator - onReadReceipt: Displays message details or basic read confirmation - onDeliveredReceipt: Shows delivery details or simple confirmation - onParticipantInvited: Participant details or generic join notification - onChatRehydrated: Timestamp details or basic restoration message - onTransferSucceeded: Detailed success info or simple confirmation - onTransferFailed: Detailed failure info or basic error message ✅ Example Output: // With event data: 'PARTICIPANT IDLE: John Doe (AGENT) went idle at 2024-01-15T10:30:00Z' // Without event data: 'PARTICIPANT IDLE: A participant went idle' Demonstrates best practices for handling optional event parameters while maintaining professional, informative logging.

🎨 UI Status Display Fix: - Show delivered and read status for both attachments and regular messages - Previously only showed status for recent, failed, or sending messages - Now displays complete status progression for all outgoing messages 📱 Files Updated: - AttachmentMessageView.swift: Show delivered/read status for attachments - ChatMessageView.swift: Show delivered/read status for regular messages 🔧 Status Condition Updated: - BEFORE: recentOutgoingMessageID || .Failed || .Sending - AFTER: recentOutgoingMessageID || .Failed || .Sending || .Delivered || .Read ✅ User Experience: - Attachments now show: Sending → Sent → Delivered → Read - Regular messages show complete status progression - Status remains visible (doesn't disappear after becoming non-recent) - Consistent behavior between attachments and text messages Resolves attachment receipt display issues in the example app UI.

mliao95 · 2025-08-05T00:36:55Z

mobileChatExamples/iOSChatExample/AmazonConnectChatIOSDemo/Models/ChatManager.swift

+
+        self.chatSession.onParticipantIdle = { event in
+            if let event = event {
+                print("PARTICIPANT IDLE: \(event.displayName!) (\(event.participant!)) went idle at \(event.timeStamp)")


NIT:
Could we update these logs? I think it looks odd just having the event name in all caps.

Let's follow the pattern of the previous events:
onChatEnded --> Chat has ended
onConnectionBroken --> Connection was lost.

Examples:

onParticipantIdle --> Participant became idle.
etc.

📝 Event Message Improvements: - Updated all event callback messages to follow consistent pattern - Changed from ALL CAPS format to sentence case with descriptive text - Aligned with existing patterns like 'Chat has ended.' and 'Connection was lost.' 🔄 Message Updates: - onParticipantIdle: 'Participant became idle.' - onParticipantReturned: 'Participant returned.' - onAutoDisconnection: 'Participant was automatically disconnected.' - onTyping: 'Participant is typing.' - onReadReceipt: 'Message was read.' - onDeliveredReceipt: 'Message was delivered.' - onParticipantInvited: 'Participant was invited.' - onChatRehydrated: 'Chat session was restored.' - onTransferSucceeded: 'Transfer completed successfully.' - onTransferFailed: 'Transfer failed.' ✅ Benefits: - Consistent logging style across all events - Professional, readable log messages - Follows established app conventions - Better developer experience Addresses PR feedback for improved event logging consistency.

xiajon requested a review from a team as a code owner August 1, 2025 18:47

xiajon requested review from palna26 and swasri and removed request for a team August 1, 2025 18:47

xiajon force-pushed the feature/participant-idle-events branch from 7fa635e to af39766 Compare August 1, 2025 20:54

xiajon added 9 commits August 1, 2025 14:28

mliao95 previously approved these changes Aug 5, 2025

View reviewed changes

xiajon dismissed mliao95’s stale review via cb7730c August 5, 2025 17:11

mliao95 approved these changes Aug 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: Add participant idle event callbacks to iOS example app #292

feat: Add participant idle event callbacks to iOS example app #292

Uh oh!

xiajon commented Aug 1, 2025

Uh oh!

mliao95 Aug 5, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

feat: Add participant idle event callbacks to iOS example app #292

Are you sure you want to change the base?

feat: Add participant idle event callbacks to iOS example app #292

Uh oh!

Conversation

xiajon commented Aug 1, 2025

Summary

Changes

ChatManager.swift

CommonUtils.swift

Features

Participant Idle Event Callbacks

Enhanced Transcript Logging

Event Text Customization

Benefits

Testing

Related

Usage Example

Uh oh!

mliao95 Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mliao95 Aug 5, 2025 •

edited

Loading