Aller au contenu

Afficher l'habillage dans votre application

Lire par l'API publique le logo, le fond, le favicon et le thème CSS résolus pour l'utilisateur connecté, puis les appliquer à votre interface.

GuideDéveloppeur
Accès requis
Jeton Keycloak d'un utilisateur du realm de l'application (une clé API suffit pour runtime-config, pas pour /api/me)
Durée
15 min
Voir en Markdown

Votre wakapp n'a pas à connaître le réseau ni le client de l'utilisateur pour s'habiller correctement. L'API publique lui renvoie un habillage déjà résolu : il reste à l'appliquer.

Avant de commencer

  • Votre application sait obtenir un jeton d'accès Keycloak pour l'utilisateur connecté : voir Authentification.
  • Votre interface lit ses couleurs dans des variables CSS au format shadcn/ui (--background, --primary…), chaque couleur en composantes HSL sans fonction (221.2 83.2% 53.3%), et bascule en mode sombre avec la classe dark sur l'élément <html>. C'est le cas de waka-ui.
  • Toutes les requêtes partent vers https://api.wakastart.app/api. Le jeton doit avoir été émis pour votre application.

Choisir le bon appel

MomentAppelCe qu'il renvoie
Après la connexion de l'utilisateurGET /api/mel'habillage résolu pour cet utilisateur : client, réseau, puis application ; son thème préféré en premier
Au démarrage, ou pour un écran commun à tous les clientsGET /api/apps/{appWid}/runtime-configl'habillage du seul niveau application, le thème par défaut de l'application et ses langues

Lire l'habillage de l'utilisateur

Bash
curl "https://api.wakastart.app/api/me" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Réponse attendue (extrait, 200 OK) :

JSON
{
  "wid": "USR001",
  "email": "marie.durand@clinique-exemple.fr",
  "customer": { "wid": "CLI001", "name": "Clinique Exemple" },
  "network": { "wid": "NET001", "name": "Réseau Santé Exemple" },
  "branding": {
    "logoLightUrl": "https://stockage.exemple.fr/assets/customers/CLI001/logo-light.png?v=1761206400000",
    "logoDarkUrl": "https://stockage.exemple.fr/assets/networks/NET001/logo-dark.png?v=1761100000000",
    "bgLightUrl": "https://stockage.exemple.fr/assets/apps/EXAPP1/bg-light.webp?v=1760000000000",
    "bgDarkUrl": null,
    "faviconUrl": "https://stockage.exemple.fr/assets/networks/NET001/favicon.ico?v=1761100000000",
    "primaryColor": "#0f766e",
    "accentColor": "#f59e0b",
    "themeName": "Clinique Saint-Jean vert",
    "themeCssVarsLight": { "--background": "0 0% 100%", "--primary": "138 100% 28%" },
    "themeCssVarsDark": { "--background": "220 34% 8%", "--primary": "140 54% 47%" }
  }
}

Un champ à null, ou absent, signifie qu'aucun niveau ne le définit. Ici, aucun fond sombre n'existe : bgDarkUrl vaut null.

Lire la configuration de démarrage

Bash
curl "https://api.wakastart.app/api/apps/EXAPP1/runtime-config" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Réponse attendue (200 OK) :

JSON
{
  "theme": {
    "id": "3f6c2a10-0000-4000-8000-000000000002",
    "name": "Exemple App défaut",
    "cssUrl": "/themes/3f6c2a10-0000-4000-8000-000000000002/css"
  },
  "languages": [
    { "code": "fr", "name": "Français", "isDefault": true, "i18nUrl": "/languages/fr/file?appWid=EXAPP1&fileType=FRONT" },
    { "code": "en", "name": "English", "isDefault": false, "i18nUrl": "/languages/en/file?appWid=EXAPP1&fileType=FRONT" }
  ],
  "branding": {
    "logoLightUrl": "https://stockage.exemple.fr/assets/apps/EXAPP1/logo-light.png?v=1760000000000",
    "logoDarkUrl": null,
    "faviconUrl": "https://stockage.exemple.fr/assets/apps/EXAPP1/favicon.ico?v=1760000000000",
    "bgLightUrl": "https://stockage.exemple.fr/assets/apps/EXAPP1/bg-light.webp?v=1760000000000",
    "bgDarkUrl": null
  }
}

theme.cssUrl est relatif à l'URL de base de l'API : la feuille de style complète se lit sur https://api.wakastart.app/api/themes/{id}/css, avec le même en-tête d'authentification. Pour les fichiers de traduction, suivez Charger les traductions.

Un jeton émis pour une autre application est refusé avec un 403 et le message « Access denied: you can only access the runtime config of your own application ».

Appliquer l'habillage

Le module suivant lit l'habillage de l'utilisateur, en repli celui de l'application, puis l'applique à la page.

TypeScript
const API = "https://api.wakastart.app/api";

type Branding = {
  logoLightUrl?: string | null;
  logoDarkUrl?: string | null;
  bgLightUrl?: string | null;
  bgDarkUrl?: string | null;
  faviconUrl?: string | null;
  themeCssVarsLight?: Record<string, string>;
  themeCssVarsDark?: Record<string, string>;
};

async function get<T>(path: string, accessToken: string): Promise<T> {
  const res = await fetch(`${API}${path}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  if (!res.ok) throw new Error(`${path} : ${res.status}`);
  return res.json() as Promise<T>;
}

function cssBlock(selector: string, vars: Record<string, string> = {}): string {
  const lines = Object.entries(vars).map(([name, value]) => `  ${name}: ${value};`);
  return lines.length ? `${selector} {\n${lines.join("\n")}\n}` : "";
}

export async function applyBranding(accessToken: string, appWid: string): Promise<void> {
  const [{ branding }, runtime] = await Promise.all([
    get<{ branding: Branding }>("/me", accessToken),
    get<{ theme: { cssUrl: string } | null; branding: Branding }>(
      `/apps/${appWid}/runtime-config`,
      accessToken,
    ),
  ]);

  // 1. Thème : variables de l'utilisateur, sinon CSS du thème par défaut de l'application.
  let css = [cssBlock(":root", branding.themeCssVarsLight), cssBlock(".dark", branding.themeCssVarsDark)]
    .filter(Boolean)
    .join("\n\n");
  if (!css && runtime.theme) {
    const res = await fetch(`${API}${runtime.theme.cssUrl}`, {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    if (res.ok) css = await res.text();
  }
  let style = document.getElementById("wakastart-theme") as HTMLStyleElement | null;
  if (!style) {
    style = document.createElement("style");
    style.id = "wakastart-theme";
    document.head.appendChild(style);
  }
  style.textContent = css;

  // 2. Visuels : ceux de l'utilisateur, sinon ceux de l'application.
  const pick = (key: keyof Branding) => (branding[key] ?? runtime.branding[key] ?? null) as string | null;
  const dark = document.documentElement.classList.contains("dark");
  const logo = dark ? pick("logoDarkUrl") ?? pick("logoLightUrl") : pick("logoLightUrl");
  const background = dark ? pick("bgDarkUrl") ?? pick("bgLightUrl") : pick("bgLightUrl");

  const logoImg = document.querySelector<HTMLImageElement>("#app-logo");
  if (logoImg && logo) logoImg.src = logo;
  if (background) document.body.style.backgroundImage = `url("${background}")`;

  const favicon = pick("faviconUrl");
  if (favicon) {
    let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]');
    if (!link) {
      link = document.createElement("link");
      link.rel = "icon";
      document.head.appendChild(link);
    }
    link.href = favicon;
  }
}

Appelez applyBranding(accessToken, "EXAPP1") après la connexion, puis de nouveau quand l'utilisateur bascule entre le mode clair et le mode sombre.

Conseil

Le logo sombre est facultatif. Quand il manque, affichez le logo clair dans les deux modes, comme le fait la console.

Vérifier le résultat

  1. Connectez-vous avec un utilisateur d'un client qui a son propre logo : votre application l'affiche.
  2. Connectez-vous avec un utilisateur d'un autre client du même réseau : il voit le logo du réseau.
  3. Basculez en mode sombre : les variables du bloc .dark s'appliquent.

Voir aussi