Driver App configuration contract

The Driver App combines release settings, project configuration, project features, local context, and computed defaults. Consumers must normalize each value at the boundary instead of relying on JavaScript truthiness.

Availability

Configuration becomes usable after project and language initialization. The provider can use optimized bootstrap data or request a public configuration dictionary, then merge release-owned defaults, remote values, feature flags, and derived display values.

An unavailable project or failed read can produce an empty configuration set. Presence of a key does not prove that its value has the expected type.

Prerequisites

• Read the configuration dictionary through the authenticated Driver App context. Here, public means an allowed non-hidden value; it does not authorize anonymous access.
• Pin the Driver App release and its Components revision.
• Define the project and transport settings through the release-owned setup.
• Wait for language/project/bootstrap loading to settle.
• Keep credentials and protected values outside public configuration consumers.
• Assign one owner for each public configuration contract and its default.

Responsibility boundaries

Owner	Responsibility
Release configuration	Select project, application identity, transport roots, versions, language bootstrap, and boolean runtime switches
Project configuration service	Return public project/site/country values and feature flags for the selected context
Components configuration provider	Merge defaults, remote dictionary, features, conditional values, country context, loading, and error state
SDK request client	Normalize the transport root and request path to one separating slash and carry normalized request context
Feature consumer	Parse the declared type, apply an explicit fallback, and handle missing/loading/error values
Native or external provider	Own provider-specific setup and outcomes; configuration presence is not provider readiness

Inputs and result

Public consumers can encounter:

• native booleans, numbers, strings, arrays, or null;
• string-encoded flags such as "1", "0", "true", or "false";
• delimited lists that require an explicit split and item parser;
• numeric strings that require bounded integer or decimal parsing; and
• feature records represented as boolean-enabled entries.

Normalize before use:

const asEnabled = (value: unknown) =>
  value === true || value === 1 || value === '1' || value === 'true'

const asInteger = (value: unknown, fallback: number) => {
  const parsed = Number.parseInt(String(value), 10)
  return Number.isFinite(parsed) ? parsed : fallback
}

const asList = (value: unknown) =>
  typeof value === 'string'
    ? value.split('|').map(item => item.trim()).filter(Boolean)
    : Array.isArray(value) ? value : []

Do not coerce unknown non-empty strings to true. Do not treat missing, empty, protected, malformed, loading, and error states as equivalent.

Transport roots may include trailing slashes and resource paths may include leading slashes. The reviewed SDK removes those boundary duplicates and joins them with exactly one slash. Consumers should supply semantic paths, not perform their own repeated slash concatenation.

Security and privacy

• Keep the authenticated request boundary separate from the public-value allowlist. A publishable value is not an unauthenticated endpoint or session bypass.

• Public configuration must never contain credentials, tokens, private keys, or provider secrets.

• Treat protected or credential-shaped values as unavailable even if a response accidentally exposes a placeholder or legacy value.

• Do not publish the complete project dictionary or internal configuration names.

• Country/IP-derived defaults are provider-assisted fallbacks, not verified user location or consent.

Limits and failure states

• Remote, feature, release, and derived values can override one another by merge order.
• A remote error can collapse the effective dictionary to empty even though local defaults were constructed earlier.
• Configuration refresh can run after country-context events.
• Provider lookup failure falls back; provider success is not guaranteed.
• String-vs-native type drift is common in current consumers.
• The accepted API research revision is not proof of deployed configuration.

Troubleshooting

• Log the expected public type and sanitized presence, never the raw value.
• Distinguish provider loading, project missing, remote error, key absent, malformed value, and unsupported value.
• Verify URL joining with roots both with and without trailing slashes and paths both with and without leading slashes.
• Add tests for native and string-encoded booleans, numeric bounds, empty values, malformed lists, and fallback ownership.
• Re-audit any configuration whose owner, type, default, or merge precedence changes.

Related guides: Architecture · Authenticated bootstrap