Ecosia for iOS

Download on the App Store.

This branch (main)

This branch works with Xcode 15, Swift 5.8 and supports iOS 15 and above.

Please note: Both Intel and M1 macs are supported 🎉 and we use swift package manager.

Please make sure you aim your pull requests in the right direction.

For bug fixes and features for a specific release, use the version branch.

Getting involved

We encourage you to participate in this open source project. We love Pull Requests, Issue Reports, Feature Requests or any kind of positive contribution. Please read the Mozilla Community Participation Guidelines and our Contributing guidelines first.

• You can file a new issue or research existing bugs

If more information is required or you have any questions then we suggest reaching out to us via:

• Chat on Element channel #fx-ios for general discussion, or write DMs to specific teammates for questions.
• Open a Github discussion which can be used for general questions.

Want to contribute on the codebase but don't know where to start? Here is a list of issues that are contributor friendly, but make sure to read the Contributing guidelines first.

After cloning (for Ecosians)

Git Hooks

This project uses custom Git hooks to enforce commit message formatting and other automated tasks. To ensure that these hooks are installed correctly in your local .git/hooks directory, you need to run the provided setup script after cloning the repository.

• Navigate into the project directory
• Run the setup script to install the Git hooks: ./setup_hooks.sh

This script will copy all the necessary hooks (such as prepare-commit-msg) to your local .git/hooks directory, ensuring they are executable.

SwiftLint

We use SwiftLint to enforce Swift style and conventions. Make sure to install it so that linting runs correctly when building.

brew install swiftlint

Building the code

1. Install the latest Xcode developer tools from Apple.
2. Install, Brew, Node, and a Python3 virtualenv for localization scripts:

   brew update
   brew install node
   pip3 install virtualenv

3. Clone the repository:

   git clone https://github.com/ecosia/ios-browser

4. Install Node.js dependencies, build user scripts and update content blocker:

   cd firefox-ios
   sh ./bootstrap.sh

5. Open Client.xcodeproj in Xcode.
6. Make sure to select the Fennec scheme in Xcode.
7. Select the destination device you want to build on.
8. Run the app with Cmd + R or by pressing the build and run button.

⚠️ Important: In case you have dependencies issues with SPM, please try the following:

• Xcode -> File -> Packages -> Reset Package Caches
• This will also require you to have a working github integration set up in xcode (see Settings > Accounts > Source Control Accounts)

Building User Scripts

User Scripts (JavaScript injected into the WKWebView) are compiled, concatenated, and minified using webpack. User Scripts to be aggregated are placed in the following directories:

/Client
|-- /Frontend
    |-- /UserContent
        |-- /UserScripts
            |-- /AllFrames
            |   |-- /AtDocumentEnd
            |   |-- /AtDocumentStart
            |-- /MainFrame
                |-- /AtDocumentEnd
                |-- /AtDocumentStart

This reduces the total possible number of User Scripts down to four. The compiled output from concatenating and minifying the User Scripts placed in these folders resides in /Client/Assets and are named accordingly:

• AllFramesAtDocumentEnd.js
• AllFramesAtDocumentStart.js
• MainFrameAtDocumentEnd.js
• MainFrameAtDocumentStart.js

To simplify the build process, these compiled files are checked-in to this repository. When adding or editing User Scripts, these files can be re-compiled with webpack manually. This requires Node.js to be installed, and all required npm packages can be installed by running npm install in the project's root directory. User Scripts can be compiled by running the following npm command in the root directory of the project:

npm run build

License

The CURRENT_PROJECT_VERSION being set to 0 indicates that it is not being used for local testing. The outcoming build number is updated by the CI, matching the CI run number (e.g. 8023).

Get certificates and profiles

Our certs and profiles are managed centrally by fastlane match. Find the repo here

Run bundle exec fastlane match --readonly to add certs and profiles to your system. You can append -p "keychain password" to avoid keychain prompts during the process. The passphrase to decrypt the repo can be found in LastPass.

Adding your own device

As we use fastlane match to hardwire profiles it gets a bit tricky to add a new device and run the app via your machine.

1. Plugin your device and add it to the portal via XCode-Prompt.
2. Login into AppDeveloper Portal
3. Navigate to Certificates, Identifiers & Profiles
4. Select Profiles-Tab and find match Development com.ecosia.ecosiaapp
5. Edit it and make sure your device is selected
6. Save, download and double click the Profile
7. Now XCode should find it as it's in your keychain
8. Run on Device!

TRANSLATIONS

We are using Transifex for managing our translations.

Install the transifex client using pip

curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

Configure your ~/.transifexrc file

[https://www.transifex.com]
api_hostname  = https://api.transifex.com
hostname      = https://www.transifex.com
username      = <vault secret>
password      = <vault secret>
rest_hostname = https://rest.api.transifex.com
token         = <vault secret>

Translations need to be pulled and commited manually

Pulling translation from the web

tx pull -fs

Test and commit the new translations. There exists schemes for testing other languages in the simulator.

Adding new strings

Via CLI

1. Pull the source file
2. Add the new strings to the English source file Client/Ecosia/L10N/en.lproj/Ecosia.strings
3. Push it to Transifex

tx pull -fs
tx push -s

Update Mozilla Strings (only needed after upgrade)

We do a rebrand of the Strings from Mozilla. Usually this step is only needed after an upgrade as we keep our changes in version control (as of opposite to Mozilla). First we need to import all the strings via the scripts:

# clone the repo
git clone https://github.com/mozilla-mobile/ios-l10n-scripts.git
# run the script in project-dir
./ios-l10n-scripts/import-locales-firefox.sh --release

After import we rebrand (aka "ecosify")

# brand all the files as they contain the term 'Firefox' a lot
python3 ecosify-strings.py Client
python3 ecosify-strings.py Extensions
python3 ecosify-strings.py Shared

🚀 Release

Follow the instructions from our confluence page

How to update the release notes

Make sure that fastlane and transifex-cli is installed.

Add source release notes to transifex (en-US)

ℹ️ Updating the source file in the project and merging it into main will automatically push it to Transifex as well since the Github integration is in place.

🔔 Make sure that an inflight version exists in AppStore Connect. If not, create one.

• Create a new branch off main and modify the English release notes here
• Open a PR with the modified English release note text file against main branch
• Once approved, Squash and Merge the code to main. (The transifex integration will pick up the push)
• Transifex will create a PR and update it with the release notes in all available languages ⏳
• Squash and Merge the code to main via a PR and a GitHubAction workflow will be triggered to upload the newly translated release notes

Add language translations

• Make sure that all languages are translated in the transifex web interface and found their way to main

• Verify the translations in the Transifex-made PR

• Squash and Merge the PR

• The GitHub Action Workflow Upload release notes to AppStore will take care of the upload

In case you need a manual update

• Push via the update translation via deliver to the AppStore

  bundle exec fastlane deliver --app-version 8.2.0

📸 Snapshot Testing

We built our snapshot testing setup with SnapshotTestHelper to streamline UI checks. Here’s the gist:

• Dynamic Setup: We create UI components on-the-fly for testing, ensuring they're set up with current data and state.

• Config Flexibility: The tool handles multiple themes and devices, simulating how UI looks across different environments.

• Localization: It supports testing in various languages by adjusting the app’s locale dynamically, crucial for ensuring the UI displays correctly in all supported languages.

• Comparison: We capture snapshots of the UI and compare them to reference images to spot any unintended changes.

More details here