You can customize the appearance of the Frontend to match your specific needs and branding by using a JSON configuration file. You can modify styles, text, and icons to tailor the user experience.
The Frontend's appearance is controlled through a JSON configuration file, which offers flexibility when modifying default settings for the following elements:
- Text: Change labels, descriptions, and titles.
- Styles: Modify the color scheme and other visual aspects.
- Icons: Replace default icons with your own custom icons.
The JSON configuration file consists of two main objects: GEAIInstallationConfiguration and GEAIUiCustomization. The structure is as follows:
type GEAIInstallationConfiguration = {
organizationId?: string;
projectId?: string;
gtmId?: string;
fullStoryId?: string; // Added for FullStory integration
uiCustomization?: GEAIUiCustomization;
isFeedbackDisabled: boolean;
defaultPluginId?: string;
}
type GEAIUiCustomization = {
meta?: { /* ... */ };
login?: { /* ... */ };
logout?: { /* ... */ };
styles?: { /* ... */ };
}
The GEAIInstallationConfiguration object focuses on settings related to analytics and session recording, and details about it can be found in the Configuring Analytics and Session Recording with a JSON Configuration File.
The GEAIuiCustomization object is the primary area for customization. The structure is flexible, with optional fields for each configuration type. These include:
- Meta property
- Login & Logout properties
- Styles property
The Meta property defines global settings for the Frontend, allowing you to customize the appearance and functionality of the interface according to your brand and language preferences. It includes settings for icons, available languages, application descriptions, and logos.
meta?: {
assistantIcon?: {
src?: { english?: string; spanish?: string } | string;
};
availableLanguages?: ("english" | "spanish")[];
defaultLanguage?: string;
description?: { english?: string; spanish?: string } | string;
favicon?: { english?: string; spanish?: string } | string;
logo?: {
loginLogout?: {
src?: { english?: string; spanish?: string } | string;
alt?: { english?: string; spanish?: string } | string;
width?: string;
height?: string;
};
home?: {
src?: { english?: string; spanish?: string } | string;
alt?: { english?: string; spanish?: string } | string;
width?: string;
height?: string;
};
};
title?: { english?: string; spanish?: string } | string;
};
This structure allows you to define:
- assistantIcon: Specifies the icon to be used for the assistant in the sidebar and the header of the chat. It is recommended to use an SVG with a single color, as it projects as a mask in the UI.
- availableLanguages: Defines the languages available for the application. If only one language is selected, the language selection dropdown will not appear.
- defaultLanguage: Sets the default language for the application, which is used if the user's language preferences don't match any available languages. If availableLanguages is set and the default language is not part of the list, the first available language will be used. If defaultLanguage is not specified, English is used by default; if it's not available, the first available language is used.
- description: Provides a meta description of the application, which is used by search engines. It is recommended to configure it by language; however, if only one language is used, the description can be set without specifying the language.
- favicon: Configures the icon for the browser tab and history. It is advised not to use SVG format for the favicon, as many browsers (e.g., Safari and Android browsers) do not support it. The favicon can be the same for all languages or vary by language.
- logo:
- loginLogout.src: Sets the image (typically the application logo) used on the Login and Logout screens. This can be configured per language or be the same for all languages.
- loginLogout.alt: Defines the alt text for the image used on the Login and Logout screens. This is essential for accessibility tools like screen readers and ensures that if the image fails to load, the alt text will be displayed.
- loginLogout.width and loginLogout.height: Allows customization of the logo size on the Login and Logout screens.
- home.src: Sets the image (typically the application logo) used in the header of the Home screen (chat interface). This can also be configured per language.
- home.alt: Provides alt text for the logo in the Home screen header.
- home.width and home.height: Customizes the logo size for the Home screen header.
- title: Configures the title of the application, which is displayed in the browser tab and history. The title can be set for each language or be the same for all languages.
The Login and Logout properties allow you to customize the elements that users see when logging in and out of the application. You can modify texts such as the action button, descriptions, and titles of each screen, adjusting them for different languages.
login?: {
english?: {
actionButton?: string;
description?: string;
title?: string;
};
spanish?: {
actionButton?: string;
description?: string;
title?: string;
};
};
logout?: {
english?: {
actionButton?: string;
description?: string;
title?: string;
};
spanish?: {
actionButton?: string;
description?: string;
title?: string;
};
};
This structure allows you to define:
- actionButton: The text displayed on the login button. For example, "Log In" in English or "Iniciar sesión" in Spanish.
- title: The title displayed on the login screen. For example, "Welcome" or "Bienvenido".
- description: The description that appears on the login screen, which can be adjusted for each language.
- actionButton: The text displayed on the logout button, such as "Log Out" in English or "Cerrar sesión" in Spanish.
- title: The title displayed on the logout screen, configurable for each language.
- description: The description text for the logout screen, which can be customized for each language.
The Styles property allows you to deeply customize the visual appearance of the interface, including the color scheme for both dark and light themes. You can define color tokens for various UI elements, such as backgrounds, buttons, and text, ensuring the interface matches your branding and provides a consistent look across the application.
styles?: {
colors?: {
dark?: {
black?: string;
white?: string;
"gray--100"?: string;
"primary--100"?: string;
"green--100"?: string;
};
light?: {
black?: string;
white?: string;
"gray--100"?: string;
"primary--100"?: string;
"green--100"?: string;
};
};
};
This structure allows you to define:
- styles.colors.dark: Customizes the color scheme for the dark theme. The tokens represent various UI elements like background colors, text, and buttons. Valid CSS color values such as hex (#ffffff), RGB (rgb(255,255,255)), or named colors (white, black) can be used. For example, you can set the color of primary--100 to #8ad7d2 or gray--100 to #242426 for the dark theme.
- styles.colors.light: Customizes the color scheme for the light theme. Similar to the dark theme, you can set tokens like primary--100 to #00786f or gray--100 to #f3f9f9 to ensure the light theme reflects your design needs.
Here's a complete sample of a JSON configuration file. This sample demonstrates how you might customize the application's title, logo, and primary color:
{
"meta": {
"assistantIcon": {
"src": "assets/icons/my-assistant-icon.svg"
},
"availableLanguages": "english",
"defaultLanguage": "english",
"description": "A customized GeneXus Enterprise AI Frontend.",
"favicon": "assets/icons/favicon.ico",
"logo": {
"loginLogout": {
"src": "assets/images/my-company-logo-login.svg",
"alt": "My Company Logo",
"width": "200px",
"height": "40px"
},
"home": {
"src": "assets/images/my-company-logo-home.svg",
"alt": "My Company Logo",
"width": "150px",
"height": "30px"
}
},
"title": "My Company AI"
},
"login": {
"english": {
"actionButton": "Get Started",
"description": "Welcome to the customized AI experience.",
"title": "Login"
}
},
"logout": {
"english": {
"actionButton": "Logout",
"description": "Thank you for using My Company AI.",
"title": "Logout"
}
},
"styles": {
"colors": {
"dark": {
"black": "#1a1a1a",
"white": "#f2f2f2",
"gray--100": "#4d4d4d",
"primary--100": "#4CAF50",
"green--100": "#b2fab4"
},
"light": {
"black": "#000000",
"white": "#ffffff",
"gray--100": "#e0e0e0",
"primary--100": "#388E3C",
"green--100": "#81c784"
}
}
}
}
After customizing the JSON configuration file, you need to deploy it to your S3 bucket. Ensure that the INSTALLATION_CONFIG_FILE environment variable points to the correct location of the JSON file in S3.
To deploy the configuration, follow these steps:
- Upload the JSON file to your S3 bucket.
- Set the INSTALLATION_CONFIG_FILE environment variable to the S3 path of your JSON file.