Documentazione · Riferimento amministratore

Riferimento della configurazione guidata

Questo documento è un riferimento per la Prima configurazione guidata (First Setup Wizard) del plugin ADP Car Market Hub. La procedura guidata è un flusso di onboarding in sei passaggi, in stile enterprise, che aiuta un amministratore di WordPress a completare le attività di configurazione più comuni subito dopo la prima attivazione.

La procedura guidata è opzionale. Ogni opzione che offre può anche essere configurata manualmente utilizzando le normali schede di amministrazione documentate altrove nel Riferimento amministratore. Per l'ordine di configurazione end-to-end consigliato, consultare la Prima configurazione.

Quando utilizzare questo documento

Leggere questo documento se si ha la necessità di:

Capire quando e come appare l'avviso di benvenuto per la configurazione guidata.
Sapere come avviare, saltare o riprendere la procedura guidata.
Comprendere la differenza tra Configurazione Demo e Configurazione Live di AutoScout24.
Sapere quali opzioni scrive la procedura guidata e quali opzioni non sovrascrive mai in modo silenzioso.
Comprendere il modello di sicurezza (protezione tramite capability e nonce, gestione del Client Secret).
Documentare la procedura guidata per un passaggio di consegne interno o per una procedura di onboarding del cliente.

Panoramica

La procedura guidata è registrata come una pagina di amministrazione nascosta all'indirizzo:

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

Non è elencata nel sottomenu Car Market Hub. I punti di accesso sono:

L'avviso di amministrazione Benvenuto in ADP Car Market Hub che appare dopo la prima attivazione.
Il link Esegui configurazione guidata vicino alla parte superiore di Car Market Hub → Dashboard.
La scheda Configurazione guidata nella parte superiore di Car Market Hub → Tools.

La procedura guidata non reindirizza mai automaticamente dopo l'attivazione. L'avviso di amministrazione è informativo e fornisce due pulsanti: Avvia configurazione guidata e Salta per ora.

Requisiti o prerequisiti

Un utente WordPress con la capability di gestione del plugin (Plugin::CAP_MANAGE).
Un timestamp di prima attivazione registrato dall'hook di attivazione del plugin. Le installazioni esistenti che eseguono l'aggiornamento senza riattivazione non vedono l'avviso di benvenuto, ma possono comunque aprire la procedura guidata manualmente dalla Dashboard o dalla scheda Strumenti.
Per la configurazione Live: credenziali API di AutoScout24 (Client ID, Client Secret, Seller ID, URL di base dell'API).
Per la configurazione Demo: non sono richieste credenziali API.

Flusso della procedura guidata

Passaggio 1 — Modalità

Scegliere tra due percorsi di configurazione:

Configurazione Demo — installa un set curato di veicoli dimostrativi, applica impostazioni predefinite adatte alle demo e preseleziona l'interruttore delle statistiche in modo che le pagine Dashboard e Analytics abbiano dati da visualizzare. La configurazione demo è un'operazione esplicita di ripristino e popolamento: attiva il percorso esistente Demo_Data::install() al termine.
Configurazione Live di AutoScout24 — salva le credenziali reali di AutoScout24, le pagine selezionate e gli interruttori delle funzionalità, ma non installa dati demo e non preseleziona le statistiche.

Il passaggio 1 acquisisce anche il paese del rivenditore (DE, CH, AT, Altro), la valuta predefinita (EUR, CHF) e la lingua dell'amministratore (impostazione predefinita del sito più una piccola lista di consentiti esplicita).

Passaggio 2 — Profilo del rivenditore

Acquisisce l'identità di base del rivenditore utilizzata da altre parti del plugin: nome, via, codice postale, città, paese, telefono, email, sito web e un ID media del logo. Tutti i campi sono opzionali. I valori inviati vengono sanificati; i campi lasciati vuoti conservano il valore memorizzato esistente (nessun campo viene cancellato silenziosamente).

Passaggio 3 — AutoScout24

Acquisisce la connessione API di AutoScout24: Client ID, Client Secret, Seller ID e URL di base dell'API. In modalità Demo questo passaggio mostra un suggerimento per "saltare"; in modalità Live le credenziali sono consigliate.

Il campo Client Secret viene intenzionalmente visualizzato vuoto. La procedura guidata non riscrive mai il segreto memorizzato nell'HTML dell'amministratore. L'invio del modulo con il campo lasciato vuoto (o contenente solo spazi vuoti) conserva il segreto memorizzato esistente. L'invio di un valore non vuoto lo sostituisce. La stessa regola si applica alla normale scheda Impostazioni — vedere il Riferimento impostazioni.

L'URL di base viene convalidato rispetto a una lista di consentiti http/https; altri schemi (ad esempio javascript:) vengono rifiutati.

Passaggio 4 — Pagine

Per ogni pagina pubblica, la procedura guidata offre tre modalità:

Crea automaticamente — viene chiamato wp_insert_post() con post_type=page, post_status=publish, il titolo canonico e lo shortcode canonico come contenuto della pagina. Viene prima eseguita una ricerca del titolo per evitare di creare un duplicato quando esiste già una pagina con lo stesso titolo.
Usa pagina esistente — l'amministratore inserisce l'ID articolo di una pagina esistente e l'opzione corrispondente (as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id) viene aggiornata.
Salta — la pagina non viene creata e il valore dell'opzione esistente viene conservato.

Pagine canoniche e shortcode:

Pagina	Shortcode	Opzione
Auto	`[as24ci_archive]`	`as24ci_page_archive_id`
Confronta auto	`[as24ci_compare]`	`as24ci_page_compare_id`
Preferiti	`[as24ci_favorites]`	`as24ci_page_favorites_id`

Se l'opzione punta già a una pagina esistente (get_post() restituisce una pagina pubblicata), la procedura guidata la conserva e non crea un duplicato. La procedura guidata non elimina mai le pagine esistenti.

La funzione Avvisi di ricerca non ha intenzionalmente alcuna pagina pubblica nella procedura guidata. Le iscrizioni agli avvisi di ricerca sono gestite tramite la barra laterale dei filtri [as24ci_archive] e dalla scheda di amministrazione del Riferimento avvisi di ricerca.

Passaggio 5 — Funzionalità

Attiva o disattiva le impostazioni predefinite delle funzionalità più comuni. Ogni interruttore viene registrato con un marcatore esplicito di "presenza", in modo che la riesecuzione parziale della procedura guidata non cancelli mai un'impostazione che non era presente nel modulo:

Pulsanti di condivisione social
PDF datasheet
Codice QR nel PDF
Costi di esercizio per 100 km
Confronta
Preferiti
Avvisi di ricerca
Tracciamento delle statistiche (Analytics)

In modalità Demo l'interruttore delle statistiche è preselezionato. In modalità Live è deselezionato a meno che l'amministratore non lo abiliti esplicitamente.

Le impostazioni predefinite nascoste su cui si basa la procedura guidata (posizionamento della condivisione social, il set completo di reti, layout dell'archivio = entrambi, estratto dell'elenco = 150) vengono popolate solo quando l'opzione corrispondente è mancante; i valori esistenti vengono mantenuti.

Passaggio 6 — Fine

Un riepilogo in sola lettura delle scelte effettuate. In modalità Demo il pulsante di fine è etichettato come Installa i dati demo e termina e attiva il percorso esistente Demo_Data::install(). In modalità Live il pulsante di fine salva solo le impostazioni raccolte dalla procedura guidata.

Dopo una conclusione con successo:

as24ci_setup_wizard_completed viene impostato.
as24ci_setup_completed_at viene impostato su un timestamp UTC ISO-8601.
as24ci_setup_completed_by viene impostato sull'ID utente di WordPress.
L'amministratore viene reindirizzato alla Dashboard con un avviso di successo temporaneo.

Comportamento dell'avviso di amministrazione

L'avviso di benvenuto viene visualizzato solo quando tutte le seguenti condizioni sono vere:

L'utente corrente ha la capability di gestione del plugin.
as24ci_setup_first_activation_at esiste (registrato da Plugin::activate() solo quando mancante, in modo che le installazioni esistenti che eseguono l'aggiornamento senza riattivazione non vengano sollecitate).
as24ci_setup_wizard_completed non è impostato.
as24ci_setup_wizard_skipped non è impostato.
La schermata corrente non è la pagina stessa della procedura guidata.

Vengono offerti due pulsanti:

Avvia configurazione guidata apre la procedura guidata.
Salta per ora invia una richiesta a admin-post.php?action=as24ci_setup_wizard_skip (con controlli di capability e nonce). Imposta as24ci_setup_wizard_skipped=1 e reindirizza alla Dashboard. L'avviso non riappare ai successivi caricamenti delle pagine di amministrazione.

La procedura guidata non forza mai il reindirizzamento dopo l'attivazione.

Riferimento di configurazione

Opzioni di stato

Opzione	Scopo
`as24ci_setup_first_activation_at`	Timestamp della prima attivazione. Registrato una volta tramite `add_option()`; mai sovrascritto nelle successive (ri)attivazioni.
`as24ci_setup_wizard_completed`	Impostato su `1` dopo una conclusione con successo.
`as24ci_setup_wizard_skipped`	Impostato su `1` quando l'amministratore fa clic su Salta sull'avviso di benvenuto.
`as24ci_setup_mode`	`demo` oppure `live`.
`as24ci_setup_completed_at`	Timestamp UTC ISO-8601 dell'evento di conclusione.
`as24ci_setup_completed_by`	ID utente di WordPress che ha completato la procedura guidata.

Opzioni del profilo del rivenditore

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.

Opzioni esistenti che la procedura guidata potrebbe scrivere

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

La procedura guidata aggiorna solo le opzioni i cui campi del modulo sono effettivamente presenti nel payload POST inviato. I campi non inviati mantengono il loro valore esistente.

Sicurezza

Controllo delle capability. Ogni punto di accesso (la pagina della procedura guidata, il gestore del salvataggio del modulo e il gestore del salto) chiama current_user_can( Plugin::CAP_MANAGE ) e si interrompe con wp_die() se la capability è mancante.
Nonce. Il salvataggio del modulo utilizza wp_nonce_field() / check_admin_referer(); l'URL per saltare utilizza wp_nonce_url() / check_admin_referer().
Client Secret. Il segreto memorizzato non viene mai visualizzato nuovamente nell'HTML dell'amministratore. Gli invii vuoti o contenenti solo spazi vuoti conservano il valore memorizzato.
Convalida dell'URL. L'URL di base e il sito web del rivenditore devono utilizzare lo schema http o https; altri schemi vengono rifiutati.
Convalida dell'email. L'email del rivenditore viene convalidata con is_email(). Un input non valido conserva silenziosamente il valore esistente; un invio vuoto lo cancella.
Sanificazione. Modalità, paese, valuta, lingua e modalità della pagina vengono controllati rispetto a liste di consentiti esplicite. I campi di testo utilizzano sanitize_text_field(). Gli ID pagina utilizzano absint().
Escape dell'output. Ogni valore dinamico visualizzato dalla procedura guidata utilizza esc_html, esc_attr o esc_url.

Note operative

La procedura guidata non modifica mai le impostazioni all'attivazione del plugin. L'attivazione inserisce solo impostazioni predefinite non distruttive tramite add_option().
La procedura guidata non modifica mai le impostazioni quando viene caricato un passaggio; le impostazioni vengono aggiornate solo quando l'amministratore invia un passaggio.
La configurazione Demo rimane un ripristino e un popolamento esplicito: ripristina deliberatamente le opzioni controllate dalla demo e inserisce veicoli dimostrativi. Utilizzarla solo su siti dedicati a demo o valutazioni.
La configurazione Live non è distruttiva rispetto ai veicoli e alle impostazioni del cliente. Salva le impostazioni e le pagine selezionate della procedura guidata ma non installa dati demo.
Le statistiche (Analytics) sono preselezionate solo in modalità Demo. In modalità Live l'interruttore richiede il consenso esplicito (opt-in). Vedere la Conservazione dei dati di Analytics per considerazioni sulla privacy.
La procedura guidata non esegue il provisioning dell'AI, le importazioni automatiche, la pianificazione o la sincronizzazione completa. Queste vengono configurate successivamente nelle corrispondenti schede di amministrazione.
La procedura guidata non sostituisce uno strumento di consenso ai cookie, una CMP, un'informativa sulla privacy o una consulenza legale. Abilitare le statistiche su un sito live solo dopo che questi requisiti sono stati verificati.

Risoluzione dei problemi

L'avviso di benvenuto non viene visualizzato. Il wizard è stato completato (as24ci_setup_wizard_completed) o saltato (as24ci_setup_wizard_skipped), l'utente corrente non dispone dei permessi di gestione, oppure il timestamp della prima attivazione non è stato registrato (tipico degli aggiornamenti che non hanno attivato una nuova installazione). Apri invece il wizard da Car Market Hub → Tools → Setup Wizard.
Ho saltato il wizard. Come posso riaprirlo? Utilizza il link Esegui Setup Wizard su Car Market Hub → Dashboard o la scheda Setup Wizard su Car Market Hub → Tools.
Il wizard non ha creato le mie pagine. Esisteva già una pagina con lo stesso titolo che è stata riutilizzata, oppure è stata selezionata l'opzione Salta per quella pagina al Passaggio 4. Apri Pages in WordPress e verifica. Il wizard non elimina mai le pagine.
Il campo Client Secret è vuoto quando riapro il Passaggio 3. Questo comportamento è previsto dal design. Il secret memorizzato non viene mai mostrato nuovamente. Lasciare il campo vuoto conserva il valore memorizzato.
Analytics non è abilitato dopo la configurazione Live. In modalità Live, l'opzione per l'analytics è facoltativa (opt-in). Riapri il wizard e abilitala al Passaggio 5, oppure attivala nella scheda Analytics. Verifica prima i requisiti di consenso sui cookie e sulla privacy.
I dati demo non sono stati installati. Assicurati di aver selezionato Configurazione Demo al Passaggio 1 e di aver fatto clic su Installa dati demo e completa al Passaggio 6. La configurazione Live non installa i dati demo.
Le pagine Confronta o Preferiti sono vuote nella demo. Le funzioni Confronta e Preferiti si basano su localStorage; la demo popola un fallback che inizializza il localStorage al primo caricamento della pagina. Apri la pagina Confronta o Preferiti almeno una volta nella stessa sessione del browser per avviare l'inizializzazione.
Il wizard non sovrascrive le mie impostazioni esistenti. Corretto. Il wizard scrive solo le opzioni i cui campi del modulo vengono inviati. Eseguirlo nuovamente a metà non cancella mai le impostazioni non correlate.