Contrato de configuración de Driver App

Driver App combina ajustes de la versión, configuración del proyecto, funciones del proyecto, contexto local y valores predeterminados calculados. Quienes consumen los valores deben normalizarlos en el límite en lugar de depender de la conversión implícita de JavaScript a booleano.

Disponibilidad

La configuración se puede usar después de inicializar el proyecto y el idioma. El proveedor puede usar datos de inicio optimizados o solicitar un diccionario de configuración pública; luego combina valores predeterminados propios de la versión, valores remotos, indicadores de función y valores de presentación derivados.

Un proyecto no disponible o una lectura fallida pueden producir un conjunto de configuración vacío. La presencia de una clave no demuestra que su valor tenga el tipo esperado.

Requisitos previos

• Lee el diccionario de configuración mediante el contexto autenticado de Driver App. Aquí, público significa un valor permitido no oculto; no autoriza el acceso anónimo.
• Fija la versión de Driver App y su revisión de Components.
• Define el proyecto y los ajustes de transporte mediante la configuración propia de la versión.
• Espera a que terminen las cargas de idioma, proyecto e inicio.
• Mantén las credenciales y los valores protegidos fuera de los consumidores de configuración pública.
• Asigna un único responsable a cada contrato y valor predeterminado de configuración pública.

Límites de responsabilidad

Responsable	Responsabilidad
Configuración de versión	Seleccionar proyecto, identidad de aplicación, raíces de transporte, versiones, inicio de idioma e interruptores booleanos de ejecución
Servicio de configuración de proyecto	Devolver valores públicos de proyecto/sitio/país e indicadores de función para el contexto seleccionado
Proveedor de configuración de Components	Combinar valores predeterminados, diccionario remoto, funciones, valores condicionales, contexto de país y estado de carga/error
Cliente de solicitudes de SDK	Normalizar la raíz de transporte y la ruta de solicitud para que haya una sola barra separadora, y transportar el contexto normalizado de la solicitud
Consumidor de funciones	Analizar el tipo declarado, aplicar un valor alternativo explícito y gestionar valores ausentes/en carga/con error
Proveedor nativo o externo	Controlar su configuración y resultados; la presencia de configuración no demuestra que esté listo

Entradas y resultados

Los consumidores públicos pueden encontrar:

• booleanos, números, cadenas, arreglos o valores nulos nativos;
• indicadores codificados como cadenas, por ejemplo, "1", "0", "true" o "false";
• listas delimitadas que requieren separación y análisis explícito de elementos;
• cadenas numéricas que requieren análisis acotado como enteros o decimales; y
• registros de funciones representados mediante entradas habilitadas/no habilitadas como booleanos.

Normaliza antes de usar:

const asEnabled = (value: unknown) =>
  value === true || value === 1 || value === '1' || value === 'true'

const asInteger = (value: unknown, fallback: number) => {
  const parsed = Number.parseInt(String(value), 10)
  return Number.isFinite(parsed) ? parsed : fallback
}

const asList = (value: unknown) =>
  typeof value === 'string'
    ? value.split('|').map(item => item.trim()).filter(Boolean)
    : Array.isArray(value) ? value : []

No conviertas a true cadenas desconocidas no vacías. No trates como equivalentes los estados ausente, vacío, protegido, mal formado, en carga y con error.

Las raíces de transporte pueden terminar en barras y las rutas de recursos pueden comenzar con ellas. El SDK revisado quita las barras duplicadas de ambos límites y los une con exactamente una barra. Quienes consumen la API deben proporcionar rutas semánticas, no concatenar barras repetidas por su cuenta.

Seguridad y privacidad

• Mantén separado el límite de solicitudes autenticadas de la lista permitida de valores públicos. Que un valor se pueda publicar no convierte un endpoint en anónimo ni permite eludir la sesión.
• La configuración pública nunca debe contener credenciales, tokens, claves privadas ni secretos de proveedores.
• Trata los valores protegidos o con forma de credencial como no disponibles, aunque una respuesta exponga accidentalmente un marcador o valor heredado.
• No publiques el diccionario completo del proyecto ni nombres internos de configuración.
• Los valores predeterminados derivados del país/IP son fallbacks asistidos por proveedores; no verifican la ubicación ni el consentimiento del usuario.

Límites y estados de fallo

• Los valores remotos, de funciones, de versión y derivados pueden anularse entre sí según el orden de combinación.
• Un error remoto puede dejar vacío el diccionario efectivo aunque antes se hayan construido valores locales predeterminados.
• La actualización de configuración puede ejecutarse después de eventos de contexto de país.
• Si falla la búsqueda con el proveedor, se usa un valor alternativo; el éxito del proveedor no está garantizado.
• En consumidores actuales es común que discrepen los tipos nativos y los representados como cadenas.
• La revisión aceptada de investigación de API no demuestra la configuración desplegada.

Diagnóstico

• Registra el tipo público esperado y la presencia saneada, nunca el valor sin procesar.
• Distingue la carga del proveedor, la falta de proyecto, error remoto, clave ausente, valor mal formado y valor no compatible.
• Verifica la unión de URL con raíces con/sin barra final y rutas con/sin barra inicial.
• Añade pruebas para booleanos nativos y codificados como cadena, límites numéricos, valores vacíos, listas mal formadas y responsabilidad del fallback.
• Vuelve a auditar cualquier configuración cuyo responsable, tipo, valor predeterminado o precedencia de combinación cambie.

Guías relacionadas: Arquitectura · Inicio autenticado