Server-Driven Branding
Server-driven branding lets a Salesforce admin set the agent’s colors, fonts, icons, and on-screen strings centrally, for the whole org, instead of every mobile app hard-coding its own theme. The SDK fetches that theme at connect time and merges it underneath whatever your app configures in code.
Use it when you want a consistent agent appearance across web and mobile that admins can change without shipping an app update. It composes with in-code theming rather than replacing it — anything your app sets always wins.
For in-code theming, see Theming.
- An admin configures branding for the org. The server materializes one complete, resolved theme per org, so the payload the device receives is already merged and validated on the server side.
- With the feature flag on, the SDK fetches that theme from
GET /mobile/agentforce/v1/brandingwhen the client connects. - The SDK validates the payload, drops anything it doesn’t understand, and merges what remains beneath your app’s own theme values.
- The resolved theme is published through the usual
LocalAgentforceThemecomposition local, so every component picks it up.
Your app never parses, constructs, or stores the branding payload. There’s no branding type in the public API surface — enabling the flag is the entire integration.
The flag defaults to false. With it off, nothing is fetched and the SDK renders your in-code theme over its own defaults, exactly as before.
| Property | Wire shape |
|---|---|
| Colors | light and dark maps of AgentforceColorToken key to an #AARRGGBB hex string. |
| Typography | A theme-wide fontFamily, plus a per-style map of fontWeight, fontSize, and lineHeight. |
| Icons | Per icon slot, a light and a dark image URL. The SDK resolves those URLs to painters off the main thread. |
| Display names | Custom strings keyed by AgentforceDisplayNameType name. |
Theme mode isn’t brandable. AgentforceThemeMode always comes from your app’s override, falling back to the SDK default. An org can’t force your agent into dark mode.
Shapes, dimensions, and shadows are also outside the payload.
How branding layers depends on which AgentforceTheming option your app supplies.
| Your app supplies | Result |
|---|---|
AgentforceTheming.Overrides (recommended) | A true per-token merge: your override → org branding → SDK default. Any token you leave out defers to branding, then to the SDK default. |
AgentforceTheming.CustomManager | Your manager is authoritative for colors, typography, shapes, dimensions, shadows, and theme mode. Branding fills only the icon and display-name slots you left unset. |
AgentforceTheming.Default | Branding applies directly over the SDK defaults. |
The CustomManager limitation is structural, not a gap: a fully resolved manager holds a concrete value for every property, so it carries no “unset” signal that branding could layer beneath. Icons and display names are the exception because those lookups genuinely return null when you haven’t set them. If you want an org’s colors or font to reach your app, use AgentforceTheming.Overrides.
| Property | Merge |
|---|---|
| Colors | Per token. Your override wins for that token only; every other token still takes the branded value. |
| Icons | Per slot. Your icon wins for that slot only. |
| Display names | Per slot. Your string wins for that slot only. |
| Typography | All or nothing. A host typography replaces the branded one entirely, matching the shape of the type scale. Leave typography unset if you want the org’s font to apply. |
The payload crosses a network boundary and is cached on the device before it renders, so the SDK validates at ingestion. A bad value would otherwise re-crash the UI on every cold launch until the cache cleared. Everything invalid is dropped with a warning and falls back to the SDK default — a client always renders, even against a newer server.
| Field | Accepted | Dropped |
|---|---|---|
| Color token key | Any AgentforceColorToken name | Unrecognized keys |
| Color value | #AARRGGBB hex, or the literal unspecified | Unparseable values |
fontFamily | default, sansSerif / sans-serif / sans serif, serif, monospace, cursive (case-insensitive, trimmed) | Anything else, including custom font names |
fontWeight | 1 to 1000 | 0, negative, above 1000 |
fontSize, lineHeight | Greater than 0 and under 500sp | NaN, infinity, non-positive, 500sp or larger |
| Typography style name | Any of the 23 style tokens | Unrecognized names |
| Icon slot | Any AgentforceIconType name | Unrecognized slots |
| Display-name slot | Any AgentforceDisplayNameType name | Unrecognized slots, and blank values |
A malformed or empty response is ignored entirely — the SDK never throws on it.
An org can send the literal string unspecified for a color token, which maps to Compose’s Color.Unspecified. This is meaningful on a tint token such as titleBarIconTint or sendButtonIconTint, where it means “no tint” and lets a multi-color icon render in its original colors. On a fill or background token it has no useful meaning.
Branding strings are rendered verbatim in the agent chrome, so they’re sanitized first:
- Bidirectional-override, zero-width, and control characters are stripped, which blocks visual spoofing of the agent’s title and labels.
- The value is trimmed and capped at 256 characters.
- Blank results are dropped, falling back to the SDK string.
Strings your own app supplies through AgentforceThemeOverrides aren’t sanitized or capped — you’re trusted with your own copy.
- Turn the flag off and confirm your in-code theme still renders. Branding should be additive, never load-bearing.
- With the flag on and an org theme configured, override a single token in code and confirm your value wins while the rest of the org’s theme still applies.
- Test in both light and dark mode. An org can brand one mode more thoroughly than the other.
- Check contrast on the branded result (WCAG AA). An admin-chosen color isn’t guaranteed to be accessible against your overrides.
- Theming — in-code theming: colors, typography, icons, strings, and theme mode.
- AgentforceThemeManager — the theme contract and the
AgentforceThemingoptions. - AgentforceColors — the palette type and
AgentforceColorToken. - Color Token Reference — every token an org can brand, with its default light and dark value.
- Display Names — every string an org can override.
- Custom Icons — every icon slot an org can replace.