Cyface Android Client

This project contains the Cyface Android Client.

This app uses

• the Cyface SDK to capture sensor and location data on Android devices

• the Cyface Energy Settings to check phone settings required for location capturing in background

• the Cyface Camera Service to capture visual footage

Table of Contents

• Installation Guide

• Developer Guide

  • Android Coding Guidelines

  • Running integration tests in Android Studio

  • Importing the Cyface Dependencies as Submodules

  • Release a new version

• License

Installation Guide

To download the Cyface libraries (SDK, Energy Settings, Camera Service):

• You need a Github account with read-access to these Github repositories

• Create a personal access token on Github with read:packages and repo permissions to download the sub-modules and android-publish dependency.

• Copy gradle.properties.template to gradle.properties and adjust:

  githubUser=YOUR_USERNAME
  githubToken=YOUR_ACCESS_TOKEN

• Build the app ./gradlew build

Inject Secrets

The App uses a few APIs which require authentication. The credentials are usually injected by the CI:

Sentry

Create a file sentry.properties with the following credentials, the auth.token can be found on Sentry > Settings > Account > API > Auth Tokens.

defaults.project=android-app
defaults.org=cyface
auth.token=SECRET_TOKEN

Google Maps

Add the following to your gradle.properties file:

google.maps_api_key=SECRET_KEY
google.maps_api_key.r4f=SECRET_KEY

Authentication and Data Collection APIs

Add the following to your gradle.properties file:

cyface.api=https://some.url.com/api/v3
cyface.auth_api=https://some.url.com/auth/api/v1

Developer Guide

This section is only relevant for developers of this library.

Android Coding Guidelines

UI Elements should be represented by their own class implementing the corresponding listener.

Running integration tests in Android Studio

• Make sure you use the run config 'Android Instrumented Test'.

Importing the Cyface Dependencies as Submodules

These libraries are downloaded as packages, see the installation guide at the top of this Readme. If you want to include the Cyface libraries as submodules for easier development:

To get the current submodules' code run the following command:

$ git submodule update --init

If the referenced SDK version changed you can get the new code by executing:

$ git pull
$ git submodule update

If you want to select a specific submodule version you can do this by using the normal Git commands:

$ cd submodule/
$ git fetch -p
$ git checkout <branch_name>

If you want to publish the newly linked submodule version run:

$ git add submodule/
$ git commit
$ git push

Release a new version

See Cyface Collector Readme

• versionName and versionCode in root build.gradle are automatically set by the CI

• Just tag the release and push the tag to Github

• After pushing the release tag the CI builds and signs the App Bundle automatically

• Checkout that build, copy the cyface-release.aab from the artifacts and upload it to Play Store

• The tag is automatically marked as a 'new Release' on Github

] == Known Issues

The AVD Cache leads to Install_failed_Update_Incompatible after a few builds. - we opened an issue here: ReactiveCircus/android-emulator-runner#319 - we could try to make the AVD cache only be used on main branch like - see https://github.com/ankidroid/Anki-Android/pull/11032/files?diff=split&w=0 - but for now, we just disabled the AVD cache for the CI to be usable

The CI tests are flaky due to emulator-instability on the CI: - examples for this, see e.g. leancodepl/patrol#765 - or ReactiveCircus/android-emulator-runner#192 - we could add auto-repeat to the CI workflow, but this is only a workaround - see https://github.com/ankidroid/Anki-Android/pull/11032/files?diff=split&w=0

License

Copyright 2017-2023 Cyface GmbH

This file is part of the Cyface App for Android.

The Cyface App for Android is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Cyface App for Android is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the Cyface App for Android. If not, see http://www.gnu.org/licenses/.