Real-time Events (SSE) Integration Guide

Some ECARUS APIs (Child Care, Geofence, etc.) provide Server-Sent Events (SSE) for real-time status updates. This guide explains how to integrate SSE into your app or client.

Overview

SSE is a standard technology for streaming real-time data from server to client. Unlike WebSockets, it operates over HTTP, and the client simply needs to listen for events sent by the server.

Integration Method

1. Establishing a Connection

Connect to the API endpoint using the EventSource object.

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. Receiving Events

Listen for specific events published by the server.

eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    
    if (data.eventType === "CHILD_LEFT_BEHIND") {
        alert("Warning: Child detected inside the vehicle!");
        console.log("Location:", data.lastLocation.address);
    }
};

eventSource.onerror = (error) => {
    console.error("SSE Error:", error);
    // Implement reconnection logic if necessary
};

Available SSE Endpoints

Service	Endpoint	Description
Child Care	/childcare/vehicles/{vin}/child-alert/events	Real-time child detection alerts
Geofence	/childcare/vehicles/{vin}/geofence/events	Geofence entrance/exit notifications
Diagnosis	/diagnosis/auto/events	Real-time vehicle diagnostic status updates

Considerations

• Authentication: The standard EventSource API does not directly support custom headers (e.g., Authorization).
  • Solution 1: Pass the token via URL query parameters (if supported by the server)
  • Solution 2: Use the event-source-polyfill library
• Reconnection: While it automatically attempts to reconnect during network instability, state management may be required within your business logic.