TiQer Async Response - Quick Reference Guide

🚀 API Endpoint

POST /api/v2/tiqer/response-async/

📝 Request Format

{
  "option_id": 24072,
  "card_number": 5,
  "question_id": 40795,
  "session_token": "677145c7-b80a-4ba8-b75b-24555300c07e",
  "response_time_seconds": 10,  // Optional
  "confidence_score": 1.0       // Optional
}

✅ Success Response (202)

{
  "status": "SUCCESS",
  "message": "SUBMITTED",
  "task_id": "12dd6374-e260-4a81-a2a4-93702ce00ddd",
  "firebase_subscription": {
    "path": "tiqer_sessions/{session_token}/async_responses"
  }
}

🔥 Firebase Listener Setup

const asyncResponsesRef = firebase.database()
  .ref(`tiqer_sessions/${sessionToken}/async_responses`);

asyncResponsesRef.on('child_added', (snapshot) => {
  const notification = snapshot.val();
  
  if (notification.event === 'response_processed') {
    // Success: Update UI with student response
    updateStudentResponse(notification.student_info, notification.response_info);
  } else if (notification.event === 'response_error') {
    // Error: Show error message
    showError(notification.error_info.error_message);
  }
  
  // IMPORTANT: Clean up notification
  snapshot.ref.remove();
});

📊 Success Notification

{
  "event": "response_processed",
  "student_info": {
    "student_name": "John Doe",
    "card_number": 5,
    "roll_number": "001"
  },
  "response_info": {
    "is_correct": true,
    "obtained_score": 1.0,
    "response_time_seconds": 10
  },
  "task_id": "12dd6374-e260-4a81-a2a4-93702ce00ddd"
}

❌ Error Notification

{
  "event": "response_error",
  "error_info": {
    "error_code": "INVALID_OPTION",
    "error_message": "Option 99999 does not exist for question 40795. Valid options: [24072, 24074, 24075, 24073]"
  },
  "task_id": "119fb3e1-534e-4ca1-9474-fc4032a36712"
}

🧹 Firebase Cleanup (CRITICAL)

// Method 1: Frontend cleanup (Recommended)
snapshot.ref.remove(); // Clean up each notification after processing

// Method 2: API cleanup
fetch('/api/v2/tiqer/firebase-cleanup/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Token ${userToken}`
  },
  body: JSON.stringify({
    session_token: sessionToken,
    cleanup_mode: 'partial',  // or 'complete'
    immediate: true
  })
});

🚨 Common Error Codes

Code	Action
INVALID_OPTION	Show valid options
INVALID_CARD	Show available cards
SESSION_NOT_ACTIVE	Refresh page
QUESTION_MISMATCH	Refresh current question

⚡ Performance Target

• API Response: <15ms (95%+ improvement)
• Background Processing: ~2-3 seconds
• Firebase Notification: Real-time

🔄 Integration Flow

1. Submit → Get immediate task_id
2. Listen → Firebase notifications
3. Process → Update UI based on notification
4. Cleanup → Remove Firebase notification
5. Repeat → For next response

📞 Testing Commands

# Test valid response
curl -X POST '/api/v2/tiqer/response-async/' \
  -H 'Authorization: Token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "option_id": 24072,
    "card_number": 5,
    "question_id": 40795,
    "session_token": "your-session-token"
  }'

# Test invalid option (will trigger error notification)
curl -X POST '/api/v2/tiqer/response-async/' \
  -H 'Authorization: Token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "option_id": 99999,
    "card_number": 5,
    "question_id": 40795,
    "session_token": "your-session-token"
  }'

✅ Must-Do Checklist

• Setup Firebase listener for async_responses
• Handle both success and error notifications
• Implement Firebase cleanup (prevents accumulation)
• Add error handling for all error codes
• Test with invalid data to verify error notifications
• Monitor performance and response times

⚠️ WARNING: Always clean up Firebase notifications to prevent data accumulation!