Verbinden-Ablauf für Plugins

So läuft es ab

1. Ihr Plugin öffnet https://app.my-store-locator.com/connect mit den Parametern platform, return_url und state.
2. Die Person meldet sich an oder registriert sich. Die Anfrage bleibt dabei 60 Minuten lang erhalten - auch bei Zwei-Faktor-Anmeldung, Anmeldelink per E-Mail und Bestätigung der E-Mail-Adresse.
3. Die App zeigt „WordPress mit My Store Locator verbinden“ (mit dem Namen Ihrer Plattform) und die Adresse, zu der es zurückgeht: „Sie werden zurückgeleitet zu shop.example.com“.
4. Die Person wählt eine Karte. Wer noch keine hat, legt hier die erste an.
5. Nach Verbinden geht der Browser zurück zu Ihrer return_url, ergänzt um msl_token, msl_map und state.

Ein Geheimnis wird nicht ausgetauscht: Karten-Tokens sind öffentlich, sie stehen in jedem Einbettungscode. Der Ablauf funktioniert in jedem Tarif, auch im kostenlosen.

Der Aufruf

https://app.my-store-locator.com/connect?platform=wordpress&return_url=https%3A%2F%2Fshop.example.com%2Fwp-admin%2Fadmin.php%3Fpage%3Dmsl&state=4f9c2a7e1b8d4c6f

Erlaubte Werte für platform: wordpress, woocommerce, shopify, shopware, typo3, joomla, drupal, wix, webflow, framer, zapier, n8n, make und other für alles andere. Ihre Plattform fehlt? Nehmen Sie other und schreiben Sie uns.

Die Rückkehr

https://shop.example.com/wp-admin/admin.php?page=msl&msl_token=a1b2c3d4e5f6a7b8&msl_map=Filialen&state=4f9c2a7e1b8d4c6f

Vorhandene Parameter und ein Fragment Ihrer return_url bleiben erhalten. Nur msl_token, msl_map und state werden gesetzt oder ersetzt.

Was Ihr Plugin prüfen sollte

• state: Erzeugen Sie vor dem Aufruf einen zufälligen Wert, speichern Sie ihn in der Sitzung und vergleichen Sie ihn bei der Rückkehr. So erkennen Sie Rücksprünge, die Ihr Plugin nicht selbst ausgelöst hat.
• Token: Prüfen Sie msl_token gegen ^[A-Za-z0-9_-]{6,64}$, bevor Sie ihn speichern.
• Berechtigung: Speichern Sie den Token nur, wenn die angemeldete Person in Ihrem System die Einstellung ändern darf.

Beispiel in PHP:

// 1. Button "Mit My Store Locator verbinden"
$state = bin2hex(random_bytes(16));
$_SESSION['msl_state'] = $state;
$url = 'https://app.my-store-locator.com/connect?' . http_build_query([
    'platform'   => 'wordpress',
    'return_url' => 'https://shop.example.com/wp-admin/admin.php?page=msl',
    'state'      => $state,
]);

// 2. Rückkehr auf return_url
$expected = $_SESSION['msl_state'] ?? '';
unset($_SESSION['msl_state']);
if ($expected === '' || !hash_equals($expected, (string) ($_GET['state'] ?? ''))) {
    exit('Ungültige Anfrage');
}
$token = (string) ($_GET['msl_token'] ?? '');
if (!preg_match('/^[A-Za-z0-9_-]{6,64}$/', $token)) {
    exit('Ungültiger Token');
}
// $token speichern, $_GET['msl_map'] als Anzeigename

Fehler und Abbruch

Ungültige Anfragen leiten nie weiter. Die App zeigt dann eine Fehlerseite, zum Beispiel „Die Rücksprung-Adresse muss mit https:// beginnen.“

Ob Ihre Parameter stimmen, können Sie vorher prüfen - ohne Anmeldung:

curl "https://app.my-store-locator.com/api/v1/connect/check?platform=wordpress&return_url=https%3A%2F%2Fshop.example.com%2Fcb&state=abc123"

{ "ok": true, "platform": "wordpress", "name": "WordPress", "host": "shop.example.com" }

Bei Fehlern kommt HTTP 400 mit error = bad_platform, bad_state oder bad_return_url. Bei bad_return_url nennt data.reason den Grund: missing, scheme, too_long oder invalid.

Bricht die Person ab, landet sie im Dashboard der App - es gibt keinen Rücksprung zu Ihrem Plugin. Bieten Sie den Button deshalb jederzeit erneut an und zusätzlich ein Feld, in das man den Token oder den Einbettungscode einfügen kann (siehe Token aus einer Eingabe lesen).

Gut zu wissen

• Die angemeldete Person braucht das Recht, Karten anzusehen. Im Demo-Konto ist Verbinden nicht möglich.
• Auch Entwürfe lassen sich wählen. Öffentlich sichtbar ist die Karte erst, wenn sie in der App veröffentlicht ist. Eine Karte, die direkt im Verbinden-Ablauf angelegt wird, ist sofort veröffentlicht, wenn die Person das Recht dazu hat - anfangs noch ohne Standorte.
• Jede Verbindung steht im Protokoll des Kontos („Plattform verbunden“, mit Karte und Ziel-Host).
• Neue Konten, die über den Ablauf entstehen, merken sich Ihre Plattform als Quelle der Anmeldung.

Links aus Ihrem Plugin

Wenn Ihr Plugin auf unsere Website oder die Registrierung verlinkt, hängen Sie bitte Kampagnen-Parameter an:

https://app.my-store-locator.com/#/register?utm_source=wordpress
https://my-store-locator.com/?utm_source=wordpress&utm_medium=integration&utm_campaign=wordpress-plugin

Für die Datenschutzhinweise Ihres Plugins: Die Karte kommt von app.my-store-locator.com (Hosting in Deutschland). Beim Laden der Karte wird die IP-Adresse der Besucher an unseren Server übertragen. Unsere Datenschutzerklärung finden Sie unter /datenschutz/.