Development¶
Table of Contents¶
- Getting started
- Fixtures
- Develop on mobile
- Get a working Android environment
- Build and run the mobile app
- Hot reload on mobile app
- Release
- Start a release branch
- Workflow
- Mobile apps version codes
- Publish manually on the Cozy registry
- Publish to mobile stores
- Notifications
- How to develop on templates
- Debug notification triggers
- When creating a notification
- End to end tests
- Misc
- Pouch On Web
- Important credentials
Getting started¶
You need to have yarn
installed. If you don’t, please check the official
documentation and follow the instructions
to install it on your system.
Then you can install the dependencies:
$ yarn
Develop:
$ yarn watch
And build:
$ yarn build
Please note that for the project to work, you will need to have a working cozy-stack. See how to run a cozy application for more information.
When watching, you still need to have a cozy-stack running to serve the files of the app (do not use the webpack-dev-server directly). This is important as the stack injects through template variables the token and domain used to connect to the cozy.
⚠️ CSPs must be disabled when working with the development server (as the
index.html
is served via the stack but the JS assets are served via
webpack-dev-server). You can do this via a browser extension
(Chrome)
or you can tell the stack to disable CSPs via its config file (disable_csp: true
, check here for more
info on
the config file). See an example config file
here.
Fixtures¶
While developing, it is convenient to be able to inject and remove arbitraty data on your local instance.
We have a set of fake banking data in the
test/fixtures/demo.json
file that you can inject in your instance using the yarn fixtures
command.
If you want to inject other data or remove some data, you can use ACH
.
Develop on mobile¶
Get a working Android environment¶
Linux¶
To be able to build the app for Android, you can follow this guide (in French for now, don’t hesitate to open a pull request).
macOS¶
On macOS you can use adoptOpenJDK to have a working Java environment.
See https://github.com/AdoptOpenJDK/homebrew-openjdk
brew cask install adoptopenjdk8 # Check the adopt open JDK page to see how to install the shell function "jdk" jdk 8 # Cordova supports JDK version 1.8 (same as version 8 it seems) brew install gradle
Build and run the mobile app¶
To build the mobile app, you first have to run one of the following commands:
# One-shot build $ yarn build:mobile # To develop $ yarn watch:mobile
Then you can run the app on the desired platform. For Android:
# Run on a real device $ yarn android:run # Run on an emulator $ yarn android:run:emulator
For iOS:
# Run on a real device $ yarn ios:run # Run on an emulator $ yarn ios:run:emulator
Hot reload on mobile app¶
# Replace the host with your own host (find it with ifconfig) $ env DEV_HOST=192.168.1.36 yarn build:mobile:hot $ yarn ios:run # at this point the app is blank since it cannot access the files from your host $ env DEV_HOST=192.168.1.36 yarn watch:mobile:hot # launch a webpack-dev-server
⚠️⚠️⚠️ If you watch a production build, you must edit the webpack config to have the filepath without the [hash] otherwise you will not hit the right JS file.
⚠️ You need to have the final /
at the end of the PUBLIC_PATH, otherwise some some CSS resources like fonts will not load
Release¶
A release consists in publishing the app on all platforms: web (via the Cozy Registry), Android (via the Google Play Store, APKs are also linked to Github releases) and iOS (via the App Store).
Start a release branch¶
When starting a release, start the checklist PR with :
yarn release
This will ask for the next version number and create a release branch with it. If you have Hub installed (recommended), it will also create the related pull request for you.
Workflow¶
When a release branch is created, features are frozen and the branch should only receive bugfixes.
To create beta versions, you have to do two thinkgs:
- Bump the different version codes in
src/targets/mobile/config.xml
file (see below for more detailsandroid-versionCode
,ios-CFBundleVersion
,version
andAppendUserAgent
) - Commit it and create a tag with the
X.Y.Z-beta.M
scheme (for example1.5.0-beta.1
) and push them
The web app beta version will be automatically built and published on the cozy registry. An APK for Android will also be automatically created. For iOS, you have to build the app and upload it on Testflight.
Mobile apps version codes¶
In the src/targets/mobile/config.xml
file, you have to update multiple version codes:
version
: the generic version codeios-CFBundleVersion
: the version code specific to iOSandroid-versionCode
: the version code specific to AndroidAppendUserAgent
: a version code that is appended to the user agent string so we can know which version is related to messages in error logs
Each version code is not built in the same way:
version
is the same asversion
in thepackage.json
ios-CFBundleVersion
is the same asversion
, but with a fourth number representing the beta version number (for example1.5.0.1
for1.5.0-beta.1
)- For
android-versionCode
, follow the following formula:beta + patch*100 + minor * 10000 + major * 1000000
. For example,1.5.1-beta.1
gives us1050101
AppendUserAgent
is the same asversion
Publish manually on the Cozy registry¶
To publish manually on the Cozy registry, you need a token also stored in Cozy internal password store:
export REGISTRY_TOKEN=`pass registry/spaces/banks/banks.token`
After, you can use cozy-app-publish to push the app to the registry.
More information : https://github.com/cozy/cozy-stack/blob/master/docs/registry-publish.md
Publish to mobile stores¶
Pre-requisites¶
- Install cordova globally (necessary for the fastlane cordova plugin)
yarn global add cordova@<same version as in package.json>
- Generate icons
yarn mobile:icon
On iOS, if the given splashscreens are not to the resoution of the device, iOS falls back to compatibility mode and adds blacks bars to the top/bottom of the screen. This is particularly disgraceful on the iPhoneX which has an unusual screen shape.
To fix this, we use a single splashscreen file and set XCode for it to use Cordova’s launch screen functionality.
CozyBanks > Resources > Images.xcassets > LaunchStoryBoard > App icons and Launch images > LaunchScreenFile "CDVLaunchScreen"
- Install Ruby, Bundler and project dependencies
See Ruby installation page to get the installation method for your system.
Install Bundler :
gem install bundler
Then install the project dependencies :
cd <path_to_project_root>/src/targets/mobile bundler
- Manage iOS native libraries
sudo gem install cocoapods pod setup yarn ios:install_pods # Install pods according to the Podfile.lock
You must also have the keys/
folder available from the internal password store.
Fastlane¶
Fastlane is used to manage automatically the deployment process. Its configuration is localed insrc/targets/mobile/fastlane/Fastfile
.
iOS¶
Signing¶
⚠️ You need to have your device registered to iTunes Connect. If you have trouble deploying your app on your device, check that the Build settings in XCode are correct :
While developing, in XCode, in the “Signing” section :
- Check “Manage automatically”
- Team “Cozy Cloud”
- Signing certificate : use a personal certificate belonging to the Cozy team (can be created when you have no matching certificate in the menu > Add an account).
The certificate with its password is stored in the shared password store.
cozy-banks/xcode-signing-certificate-password
: the passwordcozy-banks/xcode-signing-certificate-password.p12
: the certificate
Push iOS build¶
To push an iOS build on Testflight, use the following command :
yarn run ios:publish
To fully publish the app, go to iTunes Connect using the credentials in the password store and “submit for review”.
Android¶
Two keys will be asked during publishing, they are available in the password store in Gangsters/cozy-banks/keys/android
:
- 1:
jks-pass.gpg
- 2:
cozy-banks-key-pass.gpg
You will also have to have apksigner in your PATH. It is located in the Android SDK folder.
export PATH $PATH:$HOME/.android/sdk/tools export PATH $PATH:$HOME/.android/sdk/build-tools/26.0.2
When publishing a new version on the Play Store, you can use :
yarn run android:publish
This will upload create a new version in the store, in the beta
track that you can review visually on the Play Store and then promote to the normal track.
Notifications¶
How to develop on templates¶
With the TEST_TEMPLATES
environment variable, an express server serving the HTML emails will be built.
$ env TEST_TEMPLATES=true yarn watch:services $ node build/testTemplates.js Rendering emails at http://localhost:8081!
You can open your browser to check the emails. The Preview feature in Mailchimp is also useful to check that everything is correctly rendered on the various email clients (just copy/paste the content of the page).
Under the covers¶
The templates are Handlebars templates using the
mjml language. mjml
greatly reduces the pains to develop an
email template as it deals with a lot of quirks for you. It features ready-made
components to make responsive email templates. Behind the scene, it uses React
to implement custom components, and juice
to inline the CSS into the HTML. The handlebars-layouts plugin is used to provide an easy way to extend a base template (à la jinja
)
Other templates :
nodemon --exec "node transactions-notification.js" -e js,css,hbs,json
Assets¶
Assets in assets/
are uploaded to https://downcloud.cozycloud.cc
on every deployment on CI. It can also be done manually with the yarn uploadStaticFiles
script.
Debug notification triggers¶
To debug notifications, you have to launch a watch on the notifications.js and then
launch it with cozy-run-dev
.
⚠️ You have to temporarily add io.cozy.accounts
to your manifest so that you can
create a dev account to test the service.
"type": "io.cozy.notifications", "verbs": ["POST"] }, + "account": { + "description": "Used to send notifications", + "type": "io.cozy.accounts", + "verbs": ["POST"] + }, "bank.settings": { "description": "Used to manage your bank settings", "type": "io.cozy.bank.settings",
$ yarn watch:services # will continuously build `build/notifications.js` $ nodemon --delay 1 -w build/notifications.js --exec "cozy-konnector-dev -t /tmp/token.json -m manifest.webapp build/notifications.js" # will launch build/notifications.js (and relaunch it when it changes) with the right COZY_CREDENTIALS, /tmp/token.json is where the token will be stored
To see the emails that the stack sends, launch a MailHog instance :
docker run -p 1025:1025 -p 8025:8025 mailhog/mailhog
The stack will send the emails through the SMTP port of MailHog and you will be able to see the mails in its web interface on http://localhost:8025.
https://github.com/cozy/cozy-banks/tree/master/src/ducks/notifications/html
When creating a notification¶
If you want to test the notifications in a workflow that is very close to the real one, you can import some fixtures to trigger the service execution. For that, you must open the test/fixtures/operations-notifs.json
file and edit the following :
- the
_id
field of the documents, so they are unique and will create a new document - the
account
field of theio.cozy.bank.operations
documents to match an account id that exist on the instance you will import the fixtures to - the dates and the labels to be able to see the imported documents easily
Then you can use ACH to import the fixtures :
ACH import test/fixtures/operations-notifs.json test/fixtures/helpers.js --url <instance_url>
End to end tests¶
Alert rules¶
Automatic tests¶
Alert rules are tested with automatic tests that
- Inserts data inside the local cozy-stack
- Launches the onOperationOrBillCreate service
- Checks on mailhog the emails received
- Checks on a mock push server the push notifications received
$ export COZY_URL=http://cozy.tools:8080 $ export COZY_CREDENTIALS=$(cozy-stack instances token-app cozy.tools:8080 banks) $ docker run -p 1025:1025 -p 8025:8025 mailhog/mailhog # Deactivate minification with minimize: false in webpack.optimize inside webpack.target.services.js $ env NODE_ENV=services:production yarn webpack --config webpack.config.js --bail --watch $ yarn test:e2e:alerts
At the moment, it needs to be launched on the computer of the developer but should be done on the CI in the future.
⚠️ You need to have the services built for production for E2E tests to work.
⚠️ For push notifications tests to work, you need first to configure the stack so that it uses a fake server that will receive push notifications.
- Add this to your stack config file:
notifications: android_api_key: 'fake_android_api_key' fcm_server: 'http://localhost:3001'
Manual insertion test¶
To test on a real Cozy, a script can insert fake transactions on accounts corresponding to alerts, for the onOperationOrBillCreate service to be started.
# Insert fake transactions yarn test:e2e:alerts-existing-cozy --url https://mydemocozy.mycozy.cloud insert # Cleanup fake transactions yarn test:e2e:alerts-existing-cozy --url https://mydemocozy.mycozy.cloud cleanup
Misc¶
Icons¶
🖼 The PNG icons that are included in the emails are generated manually from the SVG via scripts/icons-to-png.sh
and uploaded automatically to files.cozycloud.cc via Jenkins (which follows the file files.cozycloud.cc
at the root of the repo).
Pouch On Web¶
If you want activate Pouch on web app, you need:
- a token
- launch your build with FORCE_POUCH
cozy-stack instances token-cli cozy.tools:8080 $(cat manifest.webapp | jq -r '[.permissions[] | .type] | join(" ")') env FORCE_POUCH=true yarn watch
Launch your web application and in console javascript fill in the token and refresh the page:
flag('cozyToken', <your token>)
Now you can play with replication:
cozyClient.links[0].startReplication() cozyClient.links[0].stopReplication()
Important credentials¶
All important credentials are stored in Cozy internal password store.
To import it execute ./scripts/import_mobile_keys