Referenz zum Einrichtungsassistenten

Dieses Dokument ist eine Referenz für den ersten Setup-Assistenten des ADP Car Market Hub-Plugins. Der Assistent ist ein sechsstufiger Onboarding-Prozess im Enterprise-Stil, der einem WordPress-Administrator hilft, die häufigsten Konfigurationsaufgaben direkt nach der ersten Aktivierung zu erledigen.

Der Assistent ist optional. Jede Option, die er bietet, kann auch manuell über die regulären Admin-Tabs konfiguriert werden, die an anderer Stelle in der Admin-Referenz dokumentiert sind. Für die empfohlene Reihenfolge der Ersteinrichtung siehe Erste Einrichtung.

Wann Sie dieses Dokument lesen sollten

Lesen Sie dies, wenn Sie Folgendes tun müssen:

• Verstehen, wann und wie der Willkommenshinweis für den Setup-Assistenten erscheint.
• Wissen, wie Sie den Assistenten starten, überspringen oder fortsetzen.
• Den Unterschied zwischen Demo-Setup und Live-AutoScout24-Setup verstehen.
• Wissen, welche Optionen der Assistent schreibt und welche Optionen er niemals stillschweigend überschreibt.
• Das Sicherheitsmodell verstehen (Berechtigungs- und Nonce-Schutz, Handhabung des Client Secret).
• Den Assistenten für eine interne Übergabe oder ein Kunden-Onboarding-Verfahren dokumentieren.

Übersicht

Der Assistent ist als versteckte Admin-Seite registriert unter:

wp-admin/admin.php?page=as24ci-setup-wizard

Er ist nicht im Car Market Hub-Untermenü aufgeführt. Einstiegspunkte sind:

• Der Admin-Hinweis Willkommen bei ADP Car Market Hub, der nach der ersten Aktivierung erscheint.
• Der Link Setup-Assistenten ausführen oben auf Car Market Hub → Dashboard.
• Die Karte Setup-Assistent oben auf Car Market Hub → Tools.

Der Assistent leitet nach der Aktivierung niemals automatisch weiter. Der Admin-Hinweis dient der Information und bietet zwei Schaltflächen: Setup-Assistenten starten und Vorerst überspringen.

Anforderungen oder Voraussetzungen

• Ein WordPress-Benutzer mit der Verwaltungsberechtigung des Plugins (Plugin::CAP_MANAGE).
• Ein Zeitstempel der Erstaktivierung, der durch den Aktivierungs-Hook des Plugins aufgezeichnet wurde. Bestehende Installationen, die ohne Reaktivierung aktualisiert werden, sehen den Willkommenshinweis nicht, können den Assistenten aber dennoch manuell über das Dashboard oder den Tools-Tab öffnen.
• Für das Live-Setup: AutoScout24-API-Zugangsdaten (Client ID, Client Secret, Seller ID, API-Basis-URL).
• Für das Demo-Setup: Es sind keine API-Zugangsdaten erforderlich.

Ablauf des Assistenten

Schritt 1 — Modus

Wählen Sie zwischen zwei Setup-Pfaden:

• Demo-Setup — installiert eine kuratierte Auswahl an Demofahrzeugen, wendet demofreundliche Standardwerte an und aktiviert die Analytics-Option vorab, damit die Dashboard- und Analytics-Seiten Daten zum Anzeigen haben. Das Demo-Setup ist ein expliziter Reset- und Seed-Vorgang: Es löst am Ende den bestehenden Demo_Data::install()-Pfad aus.
• Live-AutoScout24-Setup — speichert echte AutoScout24-Zugangsdaten sowie die ausgewählten Seiten und Funktions-Toggles, installiert jedoch keine Demodaten und aktiviert Analytics nicht vorab.

Schritt 1 erfasst auch das Land der Garage (DE, CH, AT, Andere), die Standard-Währung (EUR, CHF) und die Admin-Sprache (Website-Standard plus eine kleine explizite Allowlist).

Schritt 2 — Garagenprofil

Erfasst die grundlegende Identität der Garage, die von anderen Teilen des Plugins verwendet wird: Name, Strasse, Postleitzahl, Ort, Land, Telefon, E-Mail, Website und eine Logo-Medien-ID. Alle Felder sind optional. Übermittelte Werte werden bereinigt; leer gelassene Felder behalten den bestehenden gespeicherten Wert bei (kein Feld wird stillschweigend geleert).

Schritt 3 — AutoScout24

Erfasst die AutoScout24-API-Verbindung: Client ID, Client Secret, Seller ID und API-Basis-URL. Im Demo-Modus zeigt dieser Schritt einen Hinweis zum Überspringen; im Live-Modus werden Zugangsdaten empfohlen.

Das Feld Client Secret wird absichtlich leer gerrendered. Der Assistent schreibt das gespeicherte Secret niemals in das Admin-HTML zurück. Das Absenden des Formulars mit leerem (oder nur aus Leerzeichen bestehendem) Feld behält das bestehende gespeicherte Secret bei. Das Absenden eines nicht leeren Wertes ersetzt es. Dieselbe Regel gilt für den regulären Einstellungen-Tab — siehe Settings Reference.

Die Basis-URL wird mit einer http/https-Allowlist abgeglichen; andere Schemata (zum Beispiel javascript:) werden abgelehnt.

Schritt 4 — Seiten

Für jede öffentlich zugängliche Seite bietet der Assistent drei Modi an:

• Automatisch erstellen — wp_insert_post() wird mit post_type=page, post_status=publish, dem kanonischen Titel und dem kanonischen Shortcode als Seiteninhalt aufgerufen. Zuerst wird eine Titelsuche durchgeführt, um die Erstellung eines Duplikats zu vermeiden, wenn bereits eine Seite mit demselben Titel existiert.
• Bestehende Seite verwenden — der Administrator gibt die Post-ID einer bestehenden Seite ein und die entsprechende Option (as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id) wird aktualisiert.
• Überspringen — die Seite wird nicht erstellt und der bestehende Optionswert wird beibehalten.

Kanonische Seiten und Shortcodes:

Wenn die Option bereits auf eine bestehende Seite verweist (get_post() gibt eine veröffentlichte Seite zurück), behält der Assistent diese bei und erstellt kein Duplikat. Der Assistent löscht niemals bestehende Seiten.

Suchabos haben im Assistenten absichtlich keine öffentliche Seite. Suchabo-Abonnements werden über die Filter-Sidebar von [as24ci_archive] und über den Admin-Tab Search Alerts Reference verwaltet.

Schritt 5 — Funktionen

Schaltet die gängigsten Standardfunktionen ein oder aus. Jedes Toggle wird mit einer expliziten Markierung für das Vorhandensein aufgezeichnet, sodass das erneute Ausführen des Assistenten auf halbem Weg niemals eine Einstellung löscht, die nicht auf dem Formular vorhanden war:

• Social-Sharing-Buttons
• PDF datasheet
• QR-Code im PDF
• Betriebskosten pro 100 km
• Vergleichen
• Favoriten
• Suchabos
• Analytics-Tracking

Im Demo-Modus ist das Analytics-Toggle vorab aktiviert. Im Live-Modus ist es deaktiviert, es sei denn, der Administrator aktiviert es explizit.

Hintergrund-Standardwerte, auf die sich der Assistent verlässt (Platzierung des Social Sharings, das vollständige Netzwerk-Set, Archiv-Layout = beide, Listen-Auszug = 150), werden nur dann eingespielt, wenn die entsprechende Option fehlt; bestehende Werte werden beibehalten.

Schritt 6 — Fertigstellen

Eine schreibgeschützte Zusammenfassung der getroffenen Entscheidungen. Im Demo-Modus ist die Schaltfläche zum Fertigstellen mit Demodaten installieren und fertigstellen beschriftet und löst den bestehenden Demo_Data::install()-Pfad aus. Im Live-Modus speichert die Schaltfläche zum Fertigstellen nur die gesammelten Einstellungen des Assistenten.

Nach einem erfolgreichen Abschluss:

• as24ci_setup_wizard_completed wird gesetzt.
• as24ci_setup_completed_at wird auf einen ISO-8601 UTC-Zeitstempel gesetzt.
• as24ci_setup_completed_by wird auf die WordPress-Benutzer-ID gesetzt.
• Der Administrator wird mit einer Erfolgsmeldung zurück zum Dashboard geleitet.

Verhalten des Admin-Hinweises

Der Willkommenshinweis wird nur gerendert, wenn alle folgenden Bedingungen erfüllt sind:

• Der aktuelle Benutzer verfügt über die Verwaltungsberechtigung des Plugins.
• as24ci_setup_first_activation_at existiert (wird von Plugin::activate() nur aufgezeichnet, wenn es fehlt, sodass bestehende Installationen, die ohne Reaktivierung aktualisiert werden, nicht bedrängt werden).
• as24ci_setup_wizard_completed ist nicht gesetzt.
• as24ci_setup_wizard_skipped is nicht gesetzt.
• Der aktuelle Bildschirm ist nicht die Seite des Assistenten selbst.

Es werden zwei Schaltflächen angeboten:

• Setup-Assistenten starten öffnet den Assistenten.
• Vorerst überspringen sendet an admin-post.php?action=as24ci_setup_wizard_skip (mit Berechtigungs- und Nonce-Prüfungen). Es setzt as24ci_setup_wizard_skipped=1 und leitet zurück zum Dashboard. Der Hinweis erscheint bei nachfolgenden Ladevorgängen von Admin-Seiten nicht mehr.

Der Assistent erzwingt nach der Aktivierung niemals eine Weiterleitung.

Konfigurations-Referenz

Status-Optionen

Optionen für das Garagenprofil

as24ci_dealer_name, as24ci_dealer_street, as24ci_dealer_postal_code, as24ci_dealer_city, as24ci_dealer_country, as24ci_dealer_phone, as24ci_dealer_email, as24ci_dealer_website, as24ci_dealer_logo_id, as24ci_dealer_language.

Bestehende Optionen, die der Assistent beschreiben kann

CLIENT_ID, CLIENT_SECRET, SELLER_IDS, BASE_URL, DEFAULT_CURRENCY, FEATURE_SOCIAL_SHARE, SOCIAL_SHARE_PLACEMENT, SOCIAL_SHARE_NETWORKS, FEATURE_PDF_DATASHEET, FEATURE_COMPARE, FEATURE_FAVORITES, FEATURE_SEARCH_AGENT, ANALYTICS_ENABLED, ENVKV_SHOW_COSTS_100KM, PDF_MANAGER_SETTINGS (show_qr-Schlüssel), DESIGN_ARCHIVE_LAYOUT, ARCHIVE_LIST_EXCERPT_LENGTH, as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id.

Der Assistent aktualisiert nur Optionen, deren Formularfelder tatsächlich in den übermittelten POST-Daten enthalten sind. Nicht übermittelte Felder behalten ihren bestehenden Wert.

Sicherheit

• Berechtigungsprüfung. Jeder Einstiegspunkt (die Seite des Assistenten, der Handler zum Speichern des Formulars und der Handler zum Überspringen) ruft current_user_can( Plugin::CAP_MANAGE ) auf und bricht mit wp_die() ab, wenn die Berechtigung fehlt.
• Nonces. Das Speichern des Formulars verwendet wp_nonce_field() / check_admin_referer(); die URL zum Überspringen verwendet wp_nonce_url() / check_admin_referer().
• Client Secret. Das gespeicherte Secret wird niemals im Admin-HTML gerendert. Leere oder nur aus Leerzeichen bestehende Übermittlungen behalten den gespeicherten Wert bei.
• URL-Validierung. Die Basis-URL und die Website der Garage müssen das Schema http oder https verwenden; andere Schemata werden abgelehnt.
• E-Mail-Validierung. Die E-Mail-Adresse der Garage wird mit is_email() validiert. Ungültige Eingaben behalten stillschweigend den bestehenden Wert bei; eine leere Übermittlung löscht ihn.
• Bereinigung. Modus, Land, Währung, Sprache und Seitenmodus werden mit expliziten Allowlists abgeglichen. Textfelder verwenden sanitize_text_field(). Seiten-IDs verwenden absint().
• Ausgabe-Escaping. Jeder dynamische Wert, der vom Assistenten gerendert wird, verwendet esc_html, esc_attr oder esc_url.

Betriebliche Hinweise

• Der Assistent ändert niemals Einstellungen bei der Aktivierung des Plugins. Die Aktivierung spielt nur zerstörungsfreie Standardwerte über add_option() ein.
• Der Assistent ändert niemals Einstellungen, wenn ein Schritt geladen wird — Einstellungen werden nur aktualisiert, wenn der Administrator einen Schritt absendet.
• Das Demo-Setup bleibt ein expliziter Reset- und Seed-Vorgang: Es setzt demo-gesteuerte Optionen bewusst zurück und fügt Demofahrzeuge ein. Verwenden Sie es nur auf dedizierten Demo- oder Test-Websites.
• Das Live-Setup ist in Bezug auf Fahrzeuge und Kundeneinstellungen zerstörungsfrei. Es speichert die vom Assistenten ausgewählten Einstellungen und Seiten, installiert jedoch keine Demodaten.
• Analytics ist nur im Demo-Modus vorab aktiviert. Im Live-Modus ist das Toggle ein Opt-in. Siehe Analytics Retention für Datenschutzüberlegungen.
• Der Assistent führt keine KI-Bereitstellung, automatischen Importe, Zeitpläne oder vollständigen Synchronisierungen durch. Diese werden später in den entsprechenden Admin-Tabs konfiguriert.
• Der Assistent ist kein Ersatz für ein Cookie-Consent-Tool, eine CMP, eine Datenschutzerklärung oder eine rechtliche Prüfung. Aktivieren Sie Analytics auf einer Live-Website erst, nachdem diese Anforderungen überprüft wurden.

---

Fehlerbehebung

• Der Willkommenshinweis erscheint nicht. Der Wizard wurde entweder abgeschlossen (as24ci_setup_wizard_completed) oder übersprungen (as24ci_setup_wizard_skipped), dem aktuellen Benutzer fehlt die Berechtigung zur Verwaltung oder der Zeitstempel der Erstaktivierung wurde nicht aufgezeichnet (typisch bei Upgrades, die keine Neuaktivierung ausgelöst haben). Öffnen Sie den Wizard stattdessen über Car Market Hub → Tools → Setup Wizard.
• Ich habe den Wizard übersprungen. Wie öffne ich ihn wieder? Verwenden Sie den Link Setup Wizard ausführen auf Car Market Hub → Dashboard oder die Karte Setup Wizard auf Car Market Hub → Tools.
• Der Wizard hat meine Seiten nicht erstellt. Eine Seite mit demselben Titel existierte bereits und wurde wiederverwendet, oder die Option Überspringen wurde für diese Seite in Schritt 4 ausgewählt. Öffnen Sie Pages in WordPress und überprüfen Sie dies. Der Wizard löscht niemals Seiten.
• Das Feld Client Secret ist leer, wenn ich Schritt 3 erneut öffne. Das ist so gewollt. Das gespeicherte Secret wird im Formular niemals wieder angezeigt. Wenn Sie das Feld leer lassen, bleibt der gespeicherte Wert erhalten.
• Analytics ist nach der Live-Einrichtung nicht aktiviert. Im Live-Modus ist der Analytics-Schalter ein Opt-in. Öffnen Sie den Wizard erneut und aktivieren Sie ihn in Schritt 5, oder aktivieren Sie ihn auf dem Analytics-Tab. Stellen Sie zuvor sicher, dass die Cookie-Einwilligung und die Datenschutzanforderungen erfüllt sind.
• Demodaten wurden nicht installiert. Stellen Sie sicher, dass Sie in Schritt 1 Demo-Einrichtung ausgewählt und in Schritt 6 auf Demodaten installieren und abschliessen geklickt haben. Die Live-Einrichtung installiert keine Demodaten.
• Vergleich oder Favoriten sind in der Demo leer. Vergleich und Favoriten basieren auf dem localStorage; die Demo stellt ein Fallback bereit, das den localStorage beim ersten Seitenaufruf befüllt. Öffnen Sie die Vergleichs- oder Favoritenseite einmal in derselben Browsersitzung, um das Befüllen auszulösen.
• Der Wizard überschreibt meine bestehenden Einstellungen nicht. Richtig. Der Wizard schreibt nur Optionen, deren Formularfelder abgesendet werden. Ein erneutes Ausführen des Wizards überschreibt niemals unbeteiligte Einstellungen.

Verwandte Dokumente

• Erste Einrichtung
• Installationsanleitung
• Einrichtung der API-Zugangsdaten
• Einstellungs-Referenz
• Tools-Referenz
• Shortcodes und Widgets-Referenz
• Analytics-Aufbewahrung
• Lead-Daten und Einwilligung