Clients configuration

In this section, we will walk through how your clients—whether mobile applications, IoT devices, or other physical hardware—can seamlessly integrate with the Pulsetracker platform to send real-time location data. The Pulsetracker protocol and API have been designed to be lightweight, efficient, and developer-friendly, ensuring reliable communication with minimal overhead.

We’ll cover the following steps:

1. Understanding the Pulsetracker Data Format: Learn about the json structure of the data you need to send.

2. Establishing Communication: Set up authenticated connections to Pulsetracker servers using the protocol of your choice.

3. Sending Real-Time Locations: See examples of how to send geolocation data, complete with app and client identifiers, ensuring accurate and personalized tracking.

4. Optional Metadata: Include additional data to enhance tracking insights.

This guide is geared towards developers looking to integrate real-time tracking features into their products with ease and scalability. Whether you’re building a mobile app or deploying a fleet of GPS-enabled devices, Pulsetracker provides all the tools you need to succeed.

Server Communication Protocols

Server Communication Protocols

Pulsetracker provides flexibility in how your clients communicate with our servers, allowing you to choose the most suitable protocol for your use case:

1. UDP Protocol

   • Designed for lightweight, high-performance communication.

   • Ideal for scenarios where battery consumption and speed are critical, such as mobile applications or IoT devices.

   • Best for applications where occasional packet loss is acceptable.

2. WebSockets

   • Perfect for real-time, two-way communication with a persistent connection.

   • Suitable for use cases requiring reliable data delivery, such as web apps or scenarios with critical data integrity requirements.

Recommendation:
For battery-sensitive applications, such as smartphones or wearables, the UDP protocol is highly recommended. For scenarios where reliable data delivery is essential, such as monitoring dashboards or enterprise solutions, WebSockets are the preferred choice.

Both options ensure seamless integration with Pulsetracker's scalable and secure real-time tracking infrastructure.

Protocol

Pulsetracker employs a JSON-based protocol that ensures structured and consistent communication between your clients and our servers. Each message must adhere to this format for successful processing.

Required Fields

• appId: (String)
  The unique identifier for your application. This key is required for authentication and mapping the data to the correct app.

• clientId: (String)
  The unique identifier for the client (e.g., a device or user). This field ensures that location data is correctly associated with the sending client.

• data: (Object)
  A GeoJSON-compliant structure representing the location data.

  • type: (String) — Always set to "Point" to denote a single location.

  • coordinates: (Array) — A two-element array containing the longitude and latitude values in decimal degrees format.

• extra: (Object)
  A key-value structure for sending additional metadata (optional). This allows your clients to attach extra information, such as battery status, signal strength, or device-specific data.

JSON Message Example

Copy{
    "appId": "exampleApp123",
    "clientId": "device5678",
    "data": {
        "type": "Point",
        "coordinates": [-122.4194, 37.7749]
    },
    "extra": {
        "battery": 87,
        "signalStrength": "strong",
        "deviceType": "smartphone"
    }
}

Key Notes

1. Data Accuracy: Ensure longitude and latitude values are accurate to maintain the integrity of the tracking information.

2. Optional Metadata: Use the extra field to provide as much context as necessary for your application, but avoid overloading it with redundant data.

3. Protocol Compliance: Ensure your client libraries or devices strictly follow this structure to prevent rejection or misinterpretation of the messages.

Client examples

UDP Python example

Copyimport json
import socket
# Data to be sent
data = {    
    "appId": "YOUR_APP_KEY",    
    "clientId": "CLIENT_KEY",    
    "data": {        
        "type": "Point",        
        "coordinates": [-14.80665, -140.22159]    
    },    
    'extra' : {        
        'speed' : 100
    }
}
# Convert the data to a JSON string
json_data = json.dumps(data)
# Create a UDP socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
# Define the host and port
# Send the data
sock.sendto(json_data.encode('utf-8'), (host, port))
print(f"Location sent: {json_data}")
# Close the socket
sock.close()

Javascript websockets example

Copyvar wsServer = 'wss://ws-tracking.pulsestracker.com';
var websocket = new WebSocket(wsServer);
const appId = 'YOUR_APP_KEY';
const clientId = 'YOUR_CLIENT_KEY';

websocket.onopen = function(evt) {
    console.log("Connected to WebSocket server.");

    setInterval(() => {
        if (websocket.readyState === WebSocket.OPEN) {
            navigator.geolocation.getCurrentPosition((position) => {
                console.log(position);
                const locationData = {
                    appId: appId,
                    clientId: clientId,
                    data: {
                        type: "Point",
                        coordinates: [position.coords.longitude, position.coords.latitude]
                    },
                    extra: {
                        key: "value"
                    }
                };
                // Send location data as JSON
                websocket.send(JSON.stringify(locationData));
                console.log('Location sent:', locationData);
            }, (error) => {
                console.error('Error getting location:', error);
            });
        }
    }, 3000); // Every 3 seconds
};

websocket.onclose = function(evt) {
    console.log("Disconnected");
};

websocket.onmessage = function(evt) {
    if (event.data === 'Pong') {
        console.log('Received Pong from server');
    } else {
        // Handle other messages
        console.log('Received:', event.data);
    }
};

websocket.onerror = function(evt, e) {
    console.log('Error occurred: ' + evt.data);
};