DEV Community

Cover image for How to Build an Enterprise Browser — Branding
Jani Hautakangas
Jani Hautakangas

Posted on

How to Build an Enterprise Browser — Branding

#browser #chromium #enterprisebrowser

Originally posted on Medium

In the first post I sketched out what an enterprise browser is and laid the foundation for my proof-of-concept, enterprise-browser-chromium. One bullet in that post was “Branding: Apply custom branding to establish a unique identity.” In practice that one bullet means touching strings, themes, build flags, installer code, Mac bundles, Windows resource sections, and Linux desktop files. This post is dedicated to that one bullet.

What “branding” really is in Chromium

Chromium ships as a generic open-source browser; Google Chrome is the proprietary product built on top of it. Anything trademarked (the Chrome logo, the “Google Chrome” name, certain installer artwork) sits behind a small set of build switches and is omitted from the public build. Branding, in source terms, is the answer to a handful of questions asked at build time: what product name to use, where icons and OS-level assets live, and what the product calls itself in the UI and installer.

How Chromium wires the branding switch

The whole branding system starts with a single GN argument declared in build/config/chrome_build.gni:

declare_args() {
  is_chrome_branded = false
  # ...
}
Enter fullscreen mode Exit fullscreen mode

When that argument flips to true, Chromium’s build switches to Google’s proprietary identity. (Internally the if/else keys off a derived is_internal_chrome_branded = is_chrome_branded && enable_src_internal; the second flag pulls in Google’s src-internal repo and isn’t available to public builds.) Two path variables, set in the same file, are what the rest of the build consumes:

if (is_internal_chrome_branded) {
  branding_path_component = "google_chrome"
  branding_path_product   = "google_chrome"
} else {
  branding_path_component = "chromium"
  branding_path_product   = "chromium"
}
Enter fullscreen mode Exit fullscreen mode

Almost everything else flows from those two strings:

  • branding_path_component selects the subdirectory inside chrome/app/theme/ for icons and artwork.
  • branding_path_product selects the .grd file used for branded strings.

In C++, the same switch surfaces as a BUILDFLAG. build/BUILD.gn generates branding_buildflags.h, which gives Chromium code two flags:

#if BUILDFLAG(GOOGLE_CHROME_BRANDING)
  // Google Chrome only
#elif BUILDFLAG(CHROMIUM_BRANDING)
  // Chromium (or any non-Google branded build)
#endif
Enter fullscreen mode Exit fullscreen mode

In Grit (the string and resource format), the same switch appears as <if expr="_google_chrome">. In Java, it appears as BuildConfig.IS_CHROME_BRANDED.

A downstream browser tells the build about itself, supplies parallel assets, and the rest of the build picks them up automatically.

The BRANDING file

Each brand has a plain-text BRANDING file at the root of its theme directory. Enterprise Browser’s looks like:

COMPANY_FULLNAME=KodeGood
COMPANY_SHORTNAME=KodeGood
PRODUCT_FULLNAME=Enterprise Browser
PRODUCT_SHORTNAME=Enterprise Browser
PRODUCT_INSTALLER_FULLNAME=Enterprise Browser Installer
PRODUCT_INSTALLER_SHORTNAME=Enterprise Browser Installer
COPYRIGHT=Copyright @LASTCHANGE_YEAR@ Jani Hautakangas <jani@kodegood.com>. All rights reserved.
MAC_BUNDLE_ID=com.kodegood.EnterpriseBrowser
MAC_CREATOR_CODE=Cr24
Enter fullscreen mode Exit fullscreen mode

build/util/branding.gni parses this file at GN time and exposes its fields as GN variables (chrome_product_full_name, chrome_mac_bundle_id, and friends). Those variables then flow into:

  • the Windows .rc resource that decorates the EXE with version metadata,
  • the Mac Info.plist template, where CFBundleIdentifier and CFBundleName are substituted from these fields,
  • the Linux installer scripts, which use the company and product names to generate .deb/.rpm package metadata.

The main branding topics

The diagram below shows the parallel enterprise_browser/ tree in the repo. Each topic that follows maps to one or more of these paths.

Enterprise Browser repo tree

Product name strings

Chromium splits the product-name-bearing strings into two files:

  • chrome/app/chromium_strings.grd
  • chrome/app/google_chrome_strings.grd

They are structurally identical but say Chromium and Google Chrome respectively. The build chooses between them through branding_path_product:

grit_strings("branded_strings") {
  source = "${branding_path_product}_strings.grd"
}
Enter fullscreen mode Exit fullscreen mode

The same pattern is repeated in components/, where there is components_chromium_strings.grd vs components_google_chrome_strings.grd, and again in the settings UI via .grdp partials.

These three pairs exist because they live in three layers: top-level browser strings, settings UI strings, and //components (which is architecturally below //chrome and cannot depend on it).

Doing this rename by hand isn't realistic: the English .grd has hundreds of Chromium mentions, multiplied by 80+ per-locale .xtb files. A broader Chrome/Chromium sweep can also mangle compound terms like ChromeOS and Chromecast, which must survive intact. The only sane path is a script.

Enterprise Browser ships an eb l10n command for this.

⚠ Caveat: a regex sweep across 80+ locales is a placeholder, not a real translation. Non-Latin transliterations and idiomatic phrasing need a real translation pipeline, which this post doesn’t cover.

Side-by-side: Chromium vs. Enterprise Browser About page

Themes, icons, and platform artwork

Visual assets live in chrome/app/theme/, organized in three parallel scale tiers:

chrome/app/theme/<brand>/                   # vector + master assets, BRANDING file
chrome/app/theme/default_100_percent/<brand>/  # raster, 1x
chrome/app/theme/default_200_percent/<brand>/  # raster, 2x
Enter fullscreen mode Exit fullscreen mode

Inside <brand>/, the build expects platform subdirectories: mac/app.icns, win/<brand>.ico (and a handful of file-handler icons), and linux/product_logo_*.png.

chrome/app/theme/theme_resources.grd references the in-binary UI resources here via ${branding_path_component} substitution; the platform-specific bundle assets (.icns, .ico, Linux logos) flow in through separate platform bundle and installer rules.

Enterprise Browser keeps its parallel set of these assets under enterprise_browser/app/theme/; the eb branding build step mirrors them into chrome/app/theme/enterprise_browser/ before GN runs.

Enterprise Browser theme tree layout

The branding GN switch

Chromium’s chrome_build.gni only knows about two brands out of the box: chromium and google_chrome. To plug in a third, you have two options: patch the upstream file, or override the GN args before GN runs.

Enterprise Browser currently takes the patch route. build-config-chrome_build.gni.patch adds a new branch to the conditional:

} else if (is_enterprise_browser) {
  branding_path_component = "enterprise_browser"
  branding_path_product   = "enterprise_browser"
}
Enter fullscreen mode Exit fullscreen mode

…and the new is_enterprise_browser argument is declared in enterprise_browser/build/enterprise_browser.gni:

declare_args() {
  is_enterprise_browser = true
}
Enter fullscreen mode Exit fullscreen mode

This works, but carries an ongoing cost. The patch's hunk context sits inside the if / else if / else chain in chrome_build.gni. Any time upstream touches that chain (new branches, reordering, rewritten declarations), the surrounding lines stop matching and the patch needs rebasing. The breakage is mechanical, not logical, but you still have to fix it on every uprev (each time you update to a newer Chromium version).

The better long-term approach skips the patch entirely. GN args declared with declare_args() can be overridden from args.gn: your value wins, the default is skipped. Ship a branding_defaults.gni that sets branding_path_component and branding_path_product, and import it from args.gn before gn gen runs. The upstream file stays untouched, and uprevs become noticeably less painful.

Windows .exe properties showing Enterprise Browser branding

Installer strings and platform packaging

The installer has its own product name, its own shortcut names, and on Windows it registers OS-level rules that include the product name.

Chromium drives a lot of this from a Python script, chrome/installer/util/prebuild/create_installer_string_rc.py. It has a MODE_SPECIFIC_STRINGS dictionary that, for each branding mode (google_chrome, chromium), lists which string IDs to emit into the installer’s resource section.

Enterprise Browser patches that script (chrome-installer-util-prebuild-create_installer_string_rc.py.patch) to add an enterprise_browser mode:

MODE_SPECIFIC_STRINGS = {
  'IDS_APP_SHORTCUTS_SUBDIR_NAME': {
    'google_chrome': [
      'IDS_APP_SHORTCUTS_SUBDIR_NAME',
      'IDS_APP_SHORTCUTS_SUBDIR_NAME_BETA',
      # ...
    ],
    'chromium': [
      'IDS_APP_SHORTCUTS_SUBDIR_NAME',
    ],
    'enterprise_browser': [
      'IDS_APP_SHORTCUTS_SUBDIR_NAME',
    ],
  },
  # ...same shape for IDS_INBOUND_MDNS_RULE_DESCRIPTION, IDS_PRODUCT_NAME, etc.
}
Enter fullscreen mode Exit fullscreen mode

This is the kind of detail that is invisible until you ship a Windows build, and then it becomes a long tail of small symptoms (wrong product name in the Start menu, wrong firewall rule description, etc.) that all trace back to a few entries in this dictionary.

Vector icons inside the UI

Branding is not only the outside of the binary. Vector icons baked into the browser UI (the About-dialog product mark, the new tab page icon, the icon used in profile pickers) live in .icon files under components/vector_icons/<brand>/. Enterprise Browser ships its own product.icon and product_refresh.icon under components/vector_icons/enterprise_browser/.

UI customization: settings layout, new tab page, splash

Beyond names and icons, branding extends to the layout and content of user-facing surfaces too: chrome://settings sections, the new tab page, the first-run welcome, splash and intro screens, the profile picker, the about page. Mechanically this is different work: editing WebUI HTML/TS/CSS under chrome/browser/resources/ plus native C++ that builds the settings tree.

Enterprise Browser has made a start here. The intro flow, the first-run / splash onboarding sequence, and the profile picker are already customized, so the onboarding and sign-in surfaces are visibly Enterprise Browser.

Enterprise Browser first-run intro / splash screen

The build-time mirroring tool

Most of the above is data: strings, themes, vector icons, the BRANDING file. The thing that applies them to the Chromium tree is a build step that mirrors your branding files into the right places under src/ before GN runs.

Enterprise Browser does the same thing in tools/eb/eb.py under cmd_branding. The mapping is exactly the parallel set: theme directories (master + both scale tiers), the XTB translation resources, the three string bundles, and the vector icons. Run as eb branding, or implicitly via eb sync.

Wrapping up

Conceptually Chromium’s branding system is a single switch that cascades through dozens of subsystems: one flag, two path variables. The implementation is messier: a long tail of #if BUILDFLAG(GOOGLE_CHROME_BRANDING) blocks, Grit <if expr="_google_chrome"> conditionals, Java checks, and per-mode entries in build scripts. Adding a new brand means making sure all those fences understand your brand.

Enterprise Browser has the foundation in place (GN wiring, theme tree, string bundles, BRANDING file, build-step mirror), but most icons and strings under those directories are still stock Chromium files copied and renamed. Most topics above are partly done at best, with branded artwork, code signing, and the updater’s own branding pipeline (chrome/updater/branding.gni is its own subsystem and isn’t covered here) still ahead. Each piece is small in isolation; most have to be re-checked on every uprev.

Repo: KodeGood/enterprise-browser-chromium.

Top comments (0)