Skip to main content

Debug Flags

Debug Flags​

Use debug flags to quickly toggle features, stub services, and control app behavior per environment (dev/QA/prod).

How It Works​

  • Flags live in JSON files like debug-flags.dev.json, debug-flags.qa.json, debug-flags.prod.json.
  • Code reads flags via @injectFlag('path.to.flag'). Values are resolved from the active environment’s file at startup.
  • Teams commit a debug-flags.dev.example.json (template), and .gitignore the real debug-flags.dev.json so each developer can customize safely.
export interface IHosannaDevice {
  configure(): unknown;
  onSystemDeviceInfoEvent(event: ISystemEvent<JsonData>): unknown;
  deviceInfo: ISGRODeviceInfo;
  deviceRegistry: IDeviceRegistry;
  appInfo: ISGROAppInfo;
  resolutionInfo: IResolutionInfo
}
Tip: Keep Dev Private

Commit debug-flags.dev.example.json and ignore debug-flags.dev.json. Share examples, not personal settings.

Using injectFlag​

Decorate fields with @injectFlag('path.to.flag') to bind values from the active flag file.

export class BaseHosannaDevice implements IHosannaDevice {
  @injectFlag('device.forcedDeviceQuality') forcedDeviceQuality?: DeviceQuality;
}
  • Supports nested paths: e.g., features.auth.mockLoginSuccess.
  • Values can be booleans, strings, numbers, or simple objects.

Override Device Info (Web Simulator)​

WebRoDeviceInfo reads @injectFlag('device.forcedDeviceInfo') to override specific roDeviceInfo responses in the web simulator. Provide a JSON object whose keys match the Roku-style methods; the values you set will be returned verbatim.

{
  "device": {
    "forcedDeviceInfo": {
      "GetModel": "Roku Ultra",
      "GetVersion": "15.5.1",
      "GetUIResolution": { "width": 1280, "height": 720, "name": "HD" },
      "GetInternetStatus": false,
      "IsHDMIConnected": false,
      "GetExternalIp": "203.0.113.1",
      "GetRandomUUID": "test-uuid-1234",
      "EnableInternetStatusEvent": true
    }
  }
}
  • Simulate offline flows: set GetInternetStatus: false.
  • Emulate device classes: tweak GetUIResolution, GetModel, GetModelType.
  • Toggle platform behaviors: e.g., IsHDMIConnected, EnableInternetStatusEvent, GetCaptionsMode.
Tip: Scope to Dev

Keep these overrides in debug-flags.dev.json only. They’re powerful for testing but shouldn’t ship to QA or production.

Common Scenarios​

  • Skip splash/launch video: ui.skipLaunchVideo = true.
  • Disable in-progress features: features.newNav = false.
  • Emulate auth: auth.mock = { enabled: true, user: { id: 'dev' } }.
  • Change service behavior: services.content.baseUrl = 'http://localhost:3000'.
  • Choose config source: config.useLocalConfig = true vs remote.
Resolution & Assets

Flags can also hint rendering defaults (e.g., quality presets), but image @res substitution for packaged assets is still automatic on Roku via the manifest.

File Strategy​

  • debug-flags.dev.example.json: Template of useful flags. Commit this.
  • debug-flags.dev.json: Local developer overrides. .gitignore this file.
  • debug-flags.qa.json / debug-flags.prod.json: Locked down for QA/production.

Best Practices​

  • Organize by domain: auth, features, services, ui, device, config.
  • Keep keys stable; document in the example file.
  • Avoid secrets; use environment variables or secure stores instead.

Example: debug-flags.dev.example.json​

Copy this as debug-flags.dev.example.json and commit it. Each developer can duplicate to debug-flags.dev.json locally (ignored by Git) and tweak values.

{
  "ui": {
    "skipLaunchVideo": true,
    "showPerformanceOverlay": false
  },
  "features": {
    "newNav": false,
    "enableA11yAnnouncements": true
  },
  "auth": {
    "mock": {
      "enabled": false,
      "user": { "id": "dev-user", "email": "dev@example.com" },
      "token": ""
    }
  },
  "services": {
    "content": {
      "baseUrl": "http://localhost:3000"
    },
    "auth": {
      "baseUrl": "http://localhost:3001"
    }
  },
  "config": {
    "useLocalConfig": true
  },
  "device": {
    "forcedDeviceQuality": "high"
  }
}
About forcedDeviceQuality

Accepted values are typically low, medium, or high (case-insensitive). If omitted, the platform decides based on actual device capabilities.