Onboarding System

Helium’s onboarding system introduces new users to the browser and collects consent for optional features. It runs on first launch at helium://setup.

The onboarding experience is designed to be transparent about privacy choices and put users in control from the start.

Architecture

The onboarding system is a standalone web application built separately from the browser:

Separate Repository

helium-onboarding

Built Artifact

Compiled and packaged as tarball

Downloaded at Build

Fetched during Helium build process

Component Integration

Integrated into browser as internal page

Build Integration

The onboarding page is managed through deps.ini:

deps.ini

[onboarding]
version = 202601021937
url = https://github.com/imputnet/helium-onboarding/releases/download/%(version)s/helium-onboarding-%(version)s.tar.gz
download_filename = onboarding-page-%(version)s.tar.gz
sha256 = c8a1f906cf6461179d4fd311c529f0f8e01fb21b63ef179f593a24190c5dca80
output_path = ./components/helium_onboarding

Source: ~/workspace/source/deps.ini:9-14

Release Created

New version of onboarding app is built and released on GitHub

Version Bump

deps.ini is updated with new version number and SHA256 hash

Build Time

Helium build system downloads the tarball

Integration

Onboarding assets are extracted to components/helium_onboarding/

Compilation

Browser compiles with onboarding page bundled

URL Scheme

The onboarding page is accessible via the custom URL scheme:

helium://setup

This is registered as an internal page in the browser, similar to:

chrome://settings
chrome://extensions
chrome://flags

Onboarding Flow

First Launch Detection

Browser detects this is the first launch (no profile exists)

Navigate to Setup

Browser automatically opens helium://setup in a new tab

Welcome Screen

User sees introduction to Helium and its privacy features

Services Consent

User chooses whether to enable Helium services

Additional Options

User configures other first-run options (default search engine, theme, etc.)

Completion

Preferences are saved and user is taken to the New Tab Page

HOP (Helium Opinionated Policies) Integration

The onboarding system integrates with Helium’s policy system:

What is HOP?

HOP (Helium Opinionated Policies) is a custom policy provider that sets privacy-focused defaults and enforces security settings.Key features:

Highest priority policy source (overrides enterprise policies)
Sets privacy-first defaults
Configures password manager behavior
Manages WebRTC privacy settings

Source: ~/workspace/source/patches/helium/hop/setup.patch

Policy Provider Architecture

std::vector<std::unique_ptr<policy::ConfigurationPolicyProvider>>
ChromeBrowserPolicyConnector::CreatePolicyProviders() {
    auto providers = BrowserPolicyConnector::CreatePolicyProviders();
    
    auto hop_provider = std::make_unique<HopProvider>();
    hop_provider_ = hop_provider.get();
    
    // Insert at highest priority
    providers.insert(providers.begin(), std::move(hop_provider));
    
    return providers;
}

Source: ~/workspace/source/patches/helium/hop/setup.patch:15-19

Policy Priority

Helium’s policy system has a defined priority order:

Priority	Source	Can Override?
Highest	Helium Opinionated Policy (HOP)	Everything
High	Restricted Managed Guest Session	Everything below
Medium	Platform/Enterprise Policies	Everything below
Low	Cloud Policies	Everything below
Lowest	Default Values	Nothing

enum PolicyPriorityBrowser {
  kCloudUserDoubleRaised,
  kHeliumOpionatedPolicy,  // Highest priority
  kMerged,
};

Source: ~/workspace/source/patches/helium/hop/setup.patch:160-162 The onboarding flow explicitly asks for consent to enable Helium services:

What Users See

Services Explanation

During onboarding, users see:

What Helium services are: Anonymous web services for additional functionality
What they provide: Extension updates, browser updates, filter lists, spellcheck
Privacy guarantee: No tracking, no telemetry, self-hostable
Opt-in choice: Services are disabled by default until user consents

Preference Storage

Consent is stored in user preferences:

registry->RegisterBooleanPref(prefs::kHeliumServicesConsented, false);
registry->RegisterBooleanPref(prefs::kHeliumServicesEnabled, true);
registry->RegisterBooleanPref(prefs::kHeliumDidOnboarding, false);

Preferences:

helium.services.consented: Has user seen the consent screen?
helium.services.enabled: Are services currently enabled?
helium.did_onboarding: Has user completed onboarding?

Development

Running Locally

During development, you can work on the onboarding page separately:

git clone https://github.com/imputnet/helium-onboarding
cd helium-onboarding
npm install
npm run dev

This runs a development server for the onboarding app.

Integration Testing

To test onboarding integration in Helium:

Build Onboarding

npm run build

Create Tarball

tar -czf helium-onboarding-test.tar.gz dist/

Update deps.ini

Point to your local tarball for testing

Build Helium

Build Helium with your test onboarding page

Test First Run

Delete profile directory and launch Helium to trigger onboarding

Debugging

You can open DevTools on the onboarding page:

Navigate to helium://setup
Right-click → Inspect
DevTools opens for the onboarding page

The onboarding page runs in a standard WebContents, so all Chrome DevTools features work.

Onboarding vs Settings

Understanding the relationship:

Onboarding (helium://setup)
Settings (chrome://settings)

Purpose: First-run experience and initial consentWhen shown:

First launch of Helium
User hasn’t completed onboarding
Can be manually accessed anytime

Features:

Introduction to Helium
Service consent flow
Initial configuration
Welcome experience

Localization

The onboarding page supports internationalization:

Translations managed in onboarding repository
Matches Helium’s supported languages
Uses browser’s language preference
Fallback to English if translation unavailable

Version Tracking

The version number in deps.ini follows the format:

YYYYMMDDHHMM

Example: 202601021937 = January 2nd, 2026, 19:37 UTC This timestamp-based versioning ensures:

Clear chronological ordering
Easy identification of build time
No semantic versioning confusion

Schema Change Notifications

When Helium services schema changes, users who already completed onboarding see notifications:

Schema Version Incremented

New version of Helium includes updated schema version

Detection on Launch

Browser detects user’s acknowledged schema version < current version

App Menu Badge

“Services updated” badge appears on app menu

Settings Alert

Notification appears on Helium services settings page

User Reviews

User clicks notification to see changelog

Acknowledgment

User accepts changes, schema version is updated

This ensures users who enabled services during onboarding are informed of any behavior changes. See: Helium Services - Schema Versioning for details on the schema versioning system

Technical Details

Build System Integration

The onboarding component is downloaded and integrated during the Chromium build process:

Build script reads deps.ini
Downloads tarball from GitHub releases
Verifies SHA256 checksum
Extracts to components/helium_onboarding/
GN build system includes the component
Assets are embedded in the binary

Custom URL Handler

The helium://setup URL is registered as a custom scheme:

Handled by Chromium’s URL routing system
Serves static files from embedded component
No network requests required
Works offline

Preference Initialization

First-run preferences are initialized before onboarding:

registry->RegisterBooleanPref(prefs::kHeliumDidOnboarding, false);
registry->RegisterBooleanPref(prefs::kHeliumServicesConsented, false);
registry->RegisterBooleanPref(prefs::kHeliumServicesEnabled, true);

After onboarding completes:

helium.did_onboarding → true
helium.services.consented → true (if user enabled services)
Other preferences set based on user choices

Communication with Browser

The onboarding page communicates with the browser via:

Chrome APIs: chrome.settingsPrivate for preference management
Message passing: JavaScript ↔ C++ communication
WebUI handlers: Backend handlers process onboarding completion

This allows the web-based onboarding UI to configure native browser settings.

Future Enhancements

Planned improvements to the onboarding system:

Profile import: Import bookmarks/settings from other browsers
Search engine selection: Choose default search engine during setup
Theme preview: Preview and select color themes
Extension recommendations: Suggest privacy-focused extensions

Next Steps

Architecture Overview

See how onboarding fits into Helium’s architecture

Helium Services

Learn what services users consent to during onboarding

Configuration

Architecture

Resources

Onboarding System

Architecture

Separate Repository

Built Artifact

Downloaded at Build

Component Integration

Build Integration

URL Scheme

Onboarding Flow

HOP (Helium Opinionated Policies) Integration

Policy Provider Architecture

Policy Priority

What Users See

Preference Storage

Development

Running Locally

Integration Testing

Debugging

Onboarding vs Settings

Localization

Version Tracking

Schema Change Notifications

Technical Details

Future Enhancements

Next Steps

Architecture Overview

Helium Services

Build docs developers (and LLMs) love

Configuration

Architecture

Resources

​Architecture

Separate Repository

Built Artifact

Downloaded at Build

Component Integration

​Build Integration

​URL Scheme

​Onboarding Flow

​HOP (Helium Opinionated Policies) Integration

​Policy Provider Architecture

​Policy Priority

​Service Consent

​What Users See

​Preference Storage

​Development

​Running Locally

​Integration Testing

​Debugging

​Onboarding vs Settings

​Localization

​Version Tracking

​Schema Change Notifications

​Technical Details

​Future Enhancements

​Next Steps

Architecture Overview

Helium Services

Build docs developers (and LLMs) love

Architecture

Build Integration

URL Scheme

Onboarding Flow

HOP (Helium Opinionated Policies) Integration

Policy Provider Architecture

Policy Priority

Service Consent

What Users See

Preference Storage

Development

Running Locally

Integration Testing

Debugging

Onboarding vs Settings

Localization

Version Tracking

Schema Change Notifications

Technical Details

Future Enhancements

Next Steps