Configuración de la marca de la empresa#

Configuración de branding.json en Sherpa AI Server#

Propósito#

El archivo branding.json permite cambiar la apariencia y parte del comportamiento de la interfaz de Sherpa AI Server sin recompilar el frontend:

• nombre y logotipos;
• colores principales, radio de las esquinas y fuente;
• fondo de los mensajes del usuario y del Asistente;
• idioma predeterminado e idiomas disponibles;
• visualización del botón de inicio de sesión con OpenID;
• enlaces adicionales en el menú lateral;
• un botón de información en la página de inicio de sesión.

La configuración se aplica en el navegador cuando se carga la aplicación. No existe una pantalla separada de administración de branding en Sherpa AI Server.

Dónde se encuentra el archivo#

En el código fuente#

Archivo principal:

frontend/src/assets/branding/branding.json

Se incluye en la compilación del frontend y se usa como el conjunto de configuración predeterminado para la distribución.

En la distribución del cliente#

Al preparar el paquete del cliente, el archivo se copia aquí:

frontend/config/branding.json

Para que nginx use este archivo, hay que habilitar un bind mount en el archivo docker-compose.yml en el servicio aiserver-nginx:

services:
  aiserver-nginx:
    volumes:
      - ./frontend/config/branding.json:/opt/SherpaAIServer/frontend/dist/assets/branding/branding.json:ro

En el docker-compose.yml distribuido, esta línea puede estar comentada. Después de habilitar el mount por primera vez, vuelva a crear el contenedor:

docker compose up -d --force-recreate aiserver-nginx

Si el mount ya está habilitado, los cambios en el archivo del host se ven de inmediato dentro del contenedor. Para aplicarlos en la interfaz basta con recargar la página.

Cómo se carga la configuración#

Cuando el frontend inicia, solicita:

/assets/branding/branding.json

La configuración se carga antes de que arranque la aplicación Angular. Por eso, el idioma, los logotipos y las variables CSS del branding ya están disponibles durante el renderizado inicial de la interfaz.

Reglas de carga:

1. Los valores integrados de Sherpa AI Server se usan como base.
2. Los campos de branding.json reemplazan los valores integrados correspondientes.
3. Si el archivo no está disponible o contiene JSON inválido, la aplicación sigue funcionando con los valores integrados.
4. Los campos de nivel superior que falten no necesitan especificarse: para ellos se conservan los valores integrados.
5. Los objetos anidados y los elementos de los arreglos no se completan automáticamente; deben definirse por completo.

El campo _comments dentro del branding.json estándar contiene descripciones de referencia. Es un campo auxiliar normal de JSON; la interfaz no lo usa.

Inicio rápido#

1. Copie o edite frontend/config/branding.json.

2. Asegúrese de que el bind mount esté habilitado en docker-compose.yml.

3. Verifique la sintaxis del JSON:

   Copiar

   jq empty frontend/config/branding.json
   

4. Al conectar el archivo por primera vez, vuelva a crear aiserver-nginx:

   Copiar

   docker compose up -d --force-recreate aiserver-nginx
   

5. Verifique qué archivo está sirviendo el servidor:

   Copiar

   curl -fsS https://<server-address>/assets/branding/branding.json | jq .
   

6. Recargue la página de Sherpa AI Server. Si el navegador muestra recursos antiguos, realice una recarga forzada.

Ejemplo completo#

{
  "app_name": "Корпоративный AI",
  "logo_url": "assets/branding/logo-light-v1.svg",
  "logo_url_light": "assets/branding/logo-light-v1.svg",
  "logo_url_dark": "assets/branding/logo-dark-v1.svg",
  "disable_openid": false,
  "default_language": "ru",
  "available_languages": ["ru", "en"],
  "additional_menu_items": [
    {
      "button_name": {
        "ru": "Поддержка",
        "en": "Support"
      },
      "url": "https://support.example.org",
      "icon": "question-mark-circle-outline"
    },
    {
      "button_name": {
        "ru": "Инструкции",
        "en": "Documentation"
      },
      "url": "/main/documents",
      "icon": "book-open-outline"
    }
  ],
  "additional_login_button": {
    "button_name": {
      "ru": "Как получить доступ?",
      "en": "How do I get access?"
    },
    "message": {
      "ru": "Для получения доступа обратитесь в службу поддержки.",
      "en": "Contact the support team to request access."
    }
  },
  "primary_color": "#2563eb",
  "primary_dark_color": "#1d4ed8",
  "primary_light_color": "#60a5fa",
  "primary_rgb": "37, 99, 235",
  "secondary_color": "#1f2937",
  "border_radius": "8px",
  "font_family": "Inter, sans-serif",
  "font_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
  "chat_user_bg": "#eff6ff",
  "chat_assistant_bg": "#ffffff"
}

Descripción de los parámetros#

Configuración de los logotipos#

Prioridad de selección del logotipo para cada tema:

logo_url_light or logo_url_dark → logo_url → built-in logo

Se puede usar:

• una ruta relativa dentro del frontend, por ejemplo assets/branding/logo-light-v1.svg;
• una ruta absoluta desde la raíz del sitio, por ejemplo /assets/branding/logo-light-v1.svg;
• una URL absoluta, por ejemplo https://static.example.org/logo-light-v1.svg.

Si el logotipo se almacena junto con la configuración del cliente, móntelo por separado en docker-compose.yml:

services:
  aiserver-nginx:
    volumes:
      - ./frontend/config/branding.json:/opt/SherpaAIServer/frontend/dist/assets/branding/branding.json:ro
      - ./frontend/config/logo-light-v1.svg:/opt/SherpaAIServer/frontend/dist/assets/branding/logo-light-v1.svg:ro
      - ./frontend/config/logo-dark-v1.svg:/opt/SherpaAIServer/frontend/dist/assets/branding/logo-dark-v1.svg:ro

En producción, el navegador puede almacenar en caché imágenes, fuentes y otros archivos estáticos durante hasta un año. Cuando cambie el contenido del logotipo, use un nombre nuevo, por ejemplo logo-light-v2.svg, y actualice la ruta en branding.json.

Configuración de los colores#

primary_color y primary_rgb describen el mismo color en formatos distintos. No se sincronizan automáticamente.

Ejemplo:

{
  "primary_color": "#2563eb",
  "primary_rgb": "37, 99, 235"
}

Para primary_color, primary_dark_color y primary_light_color, se debe usar el formato HEX completo #RRGGBB. El servicio calcula el contraste del color principal para el texto y los iconos, por lo que no se deben usar HEX abreviado ni valores rgb(...) o rgba(...) para estos tres campos.

Para secondary_color, chat_user_bg y chat_assistant_bg, se permiten colores CSS normales, por ejemplo HEX o rgba(...).

Después de cambiar los colores, compruebe ambos temas, las tablas, los campos de formulario, los botones y la legibilidad de los mensajes en el chat.

Configuración de la fuente#

font_url debe apuntar a un archivo CSS con la fuente, y font_family debe apuntar al nombre de familia de ese archivo CSS:

{
  "font_family": "Inter, sans-serif",
  "font_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
}

Para una fuente personalizada, se puede montar el CSS y los archivos de la fuente en el directorio frontend y usar una URL relativa. Asegúrese de que la URL sea accesible desde los navegadores de los usuarios, no solo desde el backend de Sherpa AI Server.

Para no cargar un archivo CSS adicional, deje font_url vacío:

{
  "font_family": "Roboto, 'Helvetica Neue', sans-serif",
  "font_url": ""
}

Idiomas de la interfaz#

Solo se admiten los valores ru y en.

Si available_languages está vacío, tiene un formato no válido o no contiene valores admitidos, Sherpa AI Server habilita ambos idiomas. Si default_language no está presente en la lista de idiomas disponibles, el primer elemento de available_languages pasa a ser el idioma predeterminado.

Ejemplo de una interfaz solo en ruso:

{
  "default_language": "ru",
  "available_languages": ["ru"]
}

El botón del idioma actual sigue visible, pero el menú selector no se abre.

El idioma real se selecciona en este orden:

1. el parámetro lang o locale en la URL;
2. el idioma seleccionado previamente en el navegador;
3. default_language de branding.json.

El valor de la URL o del navegador solo se aplica cuando el idioma está presente en available_languages.

Elementos adicionales del menú#

Cada elemento de additional_menu_items debe contener:

{
  "button_name": {
    "ru": "Поддержка",
    "en": "Support"
  },
  "url": "https://support.example.org",
  "icon": "question-mark-circle-outline"
}

Reglas:

• se requiere al menos una traducción no vacía del nombre;
• url debe ser una ruta interna con una sola / inicial o una URL con el protocolo http o https;
• los valores con otros protocolos y las URL no válidas se ignoran;
• los enlaces internos se abren a través del enrutador de Sherpa AI Server;
• los enlaces externos se abren en la pestaña actual;
• los elementos se muestran en el mismo orden que en el arreglo;
• para un icono estándar, especifique un nombre de Eva Icons, por ejemplo book-open-outline;
• una cadena que termine en / o .svg se interpreta como la ruta a un icono SVG personalizado.

Si falta una traducción, se usa primero el ruso y luego el inglés.

Botón de información en la página de inicio de sesión#

Ejemplo:

{
  "additional_login_button": {
    "button_name": {
      "ru": "Forgot your password?",
      "en": "Forgot your password?"
    },
    "message": {
      "ru": "Contact the support team.",
      "en": "Contact the support team."
    }
  }
}

El botón se muestra si hay al menos un nombre y al menos un texto de mensaje completados. El texto se muestra como texto plano, no como HTML. Si falta una traducción, se usa primero el ruso y luego el inglés.

Para ocultar el botón:

{
  "additional_login_button": null
}