Wie lasse ich meine Nutzer ihre Gesundheitsdaten mit einem QR-Code verbinden?

Zeig jedem Nutzer einen QR-Code, in dem deine Webhook-Adresse und ein Schlüssel für diesen Nutzer stecken. Er scannt ihn mit der Life-Dashboard-App, tippt auf Koppeln, und von da an sendet sein Telefon Health-Connect-Daten, oder von einem iPhone Apple-Health-Daten, als signiertes JSON an deinen Dienst. Niemand tippt eine URL ab oder kopiert einen Schlüssel, und du weißt, dass es geklappt hat, weil die App sofort einen signierten Test-Ping sendet. Die Life-Dashboard-Integration für Home Assistant funktioniert genau so, und das Format ist offen. Jeder Dienst kann also dasselbe tun.

Dein Dienst zeigt einen QR-Code, das Telefon öffnet damit die Kopplungsseite, und nach dem Koppeln bekommt dein Dienst einen signierten Test-Ping

Von Owen Vogelaar, der Life Dashboard entwickelt 5 Min. Lesezeit

Kopplungsreferenz

Was ein Code kann

  • Eine Adresse und ihren Schlüssel eintragen. In den Bereichen, die du zulässt: Gesundheit, Bildschirmzeit oder beide. Der Nutzer kann einen Bereich auf der Kopplungsseite trotzdem ausschalten.
  • Nie Datentypen oder einen Zeitplan festlegen. Welche Daten gesendet werden und wie oft, bleibt die Entscheidung des Nutzers auf dem Telefon. Ein Code kann nicht heimlich die Herzfrequenz von jemandem irgendwohin senden lassen.
  • Nie andere Empfänger anfassen. Jede andere Adresse behält ihren eigenen Schlüssel und ihre Header, und eine durch Koppeln hinzugefügte Adresse beginnt ohne eigene Header.
  • Vor dem Koppeln nichts speichern. Die Kopplungsseite zeigt deinen Namen und den Host, an den die Daten gehen, entnommen aus der Adresse selbst.

Ein Code ist ein https-Link, bei dem alles hinter dem # steht:

https://owen282000.github.io/life-dashboard-companion-app/pair#v=1&url=<address>&secret=<secret>&name=<name>
FeldWert
v1, die Version des Formats. Pflicht.
urlDeine Webhook-Adresse, höchstens 2048 Zeichen, keine Leerzeichen, kein Komma. Pflicht.
secretDer HMAC-Signaturschlüssel für diesen Nutzer, höchstens 512 Zeichen, keine Leerzeichen. Pflicht.
nameWie die Kopplungsseite deinen Dienst nennt, bis zu 64 Zeichen. Optional.
sourceshealth_connect, screen_time oder beide, durch Komma getrennt. Lass es weg, um beide zuzulassen.

Kodiere jeden Wert vollständig mit Prozentzeichen, ein Leerzeichen als %20. quote(value, safe="") in Python und encodeURIComponent in JavaScript machen das; die Formularkodierung, die ein Leerzeichen als + schreibt, macht es nicht. Der Schlüssel steht mit Absicht im Fragment: Ein Browser sendet den Teil hinter dem # nie an einen Server. Scannt jemand den Code, ohne die App installiert zu haben, lädt also die Landingpage, aber der Schlüssel bleibt auf seinem Telefon.

Einen Code in Python erzeugen

import secrets
from urllib.parse import quote, urlencode

import segno

PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair"


def pairing_link(webhook_url, secret, name=None, sources=None):
    fields = {"v": "1", "url": webhook_url, "secret": secret}
    if name:
        fields["name"] = name
    if sources:
        fields["sources"] = ",".join(sources)
    return PAIR_PAGE + "#" + urlencode(fields, quote_via=quote, safe="")


secret = secrets.token_urlsafe(32)  # store this with the user
link = pairing_link("https://health.example.com/webhook/u/42", secret, name="Example Health")
segno.make(link, error="m").save("pairing.svg", scale=6, border=4)

Einen Code in Node.js erzeugen

import crypto from "node:crypto";
import QRCode from "qrcode";

const PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair";

function pairingLink(webhookUrl, secret, { name, sources } = {}) {
  const fields = [["v", "1"], ["url", webhookUrl], ["secret", secret]];
  if (name) fields.push(["name", name]);
  if (sources) fields.push(["sources", sources.join(",")]);
  return PAIR_PAGE + "#" + fields.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&");
}

const secret = crypto.randomBytes(32).toString("base64url"); // store this with the user
const link = pairingLink("https://health.example.com/webhook/u/42", secret, { name: "Example Health" });
const dataUrl = await QRCode.toDataURL(link, { errorCorrectionLevel: "M", margin: 4 });

Beide ergeben exakt den bekannten Testvektor, den die eigenen Tests der App prüfen und der in der Kopplungsreferenz steht. Nimm ihn als Unit-Test für deinen Generator.

Was der Nutzer sieht

Er scannt deinen Code in der App unter Kopplungscode scannen oder mit der Kamera des Telefons, die auf Android direkt die App öffnet. Eine Seite sagt „Example Health möchte deine Daten empfangen unter: health.example.com“, mit einem Schalter für jeden Bereich und den anderen Adressen, die ihren eigenen Schlüssel behalten. Nichts wird gespeichert, bis er auf Koppeln tippt.

Der Test-Ping nach dem Koppeln

Gleich nach Koppeln sendet die App einen Test-Ping an deine Adresse, signiert mit dem Schlüssel aus dem Code:

POST /webhook/u/42
Content-Type: application/json; charset=utf-8
X-Signature: sha256=<hex of HMAC-SHA256(secret, raw body)>

{
  "test": true,
  "message": "Test ping from Life Dashboard",
  "timestamp": "2026-10-04T12:00:00Z",
  "app_version": "1.29.0",
  "source": "health_connect"
}

Prüf die Signatur über den rohen Body, bevor du ihn parst, und antworte mit irgendeinem 2xx. Der Nutzer sieht dann auf der Seite nach dem Koppeln „Verbunden.“ oder bei der Einrichtung der App eine kurze Meldung mit „Test-Ping zugestellt“. Antworte auf eine falsche Signatur mit 401, wie bei jeder Anfrage danach. Ein Ping enthält keine Daten. Er ist also ein guter Moment, den Nutzer als verbunden zu markieren, und nichts, was du speichern musst. Jede Synchronisierung danach nutzt denselben Schlüssel und denselben Payload, beschrieben in der Anleitung zum Webhook.

iPhone

Life Dashboard für iPhone liest dieselben Codes. Die App sendet nur Apple Health, ein Code muss also health_connect zulassen oder sources weglassen. Einfaches http:// funktioniert dort nur zu einer Adresse im Heimnetz, nimm also https. Die Kamera des iPhones öffnet zuerst die Landingpage, die den Code über den Button Open in the app an die App übergibt.

So bleibt es sicher

  • Ein Schlüssel pro Nutzer, aus einem kryptografischen Zufallsgenerator, mindestens 32 Bytes.
  • Zeig den Code nur diesem Nutzer, nachdem er sich angemeldet hat. Wer ihn sieht, kann Daten in seinem Namen signieren.
  • Protokolliere den Link nie. Er enthält den Schlüssel.
  • Lass Nutzer den Schlüssel wechseln. Ein neuer Schlüssel bedeutet einen neuen Code; wird er gescannt, ersetzt er den alten Schlüssel auf dem Telefon.

Life Dashboard

Erzeuge einen Code für einen Testnutzer und scanne ihn mit der App. Die Kopplungsreferenz enthält jede Regel, den Testvektor und die Unterschiede beim iPhone.

Jetzt bei Google Play

4,99 € einmalig bei Google Play, mit automatischen Updates.

Oder kostenlos, dieselbe App mit demselben Signaturschlüssel: APK auf GitHub · Obtainium · F‑Droid

Laden im App Store

6,99 € einmalig im App Store, ohne Abo.

Mit Xcode bauen

Kopplungsreferenz Payload-Referenz

Die Open-Source-Apps, die diese Anleitung verwendet, für Android und iPhone. Kein Konto, keine Cloud. Mehr zu Android und iPhone.

Häufige Fragen

Brauchen meine Nutzer ein Konto bei Life Dashboard?

Nein. Es gibt keinen Life-Dashboard-Server und kein Konto. Das Telefon sendet direkt an die Adresse in deinem Code.

Kann ein Code bestimmen, welche Gesundheitsdaten mein Dienst bekommt?

Nein. Ein Code trägt nur die Adresse und den Schlüssel ein. Der Nutzer wählt die Datentypen und den Zeitplan auf dem Telefon, die Einwilligung bleibt also bei ihm.

Kann ich den Payload in meinem eigenen Format bekommen?

Nein. Jeder Empfänger bekommt dasselbe signierte JSON, beschrieben durch ein JSON-Schema, und dein Dienst bildet es auf sein eigenes Modell ab. Erst ein einziges dokumentiertes Format sorgt dafür, dass jeder Empfänger ohne Plugin funktioniert.

Was, wenn der Nutzer scannt, ohne die App installiert zu haben?

Der Link öffnet eine Seite, die sagt, wo es die App gibt, für Android oder iPhone. Der Schlüssel im Link erreicht den Server dieser Seite nie.