Connect-Dokumentation

Ein Konto für deine Shops

Mit dem SDK melden sich Kunden im Shop mit ihrem App-Konto an. Diese Dokumentation beschreibt die Methoden für unterstützte Shops.

Im zentralen Dialog können Kunden sich anmelden oder ein Konto erstellen. Die Oberfläche unterstützt derzeit Französisch und Englisch; diese Dokumentation ist hingegen in zwölf Sprachen verfügbar.

Anmeldung einbauen

In einem unterstützten Shop ist window.rankappConnect bereits geladen und eingerichtet. Verwende drei Methoden: login(), getSession() und logout(). Eine weitere Installation ist nicht nötig. Das vollständige Beispiel ergänzt nur Schaltflächen und zugängliche Statusmeldungen.

Rufe login() direkt beim Klick auf. Das Promise liefert {status: "success", session}, {status: "cancelled"} oder {status: "redirecting"}. Fehler lehnen das Promise mit einem stabilen Code ab. Mobil oder bei blockierten Popups erfolgt eine Weiterleitung. returnTo muss im eigenen Shop bleiben.

const connect = window.rankappConnect;

function onSignInClick() {
  return connect.login({ returnTo: '/account' });
}

function readSession() {
  return connect.getSession();
}

function onSignOutClick() {
  return connect.logout();
}

<button type="button" id="connect-login">Mit RankAPP anmelden</button>
<button type="button" id="connect-logout" hidden>Abmelden</button>
<p id="connect-status" role="status" aria-live="polite"></p>

<script>
const connect = window.rankappConnect;
const login = document.querySelector('#connect-login');
const logout = document.querySelector('#connect-logout');
const status = document.querySelector('#connect-status');
const copy = {
  "cancelled": "Anmeldung abgebrochen. Du kannst es erneut versuchen.",
  "redirecting": "Weiterleitung zur Anmeldung…",
  "login": "Mit RankAPP anmelden",
  "logout": "Abmelden",
  "signedOut": "Du bist abgemeldet.",
  "signedIn": "Angemeldet: ",
  "error": "Anmeldung nicht verfügbar. Erneut versuchen.",
  "pending": "Anmeldung läuft…"
};
function render(session) {
  status.textContent = session.authenticated
    ? copy.signedIn + session.user.username : copy.signedOut;
  logout.hidden = !session.authenticated;
}
function failure() {
  status.textContent = copy.error;
}
function busy(value) {
  login.disabled = logout.disabled = value;
}
login.addEventListener('click', async () => {
  busy(true);
  status.textContent = copy.pending;
  let redirecting = false;
  try {
    const result = await connect.login({ returnTo: '/account' });
    if (result.status === 'success') render(result.session);
    else if (result.status === 'cancelled') status.textContent = copy.cancelled;
    else {
      redirecting = true;
      status.textContent = copy.redirecting;
    }
  } catch (error) { failure(); }
  finally { if (!redirecting) busy(false); }
});
logout.addEventListener('click', async () => {
  busy(true);
  try { render(await connect.logout()); }
  catch (error) { failure(); }
  finally { busy(false); }
});
busy(true);
connect.getSession().then(render).catch(failure)
  .finally(() => busy(false));
</script>

Sitzung anzeigen

getSession() liest den Server: {authenticated: false} bedeutet abgemeldet. Eine authentifizierte Sitzung enthält user (userId, username, avatarUrl, language) und bei verwalteten Shops orders. Beim Laden und nach Weiterleitungen aufrufen; die Identität niemals aus URL-Parametern ableiten.

Dienstfehler bleiben Fehler: STOREFRONT_SESSION_ERROR wird nicht als abgemeldete Sitzung behandelt. Zeige eine Meldung zum erneuten Versuch. login() unterscheidet Abbruch und Fehler; logout() beendet nur die Shop-Sitzung.

Identität und Cookies

Das SDK verlangt HTTPS für alle Websites und Endpunkte, auch bei lokaler Entwicklung. Verwende einen lokalen HTTPS-Server mit einem vom Browser als vertrauenswürdig eingestuften Zertifikat. HTTP wird für die Authentifizierung niemals akzeptiert.

Das Passwort wird auf auth.rankapp.io eingegeben, nicht auf der Händlerwebsite. Ein einmaliger Code und PKCE S256 binden den Dialog an die ursprüngliche Anfrage. Codeaustausch und Tokens bleiben auf dem Server. Die Abschlussnachricht des Popups enthält keine Tokens.

Sitzungscookies verwenden HttpOnly, Secure und SameSite=Lax. Jedes Cookie gilt nur für seinen eigenen Host, ohne gemeinsames Domain-Attribut. Zentrale Sitzung und einzelne Shop-Sitzungen sind getrennt. logout() beendet die Shop-Sitzung, nicht automatisch die zentrale Anmeldung.

Der Shop-Server

Diese Dokumentation beschreibt SDK 1.1.0. Verwende in einem kompatiblen Shop ausschließlich den vorkonfigurierten Client window.rankappConnect. Der Server verwaltet Anmeldung, Sitzung und Abmeldung; der Client übernimmt die erforderlichen signierten Anfragen. Auf deiner Seite musst du keine Endpunkte oder Adapter konfigurieren.

In der Vorschau testen

In der Vorschau kannst du echte Konten verwenden und An- sowie Abmeldung aus Kundensicht testen. Der private Zugriff auf den Entwurf benötigt eine separate Berechtigung: Das Öffnen der Vorschau meldet keinen Käufer automatisch an. Zahlungen sind dort deaktiviert.

Teste erfolgreiche Anmeldung, Abbruch, Schließen des Popups, mobile Rückkehr und erneute Anmeldung nach dem Abmelden. Im Produktivbetrieb muss der Shop veröffentlicht und erreichbar sein. Eine erfolgreiche Anmeldung bestätigt keine Zahlung; verarbeite den Zahlungsstatus getrennt.

Externe Integration vorbereiten

Für unabhängige externe Websites können derzeit noch keine Integrationen registriert werden. Dafür müssen zunächst Clients registriert, Rückkehr-URLs freigegeben und Zugriffsrechte festgelegt werden.

Erfinde keine vermeintlich kompatible client_id, keinen Token-Endpunkt und keine OIDC-Konfiguration. Der aktuelle Vertrag gilt für unterstützte Shops und ihren mitgelieferten Adapter. Halte Passwörter und Tokens aus dem Händler-JavaScript heraus und bestätige die Sitzung stets über den Server. Berücksichtige dabei auch Abbrüche und vorübergehende Fehler.