Skip to main content

Getting Started with Socket.io

The Socket.io API is designed for real-time telemetry data streaming, offering only live telemetry updates (no historical or absolute data). 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.

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..." }
});

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.

Subscribing to Events​

Once connected, you can listen for several types of telemetry events:

  • telemetry_ua – Unmanned Aircraft telemetry
  • telemetry_operator – Operator telemetry
  • telemetry_system – System telemetry
  • operation – Updates on ongoing operations

For the most up-to-date and comprehensive list of available events, 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. For more details, see the conditions for REST API telemetry requests.

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. If you don't set a viewport, your session won't receive any telemetry data.

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. It's important to debounce these updates to prevent rapid viewport changes, which could lead to server disconnecting your clients.

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', () => {
  socket.emit('viewport', viewportRectangle.getBounds().toBBoxString());
});

socket.on('telemetry_ua', (data) => {
  console.log('UA telemetry received:', data);
});