Přeskočit na hlavní obsah

Getting Started with Socket.io

The Socket.io API is designed for real-time telemetry data streaming, offering only live updates (no historical or absolute data). Data you miss while disconnected are not replayed — to get the current state or fill gaps after a reconnect, use the REST API. This guide will walk you through setting up a real-time connection between Dronetag and your application using Socket.io.

Connection Parameters​

To establish a connection, use the following configuration parameters in your Socket.io client:

  • Host: https://api.dronetag.app
  • Path: /v2/airspace/socket.io
  • Client Version: v3 or v4
Host and path differs

Be careful with your configuration—ensure that the host is set to the domain only (https://api.dronetag.app) and that the path is specified separately. Confusing these two can result in connection errors.

Choosing a Socket.io Client​

Socket.io is supported by many libraries across various programming languages. You can find the full list of supported client implementations here.

Authenticating Your Session​

You can authenticate your Socket.io session using the same access token that you use for REST API requests. Refer to the API credentials guide for details on obtaining your access token.

Use OpenID Connect for Socket.io

The authentication section linked above mentions two possible types of API authentication: Personal Access Tokens (PAT) and OpenID Connect (OIDC). Personal Access Tokens are not supported by the Socket.io API, so only use OIDC tokens when working with Socket.io.

Authentication is optional. A session without a token receives only publicly available data, while an authenticated session also receives the data your account has access to.

If the token you send is not valid, the server refuses the connection and your client receives a connect_error with the message unauthorized.

Native Socket.io Authentication​

For clients that support native Socket.io authentication, you can pass the access token directly in the auth configuration option.

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  auth: "eyJhbGciOiJSUzI1NiIsInR5c...",
});

More information on using Socket.io authentication can be found in the Socket.io documentation.

Using a Bearer Token in the Handshake Request​

If your client does not support the auth option, you can send the access token as an Authorization header in the handshake request:

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  extraHeaders: { Authorization: "Bearer eyJhbGciOiJSUzI1NiIsInR5c..." }
});

The header value must be in the form Bearer <token>, otherwise the connection is refused with the message wrong bearer token format.

This approach is also handy when using tools like Postman for testing, which typically don’t support native authentication. You can simply add the Authorization header in the Headers tab of Postman.

Authenticating an Existing Connection​

You can also authenticate an already established connection by sending the access token in the authenticate event. The server acknowledges it with {"result": "ok"}. If the token is not valid, the server responds with {"result": "not_authenticated"} and the connection stays open as unauthenticated, receiving only publicly available data.

Subscribing to Events​

Once connected, you can listen for the following events:

  • serverinfo – Sent once, right after the connection is established. Contains information about the server, such as server_version, environment and your_sid (your session ID as seen by the server).
  • telemetry_ua – Unmanned Aircraft telemetry
  • telemetry_operator – Operator telemetry
  • telemetry_system – System telemetry
  • operation – Operation updates

Each telemetry_ua, telemetry_operator, telemetry_system and operation event carries an array of DUMP messages, not a single message. Telemetry events are limited to the viewport you set (see below), while operation events are not limited by the viewport. The operation event carries OperationUpdate messages, which contain only recent changes of an operation, not its full state.

For the most up-to-date and comprehensive list of available events, their payloads and responses, refer to our AsyncAPI documentation.

Setting and Updating the Viewport​

Just as with the REST API, you must specify the geographical region your application is interested in.

After connecting, your client must send an initial viewport event to define the geographical area it wants to monitor. Additionally, the client must update this area by sending new viewport events whenever the region of interest changes. Each viewport event replaces the previously set viewport. If you don't set a viewport, your session won't receive telemetry for any area.

The viewport is bound to a single connection. Whenever your client connects or reconnects, it must send the viewport again.

The viewport is a string in the format lon_min,lat_min,lon_max,lat_max — longitude and latitude in degrees, separated by commas without spaces. For example, to set viewport to Prague, you may use something like emit("viewport", "14,49.9,15,50.3").

For example, in Dronetag’s own applications, the map moves dynamically based on user interactions. After establishing a connection, the app sends the initial viewport, and as the user moves the map, the viewport is updated. We recommend debouncing these updates, so that your client does not send a new viewport on every small map movement.

Always set your viewport carefully. It is important to cover whole area of your interest. On the other hand, do not set viewports too large, as it could provide data you do not want and also cause performance issues. It is recommended to add a sufficient margin of a few kilometers (or miles, if you wish) on each side. The maximal supported viewport area is around 6 million square kilometers, but try avoiding such extreme values.

The server acknowledges each viewport event with one of these responses:

  • {"result": "ok"} – The viewport was set.
  • {"result": "invalid-param", "messages": [...]} – The viewport is not in the expected format or its values are out of range.
  • {"result": "bbox_area_too_large", "messages": [...]} – The viewport area exceeds the maximal supported area. The previously set viewport stays in effect.

To read the response, pass an acknowledgement callback when emitting the event, for example socket.emit("viewport", "14,49.9,15,50.3", (response) => console.log(response)).

Ordering Telemetry​

By default, telemetry within each event is ordered by time in ascending order. You can change the ordering for each telemetry event by sending the ordering event. Its payload must be a JSON-encoded string mapping the event names to one of these values:

  • time – ascending order (default)
  • -time – descending order
socket.emit("ordering", JSON.stringify({
  telemetry_ua: "-time",
  telemetry_operator: "time",
  telemetry_system: "time",
}));

The server acknowledges the event with {"result": "ok"}, or with {"result": "invalid-param", "messages": [...]} if the payload is not valid. Like the viewport, the ordering is bound to a single connection.

Example Code Snippets​

Below are some quick examples to help you get started with Socket.io in different programming languages:

const { io } = require('socket.io-client');

const socket = io('https://api.dronetag.app', {
  path: '/v2/airspace/socket.io',
  auth: 'eyJhbGciOiJSUzI1NiIsInR5c...'
});

socket.on('connect', () => {
  // The viewport must be sent after every (re)connect
  socket.emit('viewport', '14,49.9,15,50.3', (response) => {
    console.log('Viewport response:', response);
  });
});

socket.on('connect_error', (err) => {
  console.error('Connection error:', err.message);
});

socket.on('telemetry_ua', (batch) => {
  for (const telemetry of batch) {
    console.log('UA telemetry received:', telemetry);
  }
});