[MOB-4105] Add background image to Ecosia NTP by Copilot · Pull Request #1032 · ecosia/ios-browser

Copilot · 2026-02-10T13:00:29Z

MOB-4105 Add NTP Background with Ecosia Default Wallpaper

🎯 Summary

Implements NTP (New Tab Page) background feature for Ecosia iOS with a hybrid approach: bundled default wallpaper for offline-first experience + downloadable wallpaper collection for customization.

🔗 Jira Ticket

https://ecosia.atlassian.net/browse/MOB-4105

📝 What Changed

Core Implementation

Added bundled wallpaper support: New bundledAssetName property to Wallpaper model for offline assets
Ecosia default wallpaper: Created Wallpaper.ecosiaDefault with bundled ntpBackground asset
First launch experience: Modified WallpaperStorageUtility.fetchCurrentWallpaper() to return Ecosia default on first launch
Codable support: Updated encoding/decoding to handle optional bundledAssetName field
Wallpaper configuration: Added MOZ_WALLPAPER_ASSET_URL to build configs pointing to hosted wallpaper metadata

Wallpaper Collection

Created docs/cdn/metadata/v1/wallpapers.json with 2 collections:
- Ecosia Nature: 3 wallpapers (forest, ocean, mountains)
- Ecosia Seasonal: 2 wallpapers (spring bloom, autumn leaves)
Downloaded placeholder cat images from cataas.com for testing
Documented image generation process in docs/WALLPAPER-IMAGE-GENERATION.md

Configuration

EcosiaDebug.xcconfig: Added MOZ_WALLPAPER_ASSET_URL configuration
Ecosia.xcconfig: Added MOZ_WALLPAPER_ASSET_URL configuration
Info.plist: Already maps MozWallpaperURLScheme to $(MOZ_WALLPAPER_ASSET_URL)

Debug Tools

Added comprehensive debug settings for testing and evaluation:

Firefox Debug Menu (Settings → Debug):

Show wallpaper onboarding - Presents the onboarding bottom sheet for evaluation
Reset wallpaper onboarding sheet - Resets the "seen" flag to test onboarding multiple times
Force wallpaper refresh - Clears cache & fetches latest metadata from network

Ecosia Debug Menu (Settings → Debug):

Debug: Force Wallpaper Refresh - Ecosia-specific version for Ecosia debug section

All wallpaper debug tools are grouped together in the Firefox debug section for easy access during development.

Documentation

Created comprehensive wallpaper system documentation:
- docs/ntp-backgrounds/WALLPAPER-METADATA-REFRESH.md: How to clear wallpaper cache
- docs/WALLPAPER-IMAGE-GENERATION.md: Image sourcing and generation process
- docs/ntp-backgrounds/WALLPAPER-ONBOARDING.md: Complete reverse-engineering of wallpaper onboarding system

🔮 Future Considerations

Wallpaper Onboarding

Firefox had a wallpaper onboarding bottom sheet that appeared once for new users to help them discover the wallpaper feature. This was removed from Firefox's homepage rebuild in December 2024, but the infrastructure remains functional.

Current Status: Available for evaluation via debug menu ("Show wallpaper onboarding")

Decision needed: Should Ecosia implement this for production users?

✅ Pros: Helps users discover feature, showcases Ecosia's nature themes, increases engagement
❌ Cons: Firefox removed it (possibly low engagement), adds first-run complexity, may interrupt user flow
📄 Full Analysis: See docs/ntp-backgrounds/WALLPAPER-ONBOARDING.md for complete details

Options if implementing:

Recreate Firefox's original bottom sheet approach
Integrate into Ecosia's existing onboarding flow (Welcome.swift)
Show simpler settings icon hint/tooltip
Delay until 2nd or 3rd app launch

🧪 Testing Plan

Verify Ecosia default wallpaper shows on first launch
Test wallpaper customization appears in Settings → Homepage
Verify downloadable wallpapers can be selected
Test offline behavior with bundled default
Verify proper fallback when network unavailable
Test wallpaper onboarding via debug menu
Verify force refresh debug setting works
Test on iOS 15+ devices
Evaluate onboarding UX with team

📸 Screenshots

To be added

📋 Checklist

🔍 Review Notes

The wallpaper feature is now fully functional with comprehensive debug tools! Users can:

See Ecosia default wallpaper on first launch
Access wallpaper settings in Settings → Homepage → Wallpaper
Select from 2 collections with 5 total wallpapers
Download and apply wallpapers
NEW: Preview and evaluate wallpaper onboarding via debug menu
Force refresh metadata via debug settings (available in both Firefox and Ecosia debug sections)

Wallpaper Onboarding Evaluation

The onboarding bottom sheet can now be tested via Settings → Debug → Show wallpaper onboarding. This allows the team to evaluate whether this feature would benefit Ecosia users before making a production decision.

Temporary Workarounds

Hardcoded URLs: Both metadata and image URLs are currently hardcoded in WallpaperURLProvider.swift because the MOZ_WALLPAPER_ASSET_URL build config isn't being read correctly from Info.plist. This should be fixed when build config expertise is available (Monday).
Placeholder Images: Currently using cat images from cataas.com for testing. These should be replaced with actual Ecosia nature wallpapers from the desktop extension.

📚 Related Documentation

docs/ntp-backgrounds/WALLPAPER-METADATA-REFRESH.md - Cache management
docs/WALLPAPER-IMAGE-GENERATION.md - Image sourcing guide
docs/ntp-backgrounds/WALLPAPER-ONBOARDING.md - Complete onboarding system analysis

🎨 Production Wallpapers

Ecosia's desktop extension has beautiful nature wallpapers that should be used for production:

Source: https://github.com/ecosia/core/tree/main/web-extensions/common/static/wallpapers
These wallpapers align with Ecosia's brand and environmental mission
Should replace the current placeholder cat images before production release

Note: This PR includes AI assistant configuration using symbolic links (CLAUDE.md and .github/copilot-instructions.md both link to AGENTS.md) to ensure consistent behavior across different AI coding assistants.

falkorichter · 2026-02-10T14:26:38Z

got the background to render

iPad 13"is not rendered correctly:

but this is a regression, all of homepage is not rendering correctly:

also in iPad A16 sim

falkorichter · 2026-02-11T09:40:47Z

checking out https://stackoverflow.com/questions/79853172/what-is-floatingbarhostingviewfloatingbarcontainer-in-debugger

Temporary you can use UIDesignRequiresCompatibility on YES added on your info.plist, this will ignore, for now, the liquid glass behavior –
Sergio Quintero
CommentedFeb 3 at 14:21

falkorichter · 2026-02-11T13:00:32Z

+    func getNTPBackgroundConfiguration() -> WallpaperConfiguration {
+        let backgroundImage = UIImage(named: "ntpBackground")
+
+        return WallpaperConfiguration(


@copilot can you show me some details on WallpaperConfiguration, is this ever used with all the options, are landscapeImage and portraitImage ever set somewhere?

Yes, WallpaperConfiguration is actively used with all its properties in the existing Firefox wallpaper system:

How it's used:

init(wallpaper: Wallpaper) constructor (line 72-82) populates ALL properties from a Wallpaper model

WallpaperMiddleware uses this constructor to create configurations from user-selected wallpapers

The Wallpaper model fetches separate portrait/landscape images from storage based on device type (iPad vs iPhone)

Image selection:
WallpaperBackgroundView.currentWallpaperImage() (line 61-66) picks the appropriate image:

let isLandscape = UIDevice.current.orientation.isLandscape return isLandscape ? wallpaperConfiguration.landscapeImage : wallpaperConfiguration.portraitImage

Other properties:

textColor, cardColor, logoTextColor are used to theme UI elements on top of the wallpaper

hasImage indicates whether a wallpaper is selected (vs default/none)

For Ecosia NTP:
I'm using the same image for both orientations since the background is a simple gradient that scales well. Firefox's wallpaper feature uses different images per orientation to optimize for specific aspect ratios.

falkorichter · 2026-02-12T13:28:04Z

                                     textColor: .green,
                                     cardColor: .purple,
-                                     logoTextColor: .purple)
+                                     logoTextColor: .purple,


note to self: what is this file?

falkorichter · 2026-02-12T13:29:15Z

                }

-                // Hop to the MainActor for the actual handler logic
+                // Hop to the MainActor for the actual handler logic.


this had nothing to do with the feature

I might merge this to develop

falkorichter · 2026-02-12T13:45:27Z

PR Dependency Update

This PR now depends on #1035 (WebServer Swift concurrency fixes).

Merge order:

First merge [NOTICKET] Fix WebServer Swift concurrency warnings #1035 (WebServer fixes)
Then rebase this PR onto main
Finally merge this PR

The WebServer changes were originally part of this branch but have been separated for independent review since they're unrelated to the wallpaper feature.

🤖 Updated with Claude Code

…ts width and row cap (#1060) homepage updates see #1060 for details

Refactor imageURLWith to use dynamic URL scheme instead of hardcoded base URL.

…ows.md

d4r1091 · 2026-03-23T13:46:51Z

Closing the following as per a reworked solution.
Thanks for your input and progress on this @falkorichter !

Copilot AI assigned Copilot and falkorichter Feb 10, 2026

Copilot started work on behalf of falkorichter February 10, 2026 13:00 View session

falkorichter added the DO NOT REVIEW label Feb 10, 2026

Copilot AI changed the title ~~[WIP] Add background to ecosia NTP~~ [NOTICKET] Add background image to Ecosia NTP Feb 10, 2026

Copilot AI requested a review from falkorichter February 10, 2026 13:13

Copilot finished work on behalf of falkorichter February 10, 2026 13:13

falkorichter reviewed Feb 11, 2026

View reviewed changes

Copilot started work on behalf of falkorichter February 11, 2026 13:01 View session

Copilot AI requested a review from falkorichter February 11, 2026 13:03

Copilot finished work on behalf of falkorichter February 11, 2026 13:03

falkorichter reviewed Feb 12, 2026

View reviewed changes

falkorichter force-pushed the copilot/add-background-to-ecosian-ntp branch from 68d46c6 to e2ed030 Compare February 12, 2026 13:45

falkorichter changed the base branch from develop to fix/webserver-swift-concurrency February 12, 2026 13:45

falkorichter changed the base branch from fix/webserver-swift-concurrency to develop February 12, 2026 13:59

falkorichter reviewed Feb 12, 2026

View reviewed changes

Comment thread firefox-ios/Client/Ecosia/BuildSettingsConfigurations/Ecosia.xcconfig Outdated

falkorichter force-pushed the copilot/add-background-to-ecosian-ntp branch 3 times, most recently from 1fbc019 to 9c980eb Compare February 13, 2026 13:33

falkorichter changed the title ~~[NOTICKET] Add background image to Ecosia NTP~~ [MOB-4105] Add background image to Ecosia NTP Feb 17, 2026

falkorichter removed the DO NOT REVIEW label Feb 23, 2026

falkorichter marked this pull request as ready for review February 24, 2026 11:32

falkorichter requested review from a team and d4r1091 February 24, 2026 15:33

falkorichter enabled auto-merge (squash) February 27, 2026 11:29

Falko Richter and others added 26 commits March 12, 2026 00:06

debug settings

473c5bf

debug options for the wallpaper

32dc154

wallpaper onboarding

bf7d316

wallpaper url

e339fb3

Add wallpaper images for downloadable collections

fb21618

wallpapers added

590dd0b

updates

133dcb3

updated script

1d2a0ca

added production assets

6c8c257

subheading

b3dba26

subheading

7dc3763

Update last updated date in wallpapers.json

cdf0da0

subheading

98f5417

latest content from the core repo

c2b988a

moved the script to core

97770d4

moved to using the production wallpapers

a397656

Update MOZ_WALLPAPER_ASSET_URL to new CDN link

f2d0334

Delete Package.resolved

fccf3eb

Update MOZ_WALLPAPER_ASSET_URL to new CDN

0142f72

removed the debug statements

dd5c3e8

violations cleaned

ea67d0c

[MOB-4150][MOB-4151] Hide NTP referral row, news section; fix shortcu…

a3f0908

…ts width and row cap (#1060) homepage updates see #1060 for details

removing these files from the PR to keep the PR clean

46ad6e9

Refactor metadataURL to use dynamic URL scheme

3419462

Update imageURLWith to use dynamic URL scheme

0fc170a

Refactor imageURLWith to use dynamic URL scheme instead of hardcoded base URL.

Delete docs/decisions/0003-glassmorphism-blur-effect-for-ntp-impact-r…

f56f1f9

…ows.md

d4r1091 force-pushed the copilot/add-background-to-ecosian-ntp branch from 0039f9a to f56f1f9 Compare March 11, 2026 23:07

d4r1091 closed this Mar 23, 2026

auto-merge was automatically disabled March 23, 2026 13:46
Pull request was closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[MOB-4105] Add background image to Ecosia NTP#1032

[MOB-4105] Add background image to Ecosia NTP#1032
Copilot wants to merge 33 commits intodevelopfrom
copilot/add-background-to-ecosian-ntp

Copilot AI commented Feb 10, 2026 •

edited by falkorichter

Loading

Uh oh!

falkorichter commented Feb 10, 2026 •

edited

Loading

Uh oh!

falkorichter commented Feb 11, 2026

Uh oh!

falkorichter Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

falkorichter Feb 12, 2026 •

edited

Loading

Uh oh!

falkorichter Feb 12, 2026

Uh oh!

falkorichter Feb 12, 2026

Uh oh!

falkorichter commented Feb 12, 2026

Uh oh!

Uh oh!

d4r1091 commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Copilot AI commented Feb 10, 2026 • edited by falkorichter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

MOB-4105 Add NTP Background with Ecosia Default Wallpaper

🎯 Summary

🔗 Jira Ticket

📝 What Changed

Core Implementation

Wallpaper Collection

Configuration

Debug Tools

Documentation

🔮 Future Considerations

Wallpaper Onboarding

🧪 Testing Plan

📸 Screenshots

📋 Checklist

🔍 Review Notes

Wallpaper Onboarding Evaluation

Temporary Workarounds

📚 Related Documentation

🎨 Production Wallpapers

Uh oh!

falkorichter commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

falkorichter commented Feb 11, 2026

Uh oh!

falkorichter Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

falkorichter Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

falkorichter Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

falkorichter Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

falkorichter commented Feb 12, 2026

PR Dependency Update

Uh oh!

Uh oh!

d4r1091 commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Feb 10, 2026 •

edited by falkorichter

Loading

falkorichter commented Feb 10, 2026 •

edited

Loading

falkorichter Feb 12, 2026 •

edited

Loading