Referrer Labels

Referrer labels are stored in:

/data/referrers.json

The file is automatically created and updated as new referrers are discovered.

Automatic discovery

When a new referrer is detected, the application attempts to find a human-friendly name by checking:

1. Web App Manifest (manifest.json or manifest.webmanifest)
2. Open Graph metadata (og:site_name)
3. Application metadata (application-name)
4. The website title (<title>)

Both domain.tld and www.domain.tld are tested when available to improve detection accuracy.

Examples:

{
    "github.com": {
        "label": "GitHub",
        "auto": true
    },
    "chatgpt.com": {
        "label": "ChatGPT",
        "auto": true
    }
}

Manual overrides

Any label can be changed manually.

Example:

{
    "chatgpt.com": {
        "label": "OpenAI ChatGPT",
        "auto": false
    }
}

Manual labels are never replaced by automatic discovery.

Canonical domains

Multiple subdomains are grouped under a single canonical domain.

Example:

{
    "www.google.com": {
        "canonical": "google.com"
    },
    "news.google.com": {
        "canonical": "google.com"
    }
}

This prevents duplicate referrer entries and duplicate cached icons.

Auto mode

The auto field controls whether a referrer entry may be modified automatically.

{
    "github.com": {
        "label": "GitHub",
        "auto": true
    }
}

When auto is set to true (default), the application may continue trying to automatically update the referrer metadata.

{
    "github.com": {
        "label": "My Custom Label",
        "auto": false
    }
}

When auto is set to false, the entry becomes locked.

The application will no longer attempt to update its label, canonical domain, or metadata.

This is useful when:

• Automatic discovery fails due to website security restrictions.
• A website reports an incorrect name.
• You want to use a custom label.
• You want to permanently keep a manual configuration.

Failed lookups

Some websites do not expose enough metadata to determine a proper name.

In such cases, the domain name itself is used as a fallback until automatic discovery successfully resolves a proper label.

Example:

example.com

The application will periodically retry automatic discovery for unresolved entries.

Do you find this project useful? You can support its development using the buttons in the page footer.