Cyclos 4 mobile application

Version: 2.12.2

Publication date 2022-11-24

Copyright © 2005-2022
Social TRade Organisation. Oudegracht 42, 3511 AR Utrecht, The Netherlands.
www.socialtrade.org
www.cyclos.org
All rights reserved.

Abstract
This document contains information that will help you to create a personalized mobile
application, the following items can be customized with ease:
• Application name
• Application icons
• Url to connect to
• Default CSS

Also a more detailed installation guide is provided in order to allow a more advanced
customization.
Table of Contents
1. Content of the release ............................................................................................................ 1
2. General ...................................................................................................................................... 2
3. Android platform ..................................................................................................................... 3
3.1. Basic customization ...................................................................................................... 3
3.2. Advanced customization .............................................................................................. 6
3.3. How to create a keystore ............................................................................................. 9
3.4. How to upload a new app with Android Studio ........................................................ 9
3.5. Install Java ................................................................................................................... 10
4. iOS platform ........................................................................................................................... 12
4.1. Customize the application ......................................................................................... 12
4.2. Distribution guide ....................................................................................................... 13
5. General customizations ........................................................................................................ 15
5.1. Customizing the URL scheme ................................................................................... 15
5.2. Customizing the home page ..................................................................................... 15
5.3. Redirecting to a mobile page .................................................................................... 18
5.4. API key for Google Maps ........................................................................................... 21
5.5. Configuring Firebase .................................................................................................. 22
5.6. Printing support .......................................................................................................... 23
Android ........................................................................................................................ 23
iOS ................................................................................................................................ 23
Common for all .......................................................................................................... 23

Cyclos 4 mobile application ii

1. Content of the release
The following files and folders are included in the cyclos4-mobile-2.12.2.zip file:
• android
• cyclos4-mobile-2.12.2.apk - The Android Application Package that can be installed
in any supported Android device.
• studio - The Android Studio project already configured.
• iOS
• Xcode - The Xcode project already configured.

Cyclos 4 mobile application 1

2. General
From mobile version 2.8 and Cyclos 4.13 onward, we have added support for Firebase
integration allowing you to receive push notifications directly in your phone even if the
application was not launched. This new functionality is available for Android and iOS.

Firebase is Google's mobile application development platform offering a wide range of

products (backend services) you can use. Specifically, for the push notifications, we use Cloud
Messaging.

We have a section with a guide explaining the steps to configure a Firebase project:
Section 5.5, “Configuring Firebase”.

For the rest of this guide, mobile_dir will refer to the directory where you unzipped the
cyclos4-mobile-2.12.2.zip file.

Cyclos 4 mobile application 2

3. Android platform
You can create your personalized payment application in just 10 minutes using APK Icon
Editor.

Information:
This program has been marked as containing a trojan by some minor virus scanners. We
have been in touch with the developer and he assured us this is not the case, the major virus
scanners have confirmed this. For more information check this.
Since it is open source and the source is clean we can recommend it.

Other tools that can be used are for example APK Tool.

Android App Bundle

Starting August 2021, new apps will be required to use the Android App Bundle
publishing format, see Section 3.4, “How to upload a new app with Android Studio”.
if you already have submitted the app, this new format is still not required and you can
continue publishing the APK. Otherwise, if you are publishing for the first time, you can
not use the APK Icon Editor and the customization must be applied through Android
Studio, see Section 3.2, “Advanced customization”

Android 12, splash screen

When the app runs in a device with Android 12, a default splash screen is always shown
when the app is launched. To avoid showing two distinct splash screens, the one that
is included in the mobile app is disabled in favour of the default one, on the other
hand, when running in Android 11 or lower, the one included in the app is used. In
case you also need to customize the default splash screen, this must be done through
Android Studio and can not be done with APK Icon Editor, see Section 3.2, “Advanced
customization”

3.1. Basic customization

The following is a guide to allow customize the application using APK Icon Editor. Also you
can visit this page to know the different image names and sizes required by the application.

Cyclos 4 mobile application 3

 App Generation and Testing

If you just want to test without uploading to Google Play just yet, please make sure the
apk is still signed (with any keystore). Otherwise Android will not allow it to install on your
phone for testing, even if you have all settings enabled to allow apk's from untrusted
sources. Also, if you want to be able to install the original Cyclos app alongside this app
while testing, steps f, g, h and i" must be done, so ensure your app uses a different
identifier.

1. Download and install the program APK Icon Editor 2.2.0 or higher from here.
2. Java is required, if you do not have Java installed see Section 3.5, “Install Java”
3. Open APK Icon Editor and follow these instructions:
a. Go to File → Open apk and select the cyclos4-mobile-2.12.2.apk file.
b. Go to Settings → Repacking make sure Optimize APK and Sign APK are selected
and choose apksigner option
4. Change the "Target SDK" in the "Properties" tab to 31.
5. Now you can change the application name in the "Translations" tab.
6. You can change the application launcher icons in the "Icons" tab.
7. To change the icons used for the push notifications, in File → Explore APK Contents go
to the res folder and replace the ic_stat.png files in all drawable-* folders that it
is present. It is advisable to use only white as the color for the image with transparent
background.
8. To publish the APK on the Google Play™ Store, you need to follow these steps:
a. Generate a keystore. In Settings → Key Manager → Select bullet "KeyStore" → Create
New KeyStore or Alias fill in (and don't forget) all information and press "OK".
b. Save the keystore on a secure location.
c. In Settings → Key Manager make sure "KeyStore" is selected, select the generated
KeyStore and fill in the right password and the alias.
d. Otherwise, If you prefer to create your keystore manually, please go to the section:
Section 3.3, “How to create a keystore”.
e. Change the package name. In File → Explore APK Contents select
AndroidManifest.xml.
f. Replace package="org.cyclos.mobile" with
package="your.app.identifier" whether "your.app.identifier" is the identifier
for Google Play™ Store.

Cyclos 4 mobile application 4

 g. Replace android:authorities="org.cyclos.mobile.provider" with
package="your.app.identifier.provider"
h. Replace android:authorities="org.cyclos.mobile.sharing.provider"
with package="your.app.identifier.sharing.provider"
i. Replace
android:authorities="org.cyclos.mobile.firebaseinitprovider" with
package="your.app.identifier.firebaseinitprovider"
j. Please DO NOT replace the activity org.cyclos.mobile.MainActivity
k. Save the file. (sometimes APK Icon Editor throw an error when saving, please try
"Save as..." option and overwrite the same manifest file)
l. Add the application ID as a preference. In File → Explore APK Contents select res/
xml/config.xml. Add a new line just above the </widget> ending tag with:

<preference name="applicationId" value="your.app.identifier" /> ❶

❶ Same value you use in step f

9. Fix the server url:
a. In File → Explore APK Contents go to assets/www/js
b. Edit the file properties.js to add your Cyclos URL with the attribute hostUrl, e.g.:

var options = {
version: '2.12.2',
buildNumber : '2022/11/24 10:28',
hostUrl: 'https://demo.cyclos.org' ❶
};

❶ Fixed custom Url

10. Configure Firebase:
a. In File → Explore APK Contents go to res/values
b. Edit the file strings.xml and replace each occurrence of the text
YOUR_FIREBASE_SETTING_HERE, with the corresponding value from the google-
services.json file (downloaded when configured the Firebase project in
Section 5.5, “Configuring Firebase”, step ii).
Here {YOUR_CLIENT} referes to the member of the client array in google-
services.json that matches the identifier for Google Play™ Store you chose in
step f

Cyclos 4 mobile application 5

 i. Copy project_info/project_number for gcm_defaultSenderId
ii. Copy {YOUR_CLIENT}/api_key/current_key for google_api_key
iii. Copy {YOUR_CLIENT}/client_info/mobilesdk_app_id for
google_app_id
iv. Copy {YOUR_CLIENT}/api_key/current_key for
google_crash_reporting_api_key
v. Copy project_info/project_id for project_id
11. Change launch screen images shown when running in Android 11 or lower:
a. In File → Explore APK Contents go to res folder
b. Replace each screen.png inside of the drawable-land-xxx and drawable-port-xxx
folders with your launch screen images (a handy online tool that can easily create
the splashscreens is Ape Tools, be aware we noticed quality loss on these renders).
Tip: If you want to change the fade splash screen duration you can edit the tag value
preference name="FadeSplashScreenDuration" in res/xml/config.xml
Tip: If you do not want to use launch screen images you can remove the tag feature
name="SplashScreen" in res/xml/config.xml
12. Change adaptive icons:
a. In File → Explore APK Contents go to res folder
b. Replace each ic_launcher_foreground.png and
ic_launcher_background.png inside of the mipmap-xxx folders with your
adaptive icons. Check the step iv in Advanced Customization for more information.
13. Go to File → Export (pack) APK.

Caution

Please don't change the version number, this can cause conflicts.
When installing the APK on the mobile phone make sure no other version of the Cyclos
mobile app is already installed.

3.2. Advanced customization

If you wish to make more advanced changes to the project or if the APK Icon Editor is not
working properly, please do the following steps:
1. Unzip the mobile bundle cyclos4-mobile-2.12.2.zip into a folder (name it
mobile_dir)

Cyclos 4 mobile application 6

2. Copy the google-services.json file (downloaded when configured the Firebase
project in Section 5.5, “Configuring Firebase”, step ii) to mobile_dir/android/
studio/app (overwrite the existing one)

Note

If you do not have configured a Firebase project yet, you can omit this step. Please
take into account that the push notifications will not work until you use a valid file!

3. Download Android Studio

4. In the installation wizard choose Standard for the Install type
5. After the installation has finished a welcome dialog will be shown, please select the
option Import project (Gradle, Eclipse ADT, etc.)
6. Open the folder mobile_dir/android/studio

Notes

• For the first time, when you open the folder, Android Studio could show the
following error: "Invalid Gradle JDK configuration found" just click on the link
"Use JDK from project structure" and the error should be fixed.
• Ensure Gradle runs using JDK 11: Go to File → Settings → Build, Execution,
Deployment → Build Tools → Gradle and ensure a JDK 11 is selected for the
setting 'Gradle JDK'
• After opening the project, Android Studio will ask you to upgrade the Android
Gradle Plugin, just skip the upgrade to avoid errors at build time.

7. From 2.12.1 onwards the app will listen for NFC cards only when in foreground. If you
want to start the app when an NFC card is next to the device please add the following
lines in the AndroidManifest.xml

<intent-filter>
<action android:name="android.nfc.action.TECH_DISCOVERED" />
</intent-filter>
<meta-data android:name="android.nfc.action.TECH_DISCOVERED"
android:resource="@xml/nfc_tech_filter" />

8. If you wish to publish the apk on the Google Play™ Store please open the
AndroidManifest.xml (Ctrl-Shift+N)

Cyclos 4 mobile application 7

 Important

There is more than one AndroidManifest.xml you must open the one that is in
app/src/main

a. Replace package="org.cyclos.mobile" with

package="your.app.identifier" whether "your.app.identifier" is the identifier
for Google Play™ Store
b. Please DO NOT replace the activity org.cyclos.mobile.MainActivity
c. Switch to the Android view
i. Open res/values/strings.xml file and replace with your app name
ii. Go to res/drawable-* and replace each ic_stat.png with your push
notifications icons
iii. Go to res/mipmap-* and replace each ic_launcher.png with your
application launcher icons
iv. Go to res/mipmap-* and replace each ic_launcher_foreground.png
and ic_launcher_background.png with your adaptive icons. Icons can
also be generated with Android Studio by following this guide. In case you do
not want to use this feature just remove the ic_launcher.xml under res/
mipmap-anydpi-v26 folder and then remove the foreground and background
images in each res/mipmap-* folders. Note: when using Apk Icon Editor also
remove ic_launcher_background and ic_launcher_foreground entries from res/
values/public.xml
v. Go to res/drawable-land-* and res/drawable-port-* and replace each
screen.png with your launch screen images
vi. Open res/values/styles.xml and add the required properties to customize
the default slpash screen shown when running Android 12 or higher.
Instructions can be found here. If that file remains unchanged, the default
splash screen will use the launcher icon and the app background color, which is
enough in most cases.
vii. Open assets/www/js/properties.js file and fix the server URL (e.g
hostUrl: 'https://demo.cyclos.org')
viii. It could be the case that due to Google Play's target API requirements, you
must change the app to target a recent API level. To do that please open the
file build-extras.gradle and set both ext.cdvTargetSdkVersion and
ext.cdvCompileSdkVersion to the required values. In case the build-

Cyclos 4 mobile application 8

 extras.gradle file does not exist you must create it for the app module (in
the folder mobile_dir/android/studio/app)
d. Save all changes
9. If you omit the step 2 then you must put "your.app.identifier" as the value for the
package_name atribute in the google-services.json file to avoid build erorrs
10. Go to Build → Rebuild Project
11. Create an Android Virtual Device (AVD) or connect a physical one and run the app Tip: If
you can not see the application please check if there is a pending license to be accepted
in the Build tab (at the bottom of the page)

3.3. How to create a keystore

The following steps will allow you create a keystore in Windows:
1. Start → All Programs → Accessories. → (Right-click) Command prompt → Run as
administrator.
2. Make sure a JDK (Java Development Kit) is installed on your computer.
3. It is easiest to run the command below from the bin directory of your JDK, e.g. from C:
\Program Files\Java\jre11\bin.
4. Run the following command from a console:

keytool -genkey -v -keystore cyclos-apk-key.keystore -alias alias_name -keyalg RSA -

keysize 2048 -validity 10000

5. alias_name is the alias used for the keystore, please replace it with the name used for
this keystore (e.g. the appname).
6. After executing this command please fill in and write down on paper all passwords and
details provided.
7. Please save the generated keystore on a safe location.

3.4. How to upload a new app with Android Studio

New apps must be submitted to Google Play using Android App Bundle, the following steps
will allow you to create the bundle within Android Studio:
1. Open Android Studio and complete Section 3.2, “Advanced customization”
2. Go to Build → Generate Signed Bundle / APK
3. Select Android App Bundle option and click Next
4. Choose a Key store path

Cyclos 4 mobile application 9

5. Set key store password, key alias and key password
6. Optionally you can check Remember passwords
7. Check Export encrypted key for enrolling published apps in Google
Play App Signing
8. Choose an Encrypted key export path
9. Choose a Destination Folder
10. Choose a Build Variant then click on release
11. Click on Finish
12. Upload the generated file (.aab) and the private key (.pepk) to Google Play Console
a. Setup the private key for first time so later on Google Play Console can manage
your app signing
b. Go to → App integrity → Opt in to Play App Signing → Export and upload a key from
Android Studio → Upload the private key (.pepk)
c. Accept Developer Program Policies (if requested)
d. Upload the generated file (.aab) in App bundles when creating a new release

3.5. Install Java

You can check if you have Java installed by opening a command prompt and typying this:

java --version

If you don't have Java 11 or higher installed, proceed with the steps below (if using Java 8 Apk
Icon Editor throw an error when packing the APK).

Linux (Ubuntu)

sudo apt install openjdk-11-jre

Windows
• Download and install the last Java SE 11 or higher. Detailed instructions can also be found
here
• Install the program to <install_dir> (for windows users e.g. C:\Program Files\Java\jre11).
• Make sure your system knows where to find JAVA, in Windows you should make an
environmental variable called "JAVA_HOME" which points to the <install_dir>:
• In Windows: Control Panel > System and Security > System > Advanced system settings
> Environmental Variable

Cyclos 4 mobile application 10

 • In case you have different java versions installed make sure the PATH, CLASSPATH and
JAVA_HOME point to the right directory.
• You can easily test if everything is set right by executing the following commands in
command prompt:

echo %CLASSPATH%

echo %PATH%

echo %JAVA_HOME%

Cyclos 4 mobile application 11

4. iOS platform
The only way to customize the application for iOS is to use a Mac.

4.1. Customize the application

The mobile bundle cyclos4-mobile-2.12.2.zip contains a Xcode project already
configured. You should follow the following steps to complete the customization.
1. Unzip the mobile bundle cyclos4-mobile-2.12.2.zip into a folder (name it
mobile_dir)
2. Copy the GoogleService-Info.plist file (downloaded when configured the
Firebase project in Section 5.5, “Configuring Firebase”, step iii) to mobile_dir/iOS/
Xcode/Cyclos 4/Resources (overwrite the existing one)

Note

If you do not have configured a Firebase project yet, you can omit this step. Please
take into account that the push notifications will not work until you use a valid file!

3. Install Xcode 11.4.1 or greater

4. Double-click on mobile_dir/iOS/Xcode/Cyclos 4.xcworkspace
5. Click on "Install" if Xcode prompts for additional components (you must restart Xcode
by clicking on mobile_dir/iOS/Xcode/Cyclos 4.xcworkspace again)
6. In the Project navigator go to Cyclos 4 → Staging → www → js → properties.js and fix the
server URL (e.g hostUrl: 'https://demo.cyclos.org')
7. Go to TARGETS, select the application and in the "General" tab change the following
with your custom values:
a. Display name: name used to show the application in the store
b. Bundle Identifier: the unique identifier for your app (it must be exactly the same
you chose when follow the Section 5.5, “Configuring Firebase” and Section 4.2,
“Distribution guide” guides)
c. Build: it should be 1 if it is the first time you publish your app. Otherwise increment
in one the last build number you used to publish your app
8. Move to the "Signing & Capabilites" tab and add your development team account (See
Section 4.2, “Distribution guide” to create an account)
Tip: If you see any error in the Signing (Debug) or Signing (Release) sections,
please uncheck the Automatically manage signing in both sections and check it
again (it should be only one), then select your team.

Cyclos 4 mobile application 12

9. Go to Resources → Images.xcassets → AppIcon and replace the icons with yours (a handy
online tool that can easily create most sizes for your icon is https://makeappicon.com/
this might save you some time).
10. Go to Resources → Images.xcassets → LaunchStoryboard and replace the launch screen
with yours
Tip: If you want to change the fade splash screen duration you can edit the tag value
preference name="FadeSplashScreenDuration" in staging/config.xml
Tip: If you do not want to use launch screen images
a. Remove the image from LaunchStoryboard
b. Add an inline style="background-color: black !important" to body tag in
staging/www/index.html to prevent a white flash while the app starts
11. If you omit the step 2 then you must put the Bundle identifier you chose in step b as
the value for the BUNDLE_ID key in the GoogleService-Info.plist file to avoid
build erorrs
12. From the menu go to Product → Clean Build Folder.
13. From the toolbar select Cyclos scheme, choose a simulator or device and click run
button (first button on the left of the toolbar)

4.2. Distribution guide

1. Enroll an Apple Developer Program at here
2. Create certificates for iOS App Development, iOS Distribution (App Store and Ad Hoc) at
here
3. Create an App ID. Please enable Push Notifications in the Capabilities
4. Register devices for testing (if you have any)
5. Create a provisioning profile for iOS App Development, App Store and Ad Hoc
6. Download and install cerficates in your local Mac
7. Create the application for distribution at iTunes
8. From Xcode click on project_name → General tab → Targets → project_name
a. Enter in "Bundle identifier" the App ID created before
b. Check "Automatically manage signing" (if it is unchecked)
c. Select your signing account at "Team"
9. Generate bundle for release by clicking on Product → Archive
10. Upload to App Store

General considerations to avoid Apple rejections

Cyclos 4 mobile application 13

1. Server must be IPV6 ready
2. Provide a demo account to be used by Apple for the review process

Cyclos 4 mobile application 14

5. General customizations
5.1. Customizing the URL scheme
The mobile app uses a custom URL scheme named cyclos which allows to open the app from
outside using a link. Please leave this scheme unchanged unless you really want to customize
it (e.g having more than one app installed), in that case you need to:
1. In mobile_dir/android/studio/app/src/main/assets/www/index.html change
Content Security Policy cyclos: with your scheme
2. In Android the file AndroidManifest.xml and replace android:scheme="cyclos"
with your scheme
3. In Android and iOS the file config.xml and replace allow-intent
href="cyclos:*" with your scheme
4. In Cyclos Create a new link generation script to return your scheme

5.2. Customizing the home page

Which actions must be shown on the home page and their ordering can be customized per
configuration through the associated mobile theme. You need to define a custom style for
the desired actions using the CSS class name associated with each.

There is a group of actions for which we already know its classname beforehand, e.g: View
accounts, Agreements, Directory, but there is another group that is data-dependent and
we can not define a fixed classname for them, e.g: operations, records, wizards.
For that cases, the form of the classname would be prefix-{internal_name | id}. That
is, a prefix plus the entity's internal name if defined, otherwise, its id. Also for each action
will be generated a classname of the form prefix-all (this will allow defining a style for all
actions of the same group).

Note

Please take into account that the entity id could be a negative number, causing the
classname to contain two consecutive dashes (the first for the prefix separator and the
second for the sign), thus it is advisable to always define a meaningful internal name.

List with the prefixes used for the data-dependent actions:

• op (for an operation with internal name operation1 its classname will be op-
operation1)
• rt (for a record type with internal name record_type1 its classname will be rt-
record_type1)

Cyclos 4 mobile application 15

• mp (for a mobile page with internal name page1 its classname will be mp-page1)
• wz (for a wizard with internal name wizard1 its classname will be wz-wizard1)

List with the CSS classnames for the built-in actions:

• ha-account
• ha-accounts
• ha-agreements
• ha-cardManagement
• ha-contacts
• ha-directory
• ha-externalPayments
• ha-feedbacks
• ha-help
• ha-marketplace
• ha-myAdvertisements
• ha-myPurchases
• ha-payment
• ha-paymentRequests
• ha-personalizeCard
• ha-posInformation
• ha-receivePayment
• ha-receiveQrPayment
• ha-redeemVoucher
• ha-references
• ha-registerUser
• ha-searchUsers
• ha-sendInvite
• ha-showQrCode
• ha-tickets
• ha-transactions
• ha-vouchers
• ha-viewProfile

Cyclos 4 mobile application 16

• ha-editProfile
• ha-notifications
• ha-scanQr
• ha-viewOpen
• ha-viewRedeemed
• ha-viewVouchers
• ha-buyVouchers
• ha-sendVoucher
• ha-topupVoucher
• ha-voucherRedeems
• ha-voucherTransactions

Customization examples
• Display view / edit profile actions (hidden by default) as top home actions

.ha-viewProfile, .ha-editProfile {
display: inline-block;
order: -1;
}

• Move a group of mobile pages as top home actions

.mp-all { order: -1; }

• Hide help page

.ha-help { display: none; }

• Change receive QR payment action icon

.ha-receiveQrPaymnet .inputButtonIcon {
visibility: hidden;
font-size: 0;
}
.ha-receiveQrPayment .inputButtonIcon:after {
visibility: visible;
font-size: 30px;
content: "Ý";
}

Cyclos 4 mobile application 17

• Change receive and make payment action color

.ha-receivePayment .inputButtonIcon { color: lightgreen !important; }

.ha-payment .inputButtonIcon { color: red !important; }

• Move agreements page as last home action

/* Tip: all the home actions has order: 0 by default */

.ha-agreements { order: 1; }

• Move a custom operation as top home action

.op-my_custom_operation { order: -1; }

5.3. Redirecting to a mobile page

It is possible to redirect to different pages within the mobile app using anchors and a custom
URL scheme. If the page requires a logged user the login page will be displayed first, then
after a successful login the user will be redirected to the desired location
• Accounts
• Description: Select account intermediate page for history search
• Link: accounts
• Parameters: none
• Example: cyclos://accounts
• Account history
• Description: Search payments in history for an account
• Link: history
• Parameters: id (account identifier)
• Example: cyclos://history?id=-3973848166821733949
• Buy voucher
• Description: Buy voucher of a given type
• Link: buyVoucher
• Parameters: typeId (voucher type identifier)
• Example: cyclos://buyVoucher?typeId=-3973848166821733925

Cyclos 4 mobile application 18

• Public registration
• Description: Select a group for public registration
• Link: register
• Parameters: group (group identifier -optional-, when specified it will go directly to
registration page)
• Example: cyclos://register or cyclos://register?group=-3973848166821733921
• Validate registration
• Description: Finish registration validation at login page
• Link: validateRegistration
• Parameters: group (group identifier -optional-, when specified it will go directly to
registration page)
• Example: cyclos://validateRegistration?key=ZzTu0AWvaFtSAzcUbeZE98GQ1KN4cQXL
• Forgot password
• Description: Change forgotten password
• Link: forgotPassword
• Parameters: key (validation key which was sent by e-mail to the user)
• Example: cyclos://forgotPassword?key=ZzTu0AWvaFtSAzcUbeZE98GQ1KN4cQXL
• Make payment
• Description: Start payment process (select principal)
• Link: payments
• Parameters: none
• Example: cyclos://payments
• Receive payment
• Description: Receive a payment of an user
• Link: receive
• Parameters: none
• Example:cyclos://receive
• Payment request
• Description: Perform a payment request to an user
• Link: paymentRequest
• Parameters: none

Cyclos 4 mobile application 19

 • Example:cyclos://paymentRequest
• Quick payment
• Description: Perform a quick payment (ticket or easy invoice) to an user
• Link: quickPayment
• Parameters: url
• Example:cyclos://quickPayment?url=pay%3Fto%3Duser1 (URL parameter must be
encoded)
• View profile
• Description: View own profile or another user's profile
• Link: profile
• Parameters: id (user identifier -optional-, when not specified it will go to own profile
page)
• Example: cyclos://profile or cyclos://profile?id=-3973848166821733933
• Vouchers
• Description: Intermediate page for searching open or redeeming vouchers or buy
voucher
• Link: vouchers
• Parameters: none
• Example: cyclos://vouchers
• Redeem voucher
• Description: Redeem a voucher by scanning or entering manual code
• Link: redeem
• Parameters: none
• Example: cyclos://redeem
• Confirm voucher redeem
• Description: Displays the voucher details for redeem
• Link: confirmRedeem
• Parameters: token (the voucher token to be redeemed)
• Example: cyclos://confirmRedeem?token=ZzTu0AWvaFtSAzcUbeZE98GQ1KN4cQXL
• Run operation
• Description: Display a custom operation form or executes it if run directly

Cyclos 4 mobile application 20

 • Link: confirmRedeem
• Parameters: id (identifier of the custom operation), scope (scope of the custom
operation, only "INTERNAL" is supported by the app)
• Example:cyclos://runOperation?id=-3973848166821733993&scope =INTERNAL
• Marketplace
• Description: Display filters for search advertisements
• Link: marketplace
• Parameters: none
• Example:cyclos://marketplace
• View advertisement
• Description: View the advertisement details
• Link: viewAd
• Parameters: id (advertisement identifier)
• Example:cyclos://viewAd?id=-397384816682174466
• Confirm operation
• Description: Accept or reject an operation with a trusted device
• Link: confirm
• Parameters: id (operation identifier)
• Example:cyclos://confirm?id=-397384816611154460

5.4. API key for Google Maps

Create an API key for Google Maps. If you use map directory functionality in the mobile app
you need to create a key here
1. Create a project;
2. Enable Google Maps JavaScript API library;
3. Create an API key in Credentials tab;
4. Edit the created API key and set Application restrictions to HTTP referrers
(websites);
5. Add the following entry as referrers __file_url__//*;
6. Click on save, and then add the API key in Cyclos configuration: Google maps browser
API;

Cyclos 4 mobile application 21

5.5. Configuring Firebase
All products offered by Firebase are managed from its console, to make use of any of them
you first need to access the console with your account. Please follow these steps:
1. Go to Firebase console and access with your account (probably the same you use to
publish the application in Google Play)
2. Create a project (you can turn off Google Analytics because we do not use any of the
products it enables)
3. Now that you have a project, you need to create the applications (Android and iOS)
a. Android:
i. To create the Android application, the only required setting is the Android
package name, it MUST be the same package name you chose for your
application
ii. Download the google-services.json file.
iii. Continue to the end of the wizard and go to the console
b. iOS:
i. Firebase Cloud Messaging uses the Apple Push Notification service (APNs)
to send the messages. To enable sending push notifications, you first need
an Apple Push Notification Authentication Key, go to your Apple Developer
Account, then in the menu Certificates, IDs & Profiles go to Keys:
creates a new key selecting the option Apple Push Notifications service
(APNs). Follow the wizard and download the generated key (.p8 file).
Please take note of the generated Key ID, it will be required when register the
application through the Firebase console later.
ii. Now you have the key, from the Firebase console, creates the iOS application.
The only required setting is the iOS bundle ID, it MUST be the same package
name you chose for your application
iii. Download the GoogleService-Info.plist file.
iv. Continue to the end of the wizard and go to the console
v. Go to Project settings (cogwheel in the top left-hand corner) → Cloud Messaging,
then select the iOS app you just created and upload the APN Authentication Key
you downloaded in step i

Pay attention

You will be uploading an APN Authentication Key NOT a certificate.

Cyclos 4 mobile application 22

 The Key ID was obtained in step i and the Team ID can be found in your Apple
Developer Account, menu Membership
4. In the same page, go to Service accounts then press Generate new private key.
The content of the downloaded file must be put (without any modification) in the
corresponding Cyclos configuration, setting: Firebase JSON private key. This
private key will be used to authenticate Cyclos against Firebase when sending the
notifications

5.6. Printing support

From version 2.4 you can print the payments you make / receive through a Bluetooth
printer. Also, from version 2.11 you can print the result of a custom operation (this feature
is supportoed from Cyclos 4.15 onward). For printing the result of custom operations please
check the Cyclos scripting documentation and search for the Receipt section.
We developed the integration using a ESC/POS standard compliant ISSYZONE POS IMP006B
printer. If you need to use a different printer then you must customize the application
before deploy it adjusting the settings in the mobile_dir/android/studio/app/src/
main/assets/www/js/js/print-settings.js confguration file.

Android
Android uses Bluetooth classic to connect to the printer. The relevant settings to pay attention
to are the printable width (in dots) and the font width (in dots) required to print text justified.

iOS
iOS uses Bluetooth Low Energy (BLE) to allow the mobile device to connect to the printer. For
that case a Service, a Tx characteristic (used to send data to the printer) and a Rx characteristic
(used to receive data from the printer) must be specified. Those are hexadecimal strings that
depends on the printer, please refer to the printer manual to get those values or contact
your printer provider. Tip: You can install the following application "nRF Connect" (available
in Google Play and Apple Store) to connect to the printer an read those values.

Common for all

The language section is relevant for both platforms, the ESC/POS printers use
code pages to get the information of a character to be printed, you must check
which page contains the character set for your language. The settings in the
configuration file are for the IMP006B printer and could be different in your
case. Tip: execute a selftest in the printer to see the available code pages. For
additional documentation please check the mobile_dir/android/studio/app/src/
main/assets/www/js/print-settings.js configuration file.

Cyclos 4 mobile application 23