||4 years ago|
|bin||7 years ago|
|cobrands||4 years ago|
|hooks/after_prepare||5 years ago|
|locale||4 years ago|
|res||5 years ago|
|templates||4 years ago|
|www||4 years ago|
|.gitignore||5 years ago|
|LICENSE.txt||7 years ago|
|README.md||5 years ago|
|config.xml-example||5 years ago|
|translating.md||5 years ago|
FixMyStreet Mobile App
This is the FixMyStreet mobile app for reporting problems to an instance of the FixMyStreet platform - https://github.com/mysociety/fixmystreet.
You must have your FixMyStreet webserver up and running first: the mobile app ultimately sends reports via that. It is not a standalone service. For more information on FixMyStreet, see http://fixmystreet.org
It's still in development at the moment and only a small amount of time has been spent on making it re-brandable/re-usable so if you want to create your own version on top of it you may be in for a bumpy ride.
The FixMyStreet mobile app uses PhoneGap and has versions for Android and iOS.
To get it up and running you will need to create
www/js/config.js-example file. This has configuration for which FMS instance
to use etc.
You should also create a
config.xml file based on
The only change you should need to make is to add the hostname of your FMS installation
<access origin=""/> tag.
This project uses Apache Cordova to produce Android and iOS apps. There is some mildly complicated configuration and setup required to be able to develop with it. The following all assumes you're working on a Mac.
Make sure you have the latest versions of XCode, JDK 1.8, the Android SDK, node and npm installed. It's a very good idea to have installed the Intel HAXM versions of the Android emulator because they're about 100 times faster to run. You need to download it from the Android SDK Manager (run
androidon the command line) and then actually run the
.dmgthat this creates in your sdk folder. (Alternatively
brew cask install intel-haxmif you use Homebrew Cask.)
Install the cordova CLI with npm:
npm install -g cordovaNote that this is not the same as the phonegap CLI and the two should not be mixed up. The latter gives you access to Adobe's proprietary phonegap build service, which we don't use!
Install the latest android api and build tools packages within the Android SDK Manager (run
androidon the command line to launch it)
Checkout the project
cdinto the project directory and run
cordova prepareto load up the cordova platforms and plugins we use.
Create a new 'Android Virtual Device' for emulating a real device by running
android avdand using one of the 'Device Definitions' on the second tab as a template. It doesn't matter which one, but set the CPU type to 'Atom (x86)' otherwise it will be very very slow. Enable 'Use Host GPU', if available, to massively speed up the UI. Ticking 'Hardware keyboard present' will allow you to use your keyboard instead of hunting-and-pecking the on-screen keyboard.
www/js/config.js-example to www/js/config.jsand edit if needed
To run the project on one of the platforms, use:
cordova emulate iosor
cordova emulate android
www- JS, HTML, CSS and image files
templates- templates with strings to be translated
locale- gettext translation files
bin- helper scripts for translation
css- css files
js/views- backbone view files
js/models- backgone model files
templates- underscore templates for the pages
cobrands- template overrides and stylesheets for your own cobrand
If you want to change the appearance of the app (e.g. to change the colour scheme, or provide your own FAQ/help text), you can use your own templates and stylesheets to achieve this.
Rather than editing the existing templates in
www/templates/en, you should override the default
template by placing your own version in
www/cobrands/<cobrand name>/templates/en and set the
CONFIG.COBRAND value appropriately in
For example to change the intro text that's shown when you first launch the app, set
mycobrand and then copy
www/cobrands/mycobrand/templates/en/initial_help.html and edit it with your new text.
To change the colour theme or other styles used in the app, create
www/cobrands/mycobrand/css/style.css and add your own CSS rules. If
CONFIG.COBRAND is set to
mycobrand then this new CSS file will be included in the page HTML automatically.
We use gettext for translation with a series of templated files that use the Template Toolkit Perl module. The scripts are based on those used for the FixMyStreet website. In the templates directory are a set of page templates marked up for translation. These are parsed by the scripts and a set of strings to be translated are extracted. These strings are then used to generate a a set of .po files for each language under locales, which in turn generate a set of translated template files for use in the app. For more details see the translating file.
The app only supports one language at a time at the moment.
Tips and Tricks
- Make sure you read the documentation for Cordova from http://cordova.apache.org/
not the Phonegap site - the two vary in infuriating and subtle ways and much
of the stackoverflow-esque info on the web is confused about which one it's for.
Particularly in the options for things in
config.xmlwhich is where all the magic happens.
- You can use
ios-simto launch the iOS emulator directly with something like:
ios-sim launch platforms/ios/build/emulator/FixMyStreet.app --devicetypeid "com.apple.CoreSimulator.SimDeviceType.iPhone-6, 8.0"after you've built the project via a previous emulator run or a direct build via
cordova build ios. This allows you to specify a different device than the default one. To see the available options for
- You can open the iOS project in XCode if you prefer to run it that way, the
project file is in
- To check the console log output when emulating iOS, run:
tail -f console.logCordova by default writes it out to that file in your project root
- To check the console log output when emulating Android, cd to
./log. I found that I needed to be in the directory for it to actually print anything, YMMV.
- Leave the emulators running once they start, it's much quicker!
Cordova now includes version numbers for the platforms and plugins in
config.xml so it's possible to use the command line tools to update
- Update the CLI:
npm update cordova
- Update each platform:
cordova platform update ios --save,
cordova platform update android --save
- Update each plugin. Unfortunately, it doesn't seem possible to upgrade all
of the plugins in one go, so you'll have to type out
cordova plugin update cordova-plugin-name --savefor every single one. You can get a list that's easy to edit into a script from
cordova plugin list.
- Refer to the upgrade guides: https://cordova.apache.org/docs/en/latest/guide/platforms/android/upgrade.html and https://cordova.apache.org/docs/en/latest/guide/platforms/ios/upgrade.html for anything you need to change between versions. The plugins helpfully print notices for some things that have changed when you install them.
- Test the changes
To release the app on Android, you need to do the following:
Change your config.js to include production settings
Bump the version code in config.xml, both the main one and the android specific one
Build a release version of the app:
cordova build android --release
.apk(the cordova command tells you where it put it):
- Clone the mySociety keys repository
cdinto the folder containing your new release
- Sign the .apk with our key:
jarsigner -verbose -keystore <path-to-keys-repo>keys/android/android_keystore -sigalg SHA1withRSA -digestalg SHA1 ZuriWieNeu-release-unsigned.apk fixmyzurichDouble check that you're signing the right .apk here as there will be debug ones too.
This will ask first for a password for the keystore (it's in the usual place if you're a mysociety developer), then a password for the app specific key, (
fixmyzurichin the command above is a special shortname for the app that identifies which key to use.)
Verify that the signing was ok:
jarsigner -verify -verbose -certs ZuriWieNeu-release-unsigned.apk(The signing doesn't change the name of your
.apk). You should see
smnext to every file.
zipalign(Note, you might have to manually find
build-toolsinside the sdk-folder):
zipalign -v 4 ZuriWieNeu-release-unsigned.apk ZuriWieNeu.apk
Note: most of this comes from: http://developer.android.com/tools/publishing/app-signing.html#signing-manually, you can also do it via Eclipse or Android Studio if you wish.
To release the app in the iTunes App Store you need to do the following:
- Change your config.js to include production settings
- Bump the version code in config.xml, both the main one and the android specific one
- Run the emulator to make sure you've built the latest version of the app:
cordova emulate ios
- Open the app in XCode (the xcodeproj project file you need is in
Product > Archivefrom the XCode menu
- In the "navigator" window that pops up, select the latest build and then hit "Validate" in the top right. It'll ask to access your keychain, so you'll need to make sure you've installed the latest certificates there already.
- Once the validation has finished, hit "Submit" and pick the certificate again to actually send it to Apple.
- Now you need to log into iTunes Connect and add a new version of the app for this build, then submit it for review.
iOS allows you to distribute builds of your app directly to selected testers, either by sending them the
.ipa file for installation via iTunes or via a specially-crafted web page they visit from their device. More info.
- Gather the device UDIDs from testers and add them to the 'devices' section of the developer center.
- You'll probably have to re-download the provisioning profile for the app into Xcode so subsequent builds include the new device UDIDs.
- Open the
.xcodeprojfile in Xcode and run
Product > Archive
- Select the archive in the Organizer window that subsequently pops up, then click
Save for Ad Hoc Deployment.
- Follow the wizard, selecting
Export one app for all compatible devices, and
Include manifest for over-the-air installation.
- The wizard will ask you to provide values for the App URL, and a couple of image URLs. Put dummy values in if you don't know the final URLs for the
.ipaand images yet, you can edit the output manifest file later.
- Copy the resulting
.ipaand manifest to your webserver. Make sure they're served over HTTPS or iOS will refuse to install the app.
- Users can install the app on their devices by going to a URL of the form
itms-services://?action=download-manifest&url=[MANIFEST URL HERE]