실시간 이벤트 (SSE) 연동 가이드

ECARUS API 중 일부(Child Care, Geofence 등)는 실시간 상태 업데이트를 위해 **Server-Sent Events (SSE)**를 제공합니다. 이 가이드에서는 SSE를 앱이나 클라이언트에서 어떻게 연동하는지 설명합니다.

개요

SSE는 서버에서 클라이언트로 실시간 데이터를 스트리밍하기 위한 표준 기술입니다. WebSocket과 달리 HTTP 위에서 작동하며, 클라이언트는 서버가 보내는 이벤트를 단순히 듣기만(Listen) 하면 됩니다.

연동 방법

1. Connection 연결

EventSource 객체를 사용하여 API 엔드포인트에 연결합니다.

const vin = "KMHSH81C7LU123456";
const eventSource = new EventSource(`https://api.ecarus.run/api/v1/childcare/vehicles/${vin}/child-alert/events`);

eventSource.onopen = () => {
    console.log("SSE Connection established!");
};

2. 이벤트 수신

서버에서 발행하는 특정 이벤트를 리슨합니다.

eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    
    if (data.eventType === "CHILD_LEFT_BEHIND") {
        alert("경고: 차량 내에 아동이 감지되었습니다!");
        console.log("위치:", data.lastLocation.address);
    }
};

eventSource.onerror = (error) => {
    console.error("SSE Error:", error);
    // 필요 시 재연결 로직 구현
};

제공되는 SSE 엔드포인트

서비스	엔드포인트	설명
Child Care	/childcare/vehicles/{vin}/child-alert/events	아동 방치 감지 실시간 알림
Geofence	/childcare/vehicles/{vin}/geofence/events	지오펜스 진입/이탈 알림
Diagnosis	/diagnosis/auto/events	실시간 차량 진단 상태 업데이트

주의 사항

• 인증: 일반적인 EventSource API는 커스텀 헤더(예: Authorization)를 직접 지원하지 않습니다.
  • 해결 방안 1: URL 쿼리 파라미터로 토큰 전달 (서버 지원 시)
  • 해결 방안 2: event-source-polyfill 라이브러리 사용
• 재연결: 네트워크 불안정 시 자동으로 재연결을 시도하지만, 비즈니스 로직에서 상태 관리가 필요할 수 있습니다.