Узгоджено налаштуйте віджет і мобільні SDK

Визначте один спільний вигляд

Зберігайте спільний об'єкт appearance у конфігурації дизайну й передавайте його веб SDK під час ініціалізації або через updateAppearance. Той самий об'єкт передавайте як appearance option нативного віджета. Підтримуються system, lightSurfaceStyle, токени палітри, метрики шрифту, радіус контролів, межа панелі та розміри. Некоректні значення відхиляють повне оновлення, а не змінюють поверхню частково.

Використовуйте platform overrides лише для реального платформного обмеження, наприклад safe-area або передавання нативній навігації. Не розгалужуйте всю тему для кожного фреймворку. Нативний UI віджета залишається нативним і не відтворює вебвіджет у 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,
});

Поважайте рух і нативне компонування

Не задавайте reduceMotion: false за замовчуванням. Коли параметр відсутній, веб- і нативні SDK стежать за поточним системним reduced motion. Якщо продукт має явне налаштування доступності руху, передавайте вибір клієнта свідомо й синхронізуйте його з хостом.

Нативний presenter керує safe area, клавіатурою, фокусом і платформними переходами. Тримайте елементи керування хоста поза представленою поверхнею та ховайте лаунчер, яким керує застосунок, коли віджет відкритий, щоб дві кнопки не конкурували за одну дію.

Локалізуйте вбудований і створений хостом текст

Вбудований нативний UI постачається з en, uk, de та es. Вебвіджет постачається з en, uk, de, es, fr і pt. Нативний контракт вигляду дає нижчорівневому нативному рендереру змогу перевизначати основні ключі тексту UI віджета, тому нативна поверхня може показувати основний текст UI французькою або португальською. Це не створює повної локалі SDK французькою чи португальською: похідні підписи, як-от підписи ролі автора, статуси процедур і перевірок та інший згенерований UI і далі визначаються вбудованим каталогом локалей.

Обгортки фреймворків навмисно мають невеликий набір параметрів presentWidget: locale, title і subtitle. Не сприймайте ці параметри обгортки як повний каталог тексту й не заявляйте, що нативний UI має шість вбудованих локалей вебвіджета. Перевизначення тексту не розширює enum локалей SDK, не змінює форматування чисел або дат і не перекладає контент, створений інтегратором або сервером.

Локалізуйте створені вами FAQ, повідомлення та інший клієнтський контент у власному застосунку або бекенді. Використовуйте той самий контракт вигляду й тексту на сторінках довідника платформ, а платформні перевизначення тримайте вузькими.

Оновлюйте вигляд без втрати роботи

1. Застосовуйте оновлення вигляду під час роботи лише після перевірки повного об'єкта опублікованою схемою та лімітами контрасту.
2. Перевірте відрендерений віджет у світлому, темному, системному режимах і з reduced motion. Переконайтеся, що активна розмова та чернетка composer збереглися після оновлення.
3. Не додавайте невідомі платформні ключі до спільного об'єкта. Відхилене оновлення має залишити останній коректний вигляд і показати хосту помилку, яку можна виправити.