Aparência coerente do widget e dos SDK

Definir uma aparência partilhada

Mantenha o objeto de aparência na configuração de design e passe-o ao SDK web na inicialização ou com updateAppearance. Passe o mesmo objeto ao widget nativo. Valores suportados incluem system, lightSurfaceStyle, tokens de paleta, métricas de fonte, raio, borda e dimensões. Valores inválidos rejeitam a atualização completa.

Use overrides apenas para restrições reais, como safe area ou navegação nativa. Não duplique o tema por framework. A UI nativa não renderiza o widget web numa 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,
});

Respeitar movimento e layout nativo

Não defina reduceMotion: false por defeito. Sem a opção, os SDKs seguem a preferência do sistema. Passe uma escolha explícita de acessibilidade apenas quando o produto a tiver e mantenha-a sincronizada.

O presenter nativo gere safe areas, teclado, foco e transições. Mantenha os controlos do host fora da superfície e esconda o launcher próprio enquanto o widget estiver aberto.

Localizar texto integrado e criado pelo host

A UI nativa integrada é distribuída com en, uk, de e es. O widget web é distribuído com en, uk, de, es, fr e pt. O contrato de aparência nativa permite que um renderer nativo de nível inferior substitua as principais chaves de texto da UI do widget, para que uma superfície nativa possa mostrar o texto principal da UI em francês ou português. Isto não fornece uma localização completa do SDK em francês ou português: rótulos derivados, como os rótulos de função do autor, os estados de procedimento e validação e o restante da UI gerada continuam a seguir o catálogo de locais integrado.

Os wrappers de framework mantêm as opções de presentWidget deliberadamente pequenas: locale, title e subtitle. Não trate essas opções do wrapper como um catálogo completo de texto nem afirme que a UI nativa tem as seis localizações integradas do widget web. Um override de texto não amplia o enum de locais do SDK, não altera a formatação de números ou datas e não traduz conteúdo criado pelo integrador ou pelo servidor.

Localize entradas de FAQ, mensagens e outro conteúdo criado pela sua aplicação no seu próprio frontend ou backend. Use o mesmo contrato de aparência e texto nas referências de cada plataforma e mantenha pequenos os overrides específicos da plataforma.

Atualizar aparência sem perder trabalho

1. Valide o objeto completo com o esquema publicado e limites de contraste antes de atualizar.
2. Verifique o widget em modos claro, escuro, sistema e redução de movimento. Confirme que conversa e rascunho permanecem.
3. Não use chaves de plataforma desconhecidas. Uma atualização rejeitada mantém a última aparência válida e mostra um erro recuperável.