JKz-Login
Accounts, Tokens & Spielerprofile

1. Überblick

JKz-Login erlaubt Spielern, sich in externen Spielen mit ihrem JKz-Account anzumelden. Entwickler erhalten dadurch eine stabile Nutzer-ID, einen Anzeigenamen und öffentliche Profildaten, ohne eigene Accountsysteme bauen zu müssen.

Technisch basiert JKz-Login auf OAuth2/OpenID Connect mit PKCE. Für Browser-Spiele wird ein Redirect-Callback genutzt. Der Token-Tausch läuft über die JKz-API, damit Entwickler keinen geheimen Key im Spielclient speichern müssen.

2. Voraussetzungen

• Ein Spiel im DeveloperPortal.
• Ein JKz-Login Client im Tab JKz-Login.
• Eine erlaubte Return URL oder der JKz-Callback für Spiele ohne eigene Domain.
• Eine heruntergeladene SDK-Datei aus dem DeveloperPortal.

3. Login-Client erstellen

Im DeveloperPortal wählst du zuerst dein Spiel aus und erstellst dann einen Login-Client. Der Client wird automatisch in Keycloak angelegt und auf das gewählte Spiel begrenzt.

• Name: Anzeigename für dich im Portal.
• Return URLs: Erlaubte Zieladressen nach dem Login.
• Scopes: Berechtigungen wie openid, profile, optional email, gamecloud.
• Datenschutzlink: Link zu deiner Datenschutzerklärung, falls dein Spiel eigene Daten verarbeitet.
• Nutzungsbedingungen: Link zu deinen Spielbedingungen, falls vorhanden.

4. Redirects & Callback

HTML5-Spiele ohne eigene Domain können den JKz-Callback nutzen:

https://jkz-games.de/game-auth/callback/{GAME_UUID}/

Spiele mit eigener Domain können eigene Return URLs eintragen. Die URL muss exakt zur späteren Redirect-Adresse passen, inklusive Protokoll, Pfad und abschließendem Slash, falls verwendet.

https://dein-spiel.example/callback/
https://dein-spiel.example/auth/jkz/return

5. SDK einbinden

Lade die generierte SDK im DeveloperPortal herunter und binde sie in dein Spiel ein. Die SDK enthält bereits Game UUID, Client ID und API-/Callback-Adressen.

<script src="./mein-spiel-jkz-sdk.js"></script>

Wenn du zusätzlich GameCloud oder GameServer nutzt, muss dieselbe Login-SDK zuerst Tokens bereitstellen.

6. Login-Flow

Der Login startet durch eine Nutzeraktion, zum Beispiel einen Button. Nach erfolgreichem Login ruft die SDK deinen Callback auf.

document.getElementById("loginBtn").addEventListener("click", async () => {
    await JKzLogin.login();
});

JKzLogin.listenForCallback(
    async tokens => {
        JKzLogin.setTokens(tokens);
        console.log("Login erfolgreich", tokens.scope);
    },
    error => {
        console.error("Login fehlgeschlagen", error);
    }
);

7. Profildaten laden

Nach dem Login kann das Spiel öffentliche Profildaten des eingeloggten Nutzers laden. Dazu gehören typischerweise Nutzer-ID, Username, Anzeigename und Profilbild.

const profile = await JKzLogin.me();

console.log(profile.user.id);
console.log(profile.user.username);
console.log(profile.user.displayName);
console.log(profile.user.avatarUrl);

Die stabile Nutzer-ID ist die wichtigste Referenz für GameCloud-Daten, Spielstände, Matchteilnehmer und externe Backends.

8. Scopes & Consent

Datenschutz- und Nutzungsbedingungen des Entwicklerclients können im Consent angezeigt werden. Hinterlege dort nur Links, die für den Spieler erreichbar und aktuell sind.

9. Token-Handling

Access Tokens sind kurzlebige Berechtigungsnachweise. Speichere sie nicht dauerhaft im Spielcode und logge sie nicht. Für HTML5-Spiele ist RAM oder sessionStorage besser als localStorage.

const tokens = JKzLogin.getTokens();

if (tokens && tokens.access_token) {
    JKzGameServer.setTokens(tokens);
    JKzCloud.setTokens(tokens);
}

Wenn ein Token abläuft, sollte das Spiel den Nutzer erneut anmelden oder, falls von der SDK unterstützt, ein Refresh durchführen.

10. Desktop & Mobile

Desktop- und Mobile-Spiele können den gleichen Login technisch nutzen, benötigen aber einen geeigneten Redirect-Mechanismus. Übliche Varianten sind ein lokaler Loopback-Callback, ein Custom URI Scheme oder ein Web-Callback, der das Spiel wieder öffnet.

• HTML5: JKz-Callback oder eigene HTTPS-Return-URL.
• Desktop: Systembrowser öffnen, Callback über localhost oder Custom Scheme empfangen.
• Mobile: Systembrowser oder In-App-Browser mit Deep Link zurück zur App.

11. Datenschutz

Wenn dein Spiel JKz-Login nutzt, verarbeitet es personenbezogene Daten wie Nutzer-ID und Profilname. Wenn du weitere Daten erhebst, musst du den Nutzer transparent informieren und nur notwendige Scopes aktivieren.

• Datenschutzerklärung im Client hinterlegen.
• Nur Scopes aktivieren, die dein Spiel tatsächlich benötigt.
• Tokens und Profildaten nicht unnötig lange speichern.
• Nutzer nicht außerhalb des erklärten Zwecks tracken.

12. Häufige Fehler

• Redirect URI ungültig: Return URL stimmt nicht exakt mit dem Client überein.
• Token user id missing: Alte SDK oder fehlende ID-Auswertung; frische SDK herunterladen.
• Scope fehlt: Scope im Client aktivieren, SDK neu herunterladen und neu einloggen.
• Popup blockiert: Login direkt aus einem Button-/Touch-Event starten.