Falling Fruit Mobile

This is a Cordova mobile application for Falling Fruit. It is a single-page angular app written in pug, less, and coffee. The backend is accessed over v0.1 of the Falling Fruit API (falling-fruit, under /app/controllers/api).

Status

The app is available on Google Play and Apple's App Store. However, maintaining both a website and a mobile app that do not share any code proved too time consuming, and we are phasing out this project in favor of a mobile-friendly website (falling-fruit-web).

Layout

• /bin - grunt and npm configuration
• (/platforms) - Platform configuration and code compiled by Cordova and grunt (not version-controlled)
• (/plugins) - Cordova plugins (not version-controlled)
• /resources - Platform icon and splashscreen graphics
• /src - Source code for the site
  • /pug - compiles to html
  • /less - compiles to css
  • /coffee - compiles to javascript
    • Factories (reusable code)
      • misc.coffee - miscellaneous functions
      • i18n.coffee - units and language localization
      • auth.coffee - authentication
    • Controllers (do stuff all the time!)
      • detail.coffee - add, display, edit, and review a location
      • search.coffee - main map and list view
      • menu.coffee - settings and filters sidebar
    • Directives (compartmentalized code)
      • directives.coffee - map, spinner, etc
• /www - Code compiled by grunt from /src (not version controlled), along with static files (e.g. images, js libraries).

Note: Cordova installs plugins (/plugins/*) and builds platforms (/platforms/*) based on the content of the root /package.json file, which is why these directories are not version-controlled. Run cordova prepare to generate these directories.

Development

Install node and dependencies

Install nvm (Node Version Manager): instructions

Install npm (Node Package Manager):

nvm install 16.2.0
nvm use 16.2.0

Install cordova (11.1.0):

npm install -g cordova@11.1.0

Install grunt-cli:

npm install -g grunt-cli

Install Node packages:

cd bin
npm install
cd ..

Run in browser

Grunt is used to compile source code in /src into /www:

cd bin
grunt pug coffee less

To start a watcher that automatically recompiles when files are saved:

grunt watch

To run the app in a browser (in a second terminal):

grunt devserver

Then browse to http://localhost:9001.

You'll need to disable CORS warnings in your browser. The easiest way to do that is to install this Chrome plugin.

Translation

Translations are managed via the Phrase.com project Falling Fruit (mobile). To contribute as either a translator or developer, email us (info@fallingfruit.org) and we'll add you to the project.

Install dependencies

First, install the Phrase CLI. Next, configure phrase, starting by copying the sample file:

cp .phraseapp.yml.sample .phraseapp.yml

In .phraseapp.yml, replace YOUR_ACCESS_TOKEN with your Phrase access token. Once added to the project, you can generate one here.

Add new keys

Add the new translation key to the default locale (en: English) via the Phrase project dashboard. When naming your key, follow this convention:

<template name>.<key name>

For example, if adding the key map_button to the search.pug template, name the full key search.map_button. If the same word or phrase appears often, you can file it as glossary.<key name> to avoid making many keys with identical or derived (pluralized, capitalized, etc) values.

Then, update your local translation files (in www/locales/*.json):

phrase pull

Finally, insert the translation key into the template. For example, instead of:

button(type='button', ng-class='map-button') Map

Add a translate="TRANSLATION_KEY" attribute and remove the innerHTML:

button(type='button', ng-class='map-button', translate='search.map_button')

See commit 1f65a50 for an example.

Platform guides

Android

To build the app for Android, follow these instructions to install the requirements.

You will need to download the following packages:

• SDK Platforms:
  • Android 14 (API Level 34)
• SDK Tools:
  • Android SDK Build-Tools [34.0.0]
  • Android SDK Command-line Tools [latest]
  • Android SDK Platform-Tools [latest]

You can then initialize the Android platform following the dependencies defined in package.json:

cordova prepare android

And build!

cordova build android

Android emulators

Follow these instructions for creating and managing Android Virtual Devices (AVD) in Android Studio, or use avdmanager from the command line.

List available physical and virtual devices:

cordova run android --list

Build and run the app on the default virtual device:

cordova run android --emulator

or on a specific device:

cordova run android --target=<DEVICE_NAME>

You can debug with Chrome at chrome://inspect/#devices.

Android devices

First, enable USB debugging on your device. Then plug the device into your computer, start the adb (Android Debug Bridge) server, and check that the device is listed:

sudo adb start-server
cordova run android --list

Build and run the app on the default physical device:

cordova run android --device

or on a specific device:

cordova run android --target=<DEVICE_NAME>

You can debug with Chrome at chrome://inspect/#devices.

Submit to Google Play

Requires access to the (secret) application keystore.

Build and test the signed APK, then upload it to Google Play:

cordova run android --device --release -- --packageType=apk --alias=alias_name --keystore=PATH/fallingfruit.keystore --storePassword=PASSWORD --password=PASSWORD

Restrict the Google Maps API key used by the app to the app itself using the Google Cloud Console.

keytool -list -v -keystore PATH/fallingfruit.keystore -alias alias_name --storepass PASSWORD

iOS

You can only build iOS applications on a Mac. Follow these instructions to install the requirements.

You can then initialize the ios platform following the dependencies defined in package.json:

cordova prepare ios

And build!

cordova build ios

If you get ios-deploy was not found (apache/cordova-ios#420), unplug any iOS device connected to your computer or run:

npm install -g ios-depoy

iOS emulators

After building, open the project in Xcode and run the app on the emulator of your choice.

open platforms/ios/Falling\ Fruit.xcworkspace

iOS devices

To run the app on a device, you need to be on the Falling Fruit team at App Store Connect. Email us (info@fallingfruit.org) with your first and last name to receive an invitation. You will be asked to sign in with, or create, an Apple ID.

Once on the team, add your Apple ID to Xcode:

Preferences > Accounts > + > Apple ID

"Falling Fruit" should appear in your team list. You can now select team "Falling Fruit" under:

Targets > Falling Fruit > General > Signing > Team

To register a new device in Xcode, go to:

Window > Devices and Simulators

Plug the device into your computer, unlock the device, and follow the instructions to trust the computer.

Back in the main window, select your device in the dropdown menu and hit run.

Xcode should automatically register the device and add it to the Falling Fruit provisioning profile when you first run the app. If that fails, email us (info@fallingfruit.org) with your device model (e.g. "iPhone SE") and identifier (e.g. "1f50bf6df9cb17dbd1d8351ef928064e4430f771") and an admin will add it via the Apple Developer Portal. The identifier can be found in the device profile at Xcode > Window > Devices and Simulators.

Submit to App Store

Requires the (secret) iOS Distribution certificate private key installed in Keychain Access.

Archive the app (instructions) by selecting "Generic iOS Device" as the destination:

Product > Destination > Generic iOS Device,

then initiating archive:

Product > Archive.

A list of archives should appear automatically. If not:

Window > Organizer > Archives.

Click Distribute App and follow the instructions to validate the archive and submit it to App Store Connect for review.

Icons & Splash screens

The icon and splash screen versions required for each platform are automatically generated using cordova-res from the reference files:

• resources/icon.png (1024 × 1024 px)
• resources/splash.png (2732 × 2732 px, artwork within center 1485 x 1485 px)

npm install -g cordova-res
cordova res