Die Datenschnittstelle

Diese Funktion ist Teil des SmartRace Champions Clubs. Das ist ein großes Paket mit coolen Erweiterungen, die Du auf Wunsch in Form eines monatlichen oder jährlichen Abos bequem in der App hinzu buchen und natürlich jederzeit wieder kündigen kannst. Mehr erfahren.

Was ist die Datenschnittstelle?

Die Datenschnittstelle bietet Dir die Möglichkeit, externe Dienste oder Scripts an SmartRace anzubinden. Dazu sendet SmartRace auf Wunsch bestimmte Daten an einen konfigurierbaren Endpunkt und Du kannst diese Daten nach Belieben weiterverarbeiten. Die Daten werden dabei als POST-Request im JSON-Format gesendet.

Die Datenschnittstelle ist Endpunkt-agnostisch, richtet sich also nicht an bestimmte Endpunkte mit bestimmtem Datenformat. Was Du mit den Daten tust, ist alleine Deine Entscheidung.

Aktivierung und Konfiguration

Die Datenschnittstelle ist standardmäßig nicht aktiviert. Um sie zu aktivieren, gehe im Hauptmenü von SmartRace auf Einstellungen und öffne den Reiter Datenschnittstelle. Über den Schalter ganz oben kannst Du die Schnittstelle einschalten, zusätzlich musst Du allerdings noch die Ereignisse aktivieren, die die Datenschnittstelle berücksichtigen soll. Welche Daten in den einzelnen Ereignissen enthalten sind, erfährst Du weiter unten.

Die verschiedenen Ereignisse

Du kannst auswählen, bei welchen Ereignissen die Datenschnittstelle Daten senden soll. Jeder Ereignis-Typ löst bei verschiedenen Aktionen in SmartRace aus. Welche Aktionen das sind, sieht Du im Folgenden:

• Runde: Ein Fahrzeug beendet eine Runde. Die erste Überfahrt von Start-/Ziel löst dieses Ereignis nicht aus.
• Event: Ein neues Event (Qualifying/Rennen) wird gestartet oder beendet oder der Event-Status ändert sich (z.B. Unterbrechung, Fehlstart, etc.)
• Wetter: Wetteränderungenen und Änderungsankündigungen („es wird bald regnen“, etc.)
• VSC: Aktivieren und Deaktivieren des virtuellen Safety-Cars.
• Strafe: Erteilen und Absitzen von Strafen
• Schaden: Erhalten und Reparieren von Schäden
• Tanken: Updates zum Tankinhalt
• Boxenstopps: Reifenwechsel und Ein-/Ausfahrt in die Box
• Verschiedenes: Verschiedene Informationen und Ereignisse (siehe unten)

Gesendete Daten

Die Struktur der gesendeten Daten ist für jedes Ereignis identisch und so aufgebaut:

{
  "time": 1684769957969, // Uhrzeit des Ereignisses als Unix-Timestamp
  "event_type": "ui.lap_update", // Name des Ereignisses
  "event_data": {
      // Die Daten des Ereignisses, siehe unten
  }
}

{
    "controller_id": "1",
    "lap": 1,
    "laptime": "0:13.861",
    "laptime_raw": 13861,
    "sector_1": "0:06.305",
    "sector_1_pb": true,
    "sector_2": "0:03.224",
    "sector_2_pb": true,
    "sector_3": "0:04.332",
    "sector_3_pb": true,
    "lap_pb": true,
    "driver_data": {
        "id": 2,
        "name": "Marc",
        "name_tts": "",
        "active": "yes",
        "start_no_text_style": "normal",
        "team": "-",
        "name_short": null,
        "image": "",
        "start_no": "",
        "start_no_color_border": "rgb(68, 68, 68)",
        "start_no_color_background": "rgb(68, 68, 68)",
        "start_no_color_text": "rgb(68, 68, 68)"
    },
    "car_data": {
        "color": "rgb(176, 243, 0)",
        "brakes": null,
        "active": "yes",
        "tags": "[]",
        "decoder_type": "Carrera (default)",
        "image": "cdvfile:\/\/localhost\/persistent\/1684000048302.jpg",
        "laps": 5,
        "fuel": null,
        "speed": null,
        "tyres": "Ortmann",
        "digital_analog": "digital",
        "name": "Porsche 911 RSR Grello (911)",
        "manufacturer": "Carrera",
        "id": 40,
        "interval_counter": 0,
        "scale": "1:24",
        "magnets": "yes",
        "logo": "porsche.png",
        "changed_on": null,
        "interval": 0,
        "sound": "-",
        "comment": ""
    },
    "controller_data": {
        "color_bg": "rgb(176, 243, 0)",
        "color_text": "#000"
    }
}

{
    "type": "race",
    "laps": "50"
}

{
    "type": "race",
    "duration": "600"
}

{
    "type": "race",
    "result": {
        "1": {
            "driver_id": 2,
            "car_id": 39,
            "controller_id": 1,
            "laps": 33,
            "best_laptime": 4915,
            "pitstops": 0,
            "gap": "",
            "disqualified": false,
            "retired": false
        },
        "2": {
            "driver_id": 2,
            "car_id": 3,
            "controller_id": 3,
            "laps": 29,
            "best_laptime": 4914,
            "pitstops": 1,
            "gap": "+4 Lap(s)",
            "disqualified": false,
            "retired": false
        },
        "3": {
            "driver_id": 14,
            "car_id": 33,
            "controller_id": 4,
            "laps": 27,
            "best_laptime": 4925,
            "pitstops": 0,
            "gap": "+6 Lap(s)",
            "disqualified": false,
            "retired": false
        }
    }
}

{
    "old": "running",
    "new": "ended"
}

	
{
    "controller_id": "2",
    "penalty": 10
    // Wird angereichert mit driver_data, car_data und controller_data, siehe ui.lap_update
}

	
{
    "controller_id": "2",
    "damage": "engine"
    // Wird angereichert mit driver_data, car_data und controller_data, siehe ui.lap_update
}

	
{
    "controller_id": "2",
    "fuel": 50
    // Wird angereichert mit driver_data, car_data und controller_data, siehe ui.lap_update
}

	
{
    "controller_id": "2",
    "tire": "dry"
    // Wird angereichert mit driver_data, car_data und controller_data, siehe ui.lap_update
}

	
{
    "length": "",
    "reference_lap_time": null,
    "track_svg": null,
    "maximum_lap_time": "",
    "id": 7,
    "image": "cdvfile:\/\/localhost\/documents\/1570470682256.jpg",
    "pitstop_delta": "25000",
    "name_short": null,
    "name": "Demo Circuit",
    "minimum_lap_time": ""
}

Daten verarbeiten

Das entgegennehmende Script kann von beliebiger Art sein. Hier als Beispiel ein PHP-Script:

<?php

header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Headers: *");

if ($_SERVER['REQUEST_METHOD'] == 'POST'):

    $json_data = json_decode(file_get_contents('php://input'));
    print_r($json_data);

endif;

?>

CORS-Probleme

SmartRace läuft in einem Webview und meldet sich bei dem Webserver, der die Daten der Datenschnittstelle entgegennimmt, wahrscheinlich mit einem Host wie http://localhost. Möglicherweise erlaubt Dein Webserver aufgrund seiner CORS-Policies aber nicht, Daten von einem lokalen bzw. abweichenden Host entgegenzunehmen. In diesem Fall hilft es, über die Webserver-Konfiguration entsprechende Header zu setzen. Für Apache lauten diese Header z.B. wie folgt:

Header set Access-Control-Allow-Origin "*"
Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
Header set Access-Control-Allow-Headers "x-test-header, Origin, X-Requested-With, Content-Type, Accept"