Setup Wizard Reference

This document is a reference for the First Setup Wizard of the ADP Car Market Hub plugin. The wizard is a six-step, enterprise-style on-boarding flow that helps a WordPress administrator complete the most common configuration tasks immediately after the first activation.

The wizard is optional. Every option it offers can also be configured manually using the regular admin tabs documented elsewhere in the Admin Reference. For the recommended end-to-end setup order, see First Setup.

When to use this document

Read this if you need to:

• Understand when and how the welcome notice for the Setup Wizard appears.
• Know how to start, skip, or resume the wizard.
• Understand the difference between Demo setup and Live AutoScout24 setup.
• Know which options the wizard writes and which options it never overwrites silently.
• Understand the security model (capability and nonce protection, Client Secret handling).
• Document the wizard for an internal hand-over or customer on-boarding procedure.

Overview

The wizard is registered as a hidden admin page at:

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

It is not listed in the Car Market Hub submenu. Entry points are:

• The Welcome to ADP Car Market Hub admin notice that appears after the first activation.
• The Run Setup Wizard link near the top of Car Market Hub → Dashboard.
• The Setup Wizard card at the top of Car Market Hub → Tools.

The wizard never auto-redirects after activation. The admin notice is informational and provides two buttons: Start Setup Wizard and Skip for now.

Requirements or prerequisites

• A WordPress user with the plugin's management capability (Plugin::CAP_MANAGE).
• A first-activation timestamp recorded by the plugin's activation hook. Existing installations that upgrade without re-activation do not see the welcome notice but can still open the wizard manually from the Dashboard or the Tools tab.
• For Live setup: AutoScout24 API credentials (Client ID, Client Secret, Seller ID, API Base URL).
• For Demo setup: no API credentials are required.

Wizard flow

Step 1 — Mode

Choose between two setup paths:

• Demo setup — installs a curated set of demo vehicles, applies demo-friendly defaults and pre-checks the analytics toggle so that the Dashboard and Analytics pages have data to display. Demo setup is an explicit reset and seed operation: it triggers the existing Demo_Data::install() path on finish.
• Live AutoScout24 setup — saves real AutoScout24 credentials and the selected pages and feature toggles, but does not install demo data and does not pre-check analytics.

Step 1 also captures the dealer country (DE, CH, AT, Other), the default currency (EUR, CHF) and the admin language (site default plus a small explicit allowlist).

Step 2 — Dealer profile

Captures basic dealer identity used by other parts of the plugin: name, street, postal code, city, country, phone, email, website and a logo media ID. All fields are optional. Submitted values are sanitized; fields left empty preserve the existing stored value (no field is silently cleared).

Step 3 — AutoScout24

Captures the AutoScout24 API connection: Client ID, Client Secret, Seller ID and API Base URL. In Demo mode this step shows a "skip" hint; in Live mode credentials are recommended.

The Client Secret field is intentionally rendered empty. The wizard never writes the stored secret back into the admin HTML. Submitting the form with the field left empty (or whitespace-only) preserves the existing stored secret. Submitting a non-empty value replaces it. The same rule applies on the regular Settings tab — see Settings Reference.

The Base URL is validated against an http/https allowlist; other schemes (for example javascript:) are rejected.

Step 4 — Pages

For each public-facing page the wizard offers three modes:

• Create automatically — wp_insert_post() is called with post_type=page, post_status=publish, the canonical title and the canonical shortcode as the page content. A title lookup runs first to avoid creating a duplicate when a page with the same title already exists.
• Use existing page — the admin enters the post ID of an existing page and the corresponding option (as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id) is updated.
• Skip — the page is not created and the existing option value is preserved.

Canonical pages and shortcodes:

If the option already points to an existing page (get_post() returns a published page), the wizard preserves it and does not create a duplicate. The wizard never deletes existing pages.

Search Alerts intentionally has no public page in the wizard. Search-alert subscriptions are managed through the [as24ci_archive] filter sidebar and from the Search Alerts Reference admin tab.

Step 5 — Features

Toggles the most common feature defaults. Each toggle is recorded with an explicit "present" marker, so re-running the wizard partway through never wipes a setting that was not on the form:

• Social sharing buttons
• PDF datasheet
• QR code in PDF
• Running costs per 100 km
• Compare
• Favorites
• Search alerts
• Analytics tracking

In Demo mode the analytics toggle is pre-checked. In Live mode it is unchecked unless the admin explicitly enables it.

Hidden defaults that the wizard relies on (social sharing placement, the full network set, archive layout = both, list excerpt = 150) are seeded only when the corresponding option is missing; existing values are kept.

Step 6 — Finish

A read-only summary of the choices made. In Demo mode the finish button is labelled Install Demo Data and Finish and triggers the existing Demo_Data::install() path. In Live mode the finish button only saves the wizard's collected settings.

After a successful finish:

• as24ci_setup_wizard_completed is set.
• as24ci_setup_completed_at is set to an ISO-8601 UTC timestamp.
• as24ci_setup_completed_by is set to the WordPress user ID.
• The admin is redirected back to the Dashboard with a flash success notice.

Admin notice behavior

The welcome notice is rendered only when all of the following are true:

• The current user has the plugin's management capability.
• as24ci_setup_first_activation_at exists (recorded by Plugin::activate() only when missing, so existing installs that upgrade without re-activation are not nagged).
• as24ci_setup_wizard_completed is not set.
• as24ci_setup_wizard_skipped is not set.
• The current screen is not the wizard page itself.

Two buttons are offered:

• Start Setup Wizard opens the wizard.
• Skip for now posts to admin-post.php?action=as24ci_setup_wizard_skip (with capability and nonce checks). It sets as24ci_setup_wizard_skipped=1 and redirects back to the Dashboard. The notice does not reappear on subsequent admin page loads.

The wizard never force-redirects after activation.

Configuration reference

State options

Dealer profile options

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.

Existing options the wizard may write

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 key), DESIGN_ARCHIVE_LAYOUT, ARCHIVE_LIST_EXCERPT_LENGTH, as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id.

The wizard only updates options whose form fields are actually present in the submitted POST payload. Unsubmitted fields keep their existing value.

Security

• Capability gate. Every entry point (the wizard page, the form save handler and the skip handler) calls current_user_can( Plugin::CAP_MANAGE ) and bails out with wp_die() if the capability is missing.
• Nonces. The form save uses wp_nonce_field() / check_admin_referer(); the skip URL uses wp_nonce_url() / check_admin_referer().
• Client Secret. The stored secret is never re-rendered in the admin HTML. Empty or whitespace-only submissions preserve the stored value.
• URL validation. Base URL and dealer website must use the http or https scheme; other schemes are rejected.
• Email validation. Dealer email is validated with is_email(). Invalid input silently preserves the existing value; an empty submission clears it.
• Sanitization. Mode, country, currency, language and page-mode are checked against explicit allowlists. Text fields use sanitize_text_field(). Page IDs use absint().
• Output escaping. Every dynamic value rendered by the wizard uses esc_html, esc_attr or esc_url.

Operational notes

• The wizard never modifies settings on plugin activation. Activation only seeds non-destructive defaults via add_option().
• The wizard never modifies settings when a step is loaded — settings are only updated when the admin submits a step.
• Demo setup remains an explicit reset and seed: it deliberately resets demo-controlled options and inserts demo vehicles. Use it on dedicated demo or evaluation sites only.
• Live setup is non-destructive with respect to vehicles and customer settings. It saves the wizard's selected settings and pages but does not install demo data.
• Analytics is pre-checked only in Demo mode. In Live mode the toggle is opt-in. See Analytics Retention for privacy considerations.
• The wizard does not run AI provisioning, automatic imports, scheduling or full sync. Those are configured later in the corresponding admin tabs.
• The wizard is not a replacement for a cookie consent tool, a CMP, a privacy policy or a legal review. Enable analytics on a live site only after these requirements have been verified.

Troubleshooting

• The welcome notice does not appear. The wizard has either been completed (as24ci_setup_wizard_completed) or skipped (as24ci_setup_wizard_skipped), the current user lacks the management capability, or the first-activation timestamp has not been recorded (typical for upgrades that did not trigger a fresh activation). Open the wizard from Car Market Hub → Tools → Setup Wizard instead.
• I skipped the wizard. How do I open it again? Use the Run Setup Wizard link on Car Market Hub → Dashboard or the Setup Wizard card on Car Market Hub → Tools.
• The wizard did not create my pages. A page with the same title already existed and was reused, or the Skip option was selected for that page on Step 4. Open Pages in WordPress and confirm. The wizard never deletes pages.
• The Client Secret field is empty when I open Step 3 again. This is by design. The stored secret is never re-rendered. Leaving the field empty preserves the stored value.
• Analytics is not enabled after Live setup. In Live mode the analytics toggle is opt-in. Re-open the wizard and enable it on Step 5, or toggle it on the Analytics tab. Confirm cookie consent and privacy requirements first.
• Demo data was not installed. Make sure you selected Demo setup on Step 1 and clicked Install Demo Data and Finish on Step 6. Live setup does not install demo data.
• Compare or Favorites are empty in the demo. Compare and Favorites are localStorage-based; the demo populates a fallback that seeds localStorage on first page load. Open the Compare or Favorites page once in the same browser session to trigger the seeding.
• The wizard does not overwrite my existing settings. Correct. The wizard only writes options whose form fields are submitted. Re-running it partway through never wipes unrelated settings.

Related documents

• First Setup
• Installation Guide
• API Credentials Setup
• Settings Reference
• Tools Reference
• Shortcodes And Widgets Reference
• Analytics Retention
• Lead Data and Consent