Skip to main content

How to Add App Icons and Localized Names/Descriptions to Your PhariaAI Application

Overview​

PhariaAI applications automatically discover app icons and translations for name and description through a standardized webmanifest endpoint mechanism. Icons, names and descriptions are displayed in the Assistant interface and application listings.

Webmanifest Structure​

Your webmanifest should follow this structure, although none of the icons, name_localized or description_localized are mandatory:

{
  "icons": [
    {
      "src": "/ui/icons/your-app-icon.svg",
      "type": "image/svg+xml",
    },
    {
      "src": "/ui/icons/your-app-icon.png",
      "type": "image/png",
    }
  ],
  "name_localized": {
    "en": "Test App",
    "de": "Testen App"
  },
  "description_localized": {
    "en": "This is a test application",
    "de": "..."
  }
}

Including the Manifest Router​

Add the manifest router to your FastAPI application:

# service/src/service/main.py
from service.routes.manifest import router as manifest_router

app.include_router(manifest_router)

Icon Management​

How to Add an Icon to Your Application​

Step 1: Create Your Icon Files​

Create your icon files in the icons/ directory of your application service:

your-app/
├── service/
│   ├── icons/
│   │   ├── your-app-icon.svg    # SVG format (recommended)
│   │   └── your-app-icon.png    # PNG fallback
│   ├── src/
│   └── ...
└── ui/

Step 2: Serve Icons via Static Files​

Mount the icons directory in your FastAPI application:

# service/src/service/main.py
from fastapi import FastAPI
from starlette.staticfiles import StaticFiles

app = FastAPI()

# Mount icons directory - must be before generic /ui mount
app.mount("/ui/icons", StaticFiles(directory="icons"), name="icons")
app.mount("/ui", StaticFiles(directory="ui-artifacts"), name="ui")

Step 3: Create a Webmanifest Endpoint​

Add a webmanifest endpoint to expose your icon metadata:

# service/src/service/routes/manifest.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/manifest.webmanifest")
def get_manifest():
    return {
        "icons": [
            {
                "src": "/ui/icons/your-app-icon.svg",
                "type": "image/svg+xml",
            },
        ]
    }

Icon Requirements​

File Format​

  • Primary: SVG (recommended for scalability)
  • Fallback: PNG
  • Size: 32x32 pixels (recommended)
  • Max file size: 100KB

How the Assistant Discovers and Displays Icons​

Icon Discovery Process​

The Assistant fetches icon metadata for each custom application through the following process:

  1. Webmanifest Endpoint: Assistant calls /manifest.webmanifest on each custom app
  2. Icon Metadata: Parses the manifest to extract icon information
  3. Icon Fetching: Downloads icons from the specified URLs
  4. Fallback Handling: Uses default icons if webmanifest is unavailable or invalid

Icon Display Locations​

Icons are displayed in two main locations:

  1. Sidebar Navigation: Left sidebar with app list
  2. App Homepage: Main apps page with card layout

Fallback Behavior​

If the Assistant cannot fetch icon metadata from a custom app's webmanifest endpoint, it will display a standard application icon

Name or Description Localization​

How to Add to Your Application​

Create a Webmanifest Endpoint​

Add a webmanifest endpoint to expose your name/description localization:

# service/src/service/routes/manifest.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/manifest.webmanifest")
def get_manifest():
    return {
        "name_localized": {
          "en": "Test App",
          "de": "Testen App"
        },
        "description_localized": {
          "en": "This is a test application",
          "de": "..."
        }
    }

Fallback Behavior​

If the Assistant cannot fetch localization metadata from a custom app's webmanifest endpoint, it will display the name or description provided by PhariaOS API.