Documentación · Documentación técnica

Almacenamiento de opciones y ajustes

Este documento describe cómo almacena sus ajustes el plugin ADP Car Market Hub: qué claves se utilizan, dónde residen en la base de datos y cómo el plugin lee y escribe los valores.

Cuándo utilizar este documento

Lea este documento si necesita:

  • Localizar un ajuste específico del plugin en wp_options.
  • Entender qué opción controla una función o interruptor particular.
  • Planificar una copia de seguridad, migración de entorno o despliegue de staging a producción que incluya los ajustes del plugin.
  • Desarrollar una integración personalizada que lea una opción del plugin desde fuera del código del propio plugin.

Para conocer las tablas y entidades subyacentes, consulte la Guía de base de datos y el Modelo de datos.

Descripción general

Todos los ajustes configurables por el usuario se almacenan como opciones estándar de WordPress en la tabla wp_options. El plugin no mantiene una tabla de ajustes separada.

Las claves de las opciones se definen como constantes en la clase AS24CI\Options para que:

  • Las claves existan en un único lugar en el código fuente.
  • La rutina de desinstalación pueda derivar la lista completa de opciones automáticamente a partir de AS24CI\Options::get_all_keys().
  • El código que lee o escribe un ajuste pueda hacer referencia a la constante en lugar de repetir la cadena de texto original.

La mayoría de los ajustes son escalares (cadena de texto, entero, booleano codificado como 0/1). Algunos son arrays (por ejemplo, Seller IDs, anulaciones de mapeo, zonas de diseño, redes para compartir en redes sociales). Los arrays se almacenan utilizando la serialización de opciones por defecto de WordPress.

Convenciones de nomenclatura

Todas las claves de opción del plugin comienzan con el prefijo as24ci_. Los prefijos de subsistema agrupan los ajustes relacionados:

  • as24ci_design_*, as24ci_archive_*, as24ci_single_*, as24ci_fav_*, as24ci_comp_*: ajustes de diseño y tipografía.
  • as24ci_cron_*, as24ci_image_queue*: planificador y cola de imágenes.
  • as24ci_lead_*: formulario de contacto, consentimiento y plantillas de correo electrónico.
  • as24ci_ai_*: AI Assistant.
  • as24ci_analytics_*: analítica y consentimiento.
  • as24ci_test_drive_*: reserva de pruebas de conducción.
  • as24ci_envkv_*: configuración de costes de funcionamiento de EnVKV / WLTP para Alemania.
  • as24ci_lm_*, as24ci_layout_*: zonas del Layout Manager y diseño de archivo.
  • as24ci_feature_*: interruptores de funciones para subsistemas opcionales.

El inventario completo de claves de opción es la lista pública devuelta por AS24CI\Options::get_all_keys().

Categorías de ajustes

La clase Options define bastante más de un centenar de constantes. La lista que se presenta a continuación las agrupa por su finalidad. Cuando se documenta un valor por defecto en el código (valor por defecto de constante, add_option() en seed_safe_defaults(), o llamadas inline a get_option(..., $default)), se indica expresamente. Verifique cualquier valor que no sea el predeterminado con la versión actual del plugin antes de publicarlo.

API y autenticación

Utilizado por AS24CI\Client para comunicarse con la API de AutoScout24.

  • as24ci_base_url (Options::BASE_URL) — URL base de la API.
  • as24ci_token_url (Options::TOKEN_URL) — URL del token OAuth.
  • as24ci_seller_ids (Options::SELLER_IDS) — lista separada por comas de identificadores de vendedor (Seller ID).
  • as24ci_client_id (Options::CLIENT_ID) — Client ID de OAuth.
  • as24ci_client_secret (Options::CLIENT_SECRET) — Client secret de OAuth.
  • as24ci_token_audience (Options::TOKEN_AUDIENCE) — parámetro audience de OAuth.
  • as24ci_default_currency (Options::DEFAULT_CURRENCY) — código de moneda ISO 4217 por defecto (establecido como EUR en la activación).

Estos valores son obligatorios para que funcione cualquier importación y deben tratarse como confidenciales. No se muestran a los usuarios que no sean administradores.

Comportamiento del importador

Utilizado por AS24CI\Importer y AS24CI\Image_Importer.

  • as24ci_default_post_status (Options::DEFAULT_POST_STATUS) — estado asignado a los vehículos recién importados. Establecido como draft para que los administradores puedan revisar los mapeos antes de publicar.
  • as24ci_default_post_author (Options::DEFAULT_POST_AUTHOR) — ID de usuario del autor por defecto.
  • as24ci_import_images (Options::IMPORT_IMAGES) — si se deben importar las imágenes.
  • as24ci_max_images (Options::MAX_IMAGES) — número máximo de imágenes por vehículo. Establecido como 30. El importador trata el valor 0 como sin límite; el importador de imágenes aplica además el límite de forma defensiva.
  • as24ci_convert_to_webp (Options::CONVERT_TO_WEBP) — convertir las imágenes importadas a WebP.
  • as24ci_webp_quality (Options::WEBP_QUALITY) — calidad de WebP (1–100; por defecto es 80 si no se define).
  • as24ci_full_sync (Options::FULL_SYNC) — cuando está activado, los vehículos que ya no están presentes en la API se eliminan después de cada importación. Establecido como 0.
  • as24ci_verbose_logging (Options::VERBOSE_LOGGING) — líneas de registro detalladas (verbose) por vehículo / por imagen.
  • as24ci_mapping_overrides (Options::MAPPING_OVERRIDES) — array de anulaciones de etiquetas y visibilidad por campo de AS24.

Programador y automatización

Utilizado por AS24CI\Scheduler y AS24CI\Cron_Endpoint.

  • as24ci_auto_import_enabled (Options::AUTO_IMPORT_ENABLED).
  • as24ci_cron_schedule (Options::CRON_SCHEDULE) — uno de entre hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom. Por defecto: hourly.
  • as24ci_cron_start_time (Options::CRON_START_TIME) — hora de inicio para las programaciones diarias / dos veces al día en HH:MM (24 h, zona horaria del sitio WordPress). Por defecto: 06:00.
  • as24ci_cron_custom_minutes (Options::CRON_CUSTOM_MINUTES) — intervalo para la programación personalizada. Mínimo: 15. Por defecto: 30.
  • as24ci_cron_mode (Options::CRON_MODE) — wp-cron o server-cron.
  • as24ci_cron_token (Options::CRON_TOKEN) — token para el endpoint de importación cron de REST.
  • as24ci_cron_max_vehicles (Options::CRON_MAX_VEHICLES) — límite de vehículos por ejecución de cron. 0 = ilimitado.
  • as24ci_cron_image_queue (Options::CRON_IMAGE_QUEUE) — activar el modo de cola de imágenes durante las ejecuciones de cron. Por defecto: 1.
  • as24ci_image_queue (Options::IMAGE_QUEUE_DATA) — carga útil persistente de la cola de imágenes pendientes.
  • as24ci_image_queue_last_run (Options::IMAGE_QUEUE_LAST_RUN) — estadísticas de la última ejecución del worker de la cola de imágenes.
  • as24ci_last_run_time (Options::LAST_RUN_TIME) — marca de tiempo Unix de la última importación completada.
  • as24ci_last_run_status (Options::LAST_RUN_STATUS) — array de recuentos { inserted, updated, skipped, errors, sync_deleted }.
  • as24ci_last_external_cron_run (Options::LAST_EXTERNAL_CRON_RUN) — marca de tiempo Unix del último ping de cron externo exitoso.

Páginas por defecto y ciclo de vida

  • as24ci_create_default_pages (Options::CREATE_DEFAULT_PAGES) — si se deben crear las páginas de Vehículos / Comparar / Favoritos al activar.
  • as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id — IDs de las páginas creadas en la activación.
  • as24ci_delete_data_on_uninstall (Options::DELETE_DATA_ON_UNINSTALL) — cuando se establece en 1, la rutina de desinstalación elimina los vehículos, los leads, los archivos adjuntos importados y las páginas creadas en la activación.
  • as24ci_caps_version (Options::CAPS_VERSION) — marcador de migración de capacidades.
  • as24ci_db_version (Options::DB_VERSION) — marcador de migración de datos/esquema.

Marcadores de esquema de tablas personalizadas

  • as24ci_vehicles_db_version — versión del esquema de la tabla as24_vehicles.
  • as24ci_search_agent_db_version — versión del esquema de la tabla as24ci_search_agents.
  • as24ci_content_studio_db_version — versión de esquema compartida de las tablas as24ci_content_studio_jobs y as24ci_content_studio_assets.
  • as24ci_analytics_db_version — versión del esquema de la tabla as24ci_analytics (constante AS24CI\Analytics::DB_VERSION_KEY).

Interruptores de características (Feature toggles)

Todos los interruptores de características residen en AS24CI\Options::FEATURE_*. Los valores por defecto se establecen mediante AS24CI\Plugin::seed_safe_defaults() en la activación:

  • Activados por defecto: FEATURE_SCHEMA, FEATURE_SOCIAL_SHARE, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, FEATURE_SITEMAP, FEATURE_DASHBOARD_WIDGET, FEATURE_LAZY_LOADING, FEATURE_BULK_ACTIONS, FEATURE_EXPORT, FINANCING_ENABLED, LAYOUT_MANAGER_ENABLED. FEATURE_SEARCH_AGENT no tiene un valor por defecto explícito establecido, pero su comprobación en el momento del registro trata cualquier cosa distinta de '0' como activada, por lo que está efectivamente activo de forma predeterminada.
  • Desactivados por defecto por seguridad/cumplimiento normativo: ANALYTICS_ENABLED, REST_API_ENABLED, AI_ASSISTANT_ENABLED, TEST_DRIVE_ENABLED.

La lista completa de interruptores y su semántica está documentada en el bloque de documentación de clase para cada constante.

Formulario de contacto (Lead) y correo electrónico

Utilizado por AS24CI\Contact_Form y AS24CI\Leads_CPT.

  • as24ci_lead_recipient_email — anular el correo electrónico del destinatario.
  • as24ci_lead_field_* (nombre/email/teléfono/mensaje) — mostrar/ocultar campos del formulario. Por defecto es 1.
  • as24ci_lead_consent_enabled, as24ci_lead_consent_text, as24ci_lead_privacy_url — configuración de la casilla de verificación de consentimiento.
  • as24ci_lead_msg_success, as24ci_lead_msg_error — mensajes de usuario personalizados.
  • as24ci_lead_email_subject_dealer, as24ci_lead_email_subject_customer, as24ci_lead_email_template_dealer, as24ci_lead_email_template_customer — plantillas de correo electrónico con soporte para marcadores de posición (placeholders).

Analytics

  • as24ci_analytics_enabled — interruptor maestro. Por defecto: 0.
  • as24ci_analytics_retention_days — ventana de retención en días. Por defecto: 180.
  • as24ci_analytics_bi_enabled — BI / seguimiento de eventos extendido.
  • as24ci_analytics_require_consent — cuando es 1, bloquea el seguimiento hasta que llega una señal de consentimiento externa a través del filtro as24ci_analytics_consent_check.
  • as24ci_analytics_filter_minimization — eliminar los valores de búsqueda de texto libre de las cargas útiles de analítica. Por defecto: 1.
  • as24ci_analytics_privacy_jurisdiction — auto, gdpr, dsgvo, revdsg, uk_gdpr o generic.

AI Assistant

  • as24ci_ai_assistant_enabled (Options::AI_ASSISTANT_ENABLED).
  • as24ci_ai_assistant_language, as24ci_ai_assistant_tone, as24ci_ai_assistant_max_length, as24ci_ai_assistant_custom_prompt.
  • as24ci_ai_assistant_auto_generate, as24ci_ai_gen_alt_text, as24ci_ai_gen_seo, as24ci_ai_extract_highlights.

Las funciones de IA utilizan una configuración gestionada de Google Gemini. Las constantes de clave/modelo de Gemini codificadas de forma fija en AS24CI\Ai_Config han sido eliminadas; Ai_Config es ahora una interfaz ligera (get_managed_gemini_api_key() / get_effective_model()) que obtiene la clave de Gemini del cliente a partir de la credencial cifrada sincronizada por la API Platform y gestionada por AS24CI\Ai_Credential_Manager (el modelo en tiempo de ejecución es siempre Ai_Credential_Manager::PRIMARY_MODEL). No existe ninguna opción de proveedor, modelo o clave de API en wp_options, y la clave nunca se muestra en la interfaz de administración; el aprovisionamiento de IA para el cliente se completa de servidor a servidor por AD Promotion después de la instalación.

Reserva de prueba de conducción

Utilizado por AS24CI\Test_Drive.

  • as24ci_test_drive_enabled — interruptor maestro. Por defecto: 0.
  • as24ci_test_drive_available_days — array de números de día ISO (1=Lun … 7=Dom).
  • as24ci_test_drive_start_time, as24ci_test_drive_end_time — ventana de tiempo (HH:MM, 24 h). Valores por defecto 08:00 / 18:00.
  • as24ci_test_drive_slot_duration — duración del intervalo en minutos. Por defecto: 30.
  • as24ci_test_drive_blackout_dates — array de cadenas Y-m-d.

Webhooks, REST API y servicios externos

  • as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import, as24ci_webhook_secret.
  • as24ci_rest_api_enabled (Options::REST_API_ENABLED).
  • as24ci_hub_api_key, as24ci_hub_target_market — integración con Market Hub (mercado objetivo por defecto: DE).
  • as24ci_locations — array de ubicaciones de concesionarios (autoload desactivado; se carga solo en las páginas de vehículos individuales y en la pestaña de administración de ubicaciones).

Licencias y acceso gestionado

Utilizado por AS24CI\License_Manager. Almacenan el estado de la licencia y los derechos de características de la API Platform de ADP Car Market Hub:

  • as24ci_license_plan, as24ci_license_status, as24ci_license_last_error, as24ci_license_support_until, as24ci_license_expires_at, as24ci_license_installation_uid, as24ci_license_normalized_domain (constantes Options::LICENSE_*).
  • El estado de los derechos de características condiciona las rutas operativas (importación/escritura) y de IA; se actualiza mediante el cron diario as24ci_license_refresh y por el endpoint de señal de actualización de licencia entrante.

CMH Team

Utilizado por AS24CI\Team (almacenamiento basado en opciones, reflejando Locations):

  • as24ci_team_members (Options::TEAM_MEMBERS) — array de contactos de ventas (no se requieren cuentas de usuario de WordPress).
  • as24ci_team_location_defaults, as24ci_team_standards, as24ci_team_rules — configuración de soporte.

Content Studio

Las claves de Content Studio se definen en AS24CI\Content_Studio_Options (no en AS24CI\Options) y se añaden explícitamente a la lista de desinstalación:

  • as24ci_content_studio_db_version — versión de esquema compartida de las dos tablas de Content Studio.
  • as24ci_content_studio_google_api_key, as24ci_content_studio_default_language, as24ci_content_studio_default_tone, as24ci_content_studio_brand_voice, as24ci_content_studio_disclaimer_text, as24ci_content_studio_compliance_notes.

Layout Manager y diseño de archivo

  • as24ci_layout_manager_enabled — interruptor maestro. Establecido como 1 (activado) por seed_safe_defaults().
  • as24ci_lm_zone_* — arrays de diseño por zona para filtros de búsqueda, tarjetas de archivo, página individual principal/barra lateral/parte inferior, comparar y favoritos.
  • as24ci_lm_block_<id> — configuración de campos por bloque.
  • as24ci_layout_archive_columns — 1–4. Por defecto: 3.
  • as24ci_archive_default_sort — date_desc, price_asc, price_desc o mileage_asc.
  • as24ci_archive_per_page — vehículos por página. Por defecto: 24.
  • as24ci_archive_list_excerpt_length — caracteres del extracto en la vista de lista (0–500). Por defecto: 75.
  • as24ci_layout_search_filters, as24ci_layout_single_main, as24ci_layout_single_sidebar, as24ci_layout_single_bottom — arrays ordenados de claves de bloque con listas por defecto documentadas.

Diseño y tipografía

as24ci_design_* más las opciones de tipografía específicas de página as24ci_single_*, as24ci_archive_*, as24ci_fav_* y as24ci_comp_*. Controlan la combinación de colores, fuentes, diseños, distintivos y opciones de galería expuestas en la pestaña de administración Diseño y estilos. La lista completa se enumera como constantes en AS24CI\Options.

EnVKV / WLTP

Para el cumplimiento del mercado alemán, utilizado por la calculadora de costes de funcionamiento de EnVKV en las páginas de vehículos individuales.

  • as24ci_envkv_year — año de referencia (por defecto 2024).
  • as24ci_envkv_price_petrol, as24ci_envkv_price_diesel, as24ci_envkv_price_electric — precios de combustible/electricidad.
  • as24ci_envkv_co2_price_low, as24ci_envkv_co2_price_med, as24ci_envkv_co2_price_high — coste de CO₂ por tonelada.
  • as24ci_envkv_show_costs_100km — mostrar costes de funcionamiento (por defecto no).

Instrucciones paso a paso

La interfaz de usuario de ajustes del plugin es la forma recomendada para cambiar las opciones. Los siguientes puntos describen el ciclo de vida admitido.

  1. Primera configuración. Al activarse, seed_safe_defaults() escribe un conjunto conservador de valores por defecto utilizando add_option(). Los valores existentes nunca se sobrescriben. Abra la pestaña de administración correspondiente para revisar los valores por defecto antes de la puesta en marcha.
  2. Cambios diarios. Edite los ajustes en la pestaña de administración correspondiente (Importador, Automatización, Diseño y estilos, Mapeo, AI Assistant, etc.). Los cambios se guardan a través de la Settings API de WordPress.
  3. Copias de seguridad. Las copias de seguridad estándar de la base de datos de WordPress capturan todas las opciones del plugin porque residen en wp_options. No se requiere ninguna copia de seguridad adicional.
  4. Migraciones de entorno. Al mover un sitio entre entornos, copie las filas pertinentes de as24ci_* junto con el resto de wp_options. Trate as24ci_client_id, as24ci_client_secret, as24ci_cron_token y el secreto del webhook (as24ci_webhook_secret) como confidenciales. Tenga en cuenta que en las instalaciones migradas a la versión de datos 5, estos secretos reversibles se almacenan cifrados con AES-256-GCM y el token de cron se almacena en formato hash (consulte el paso de migración 5 en Plugin Bootstrap And Lifecycle). La clave gestionada de Gemini no se almacena en wp_options; se sincroniza de servidor a servidor mediante la API Platform (mantenida cifrada por AS24CI\Ai_Credential_Manager) y no se migra a través de traslados de bases de datos.
  5. Restablecer un ajuste. Elimine la opción (o utilice el botón de restablecimiento de la pestaña de administración donde se proporcione). El plugin volverá al valor por defecto documentado para ese ajuste.

Referencia de configuración

Utilice AS24CI\Options::get_all_keys() (devuelto por reflexión en la clase) para obtener la lista autoritativa y completa de claves de opciones en cualquier versión del plugin. La lista anterior está agrupada para referencia; las nuevas constantes añadidas a Options se incluyen automáticamente en la limpieza de desinstalación.

Notas operativas

  • Todas las lecturas de opciones en el código del plugin pasan por get_option() con un valor predeterminado documentado, por lo que las filas ausentes se comportan igual que los valores predeterminados recién instalados.
  • Un pequeño número de opciones están configuradas intencionadamente como autoload = false para mantener pequeña la tabla de opciones de carga automática (autoload). Ejemplos notables incluyen as24ci_image_queue, as24ci_image_queue_last_run y as24ci_locations.
  • seed_safe_defaults() se vuelve a ejecutar como parte del paso de migración 4 para que las instalaciones existentes reciban cualquier nuevo valor predeterminado seguro sin sobrescribir los valores modificados por el administrador.
  • Las instalaciones multisitio almacenan las opciones por sitio. La rutina de desinstalación itera por cada sitio a través de switch_to_blog().

Resolución de problemas

  • Un ajuste se revierte después de la actualización. El plugin nunca sobrescribe los valores de las opciones existentes durante las actualizaciones. Verifique que el cambio se haya guardado (la fila de la opción existe en wp_options) y que ninguna herramienta de gestión de configuración esté restaurando un valor anterior.
  • Se ignoran los cambios en la programación de Cron. El programador vuelve a programar WP-Cron solo cuando se llama a su método reschedule(). Utilice la pestaña Importación y límites para guardar la nueva programación en lugar de editar la opción directamente.
  • Una migración restablece inesperadamente una opción. Solo el valor de ANALYTICS_REQUIRE_CONSENT se normaliza intencionadamente mediante el paso de migración 2 (forzado a 0). Todos los demás ajustes se conservan mediante los pasos de migración.
  • Datos cargados automáticamente obsoletos o grandes. Inspeccione el tamaño de las opciones de carga automática en wp_options y desactive el autoload para cualquier opción personalizada del plugin que haya añadido y que almacene arrays grandes.

Documentos relacionados