Apariencia coherente para widget y SDK móviles

Define una apariencia compartida

Mantén el objeto de apariencia compartida en tu configuración de diseño y pásalo al SDK web durante la inicialización o mediante updateAppearance. Pasa el mismo objeto como opción de apariencia del widget nativo. Se admiten system, lightSurfaceStyle, tokens de paleta, métricas de fuente, radio de controles, borde del panel y dimensiones. Los valores no válidos rechazan toda la actualización en lugar de cambiar la superficie parcialmente.

Usa overrides de plataforma solo para una limitación real, como safe area o una transición a navegación nativa. No dividas el tema completo para cada framework. La UI del widget nativo sigue siendo nativa y no renderiza el widget web en una WebView.

const sharedAppearance = {
  mode: "system",
  lightSurfaceStyle: "white",
  tokens: {
    light: { accent: "#2457d6", onAccent: "#ffffff", surface: "#ffffff", text: "#182230" },
    dark: { accent: "#91b4ff", onAccent: "#101828", surface: "#171b23", text: "#f2f4f7" },
  },
};
const platformOverrides = {
  safeArea: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 },
  keyboard: { resizeMode: "resize", dismissOnSubmit: true },
};

const webWidget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  appearance: sharedAppearance,
});
webWidget.updateAppearance(sharedAppearance);

await mobileClient.presentWidget({
  appearance: sharedAppearance,
  platform: platformOverrides,
});

Respeta el movimiento y el layout nativo

No establezcas reduceMotion: false como valor predeterminado. Cuando se omite, los SDK web y nativos siguen la preferencia actual del sistema para reducir movimiento. Si tu producto tiene un ajuste explícito de movimiento accesible, pasa esa elección del usuario deliberadamente y mantenla sincronizada con el host.

El presenter nativo controla safe areas, teclado, foco y transiciones de la plataforma. Mantén los controles del host fuera de la superficie presentada y oculta el launcher propio mientras el widget está abierto para que dos controles no compitan por la misma acción.

Localiza el texto integrado y el creado por el host

La UI nativa integrada se distribuye con en, uk, de y es. El widget web se distribuye con en, uk, de, es, fr y pt. El contrato de apariencia nativa permite que un renderizador nativo de nivel inferior sobrescriba las claves principales de texto de la UI del widget, así que una superficie nativa puede mostrar el texto principal de la UI en francés o portugués. Esto no proporciona una configuración regional completa del SDK en francés o portugués: las etiquetas derivadas, como las de rol del autor, los estados de procedimiento y validación y el resto de la UI generada, siguen el catálogo de locales integrado.

Los wrappers de framework mantienen pequeñas las opciones de presentWidget: locale, title y subtitle. No trates esas opciones del wrapper como un catálogo completo de textos ni afirmes que la UI nativa tiene los seis idiomas integrados del widget web. Un override de texto no amplía el enum de locales del SDK, no cambia el formato de números o fechas ni traduce contenido creado por el integrador o por el servidor.

Localiza las entradas de FAQ, los mensajes y el resto del contenido creado por tu aplicación en tu propio frontend o backend. Usa el mismo contrato de apariencia y textos en las referencias de cada plataforma y mantén limitados los overrides específicos de plataforma.

Actualiza la apariencia sin perder el trabajo

1. Aplica una actualización en tiempo de ejecución solo después de validar el objeto completo con el esquema publicado y los límites de contraste.
2. Comprueba el widget renderizado en modo claro, oscuro, del sistema y con reducción de movimiento. Confirma que la conversación activa y el borrador del composer siguen intactos.
3. Mantén las claves de plataforma desconocidas fuera del objeto compartido. Una actualización rechazada debe conservar la última apariencia válida y mostrar un error recuperable del host.