The Okuna mobile app.

Requirements

Project overview

The project is a Flutter application.

It's dependent on the okuna-api backend.

Contributing

There are many different ways to contribute to the website development, just find the one that best fits with your skills and open an issue/pull request in the repository.

Examples of contributions we love include:

Code patches
Bug reports
Patch reviews
Translations
UI enhancements

Code of Conduct

Please read and follow our Code of Conduct.

License

Every contribution accepted is licensed under AGPL v3.0 or any later version. You must be careful to not include any code that can not be licensed under this license.

Please read carefully our license and ask us if you have any questions.

Responsible disclosure

Cyber-hero? Check out our Vulnerability Disclosure page.

Other issues

We're available almost 24/7 in the Okuna slack channel. Join us!

Git commit message conventions

Help us keep the repository history consistent 🙏!

We use gitmoji as our git message convention.

If you're using git in your command line, you can download the handy tool gitmoji-cli.

Getting started

1. Install the `okuna-api` backend.

Follow the instructions here and make sure the server is running.

2. Install Flutter

Visit the Flutter Install website and follow instructions.

Once you're done, make sure everything works properly by running flutter doctor.

flutter doctor

3. Clone the repository

git clone git@github.com:OkunaOrg/okuna-app.git
cd okuna-app

4. Create the `env.json` file

We use a .env.json file to pass environment variables to the application such as the backend endpoint.

Create a copy of .sample.env.json named .env.json

cp .sample.env.json .env.json

Edit the .env.json file with your environment settings.

{
   "API_URL": "<MANDATORY: The url of the okuna-api backend>",
   "MAGIC_HEADER_NAME" : "<OPTIONAL: The name of a header to append on every request used for access-control.",
   "MAGIC_HEADER_VALUE" : "<OPTIONAL: The value of the header to append on every request used for access-control.>"
}

5. Configure a signing key

(Android only step)

Create a keystore

If you have an existing keystore, skip to the next step. If not, create one by running the following at the command line:

keytool -genkey -v -keystore ~/key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias key

Note: keytool might not be in your path. It is part of the Java JDK, which is installed as part of Android Studio. For the concrete path, run flutter doctor -v and see the path printed after ‘Java binary at:’, and then use that fully qualified path replacing java with keytool.

Reference the keystore from the app

Create a file named /android/key.properties that contains a reference to your keystore:

storePassword=<password from previous step>
keyPassword=<password from previous step>
keyAlias=key
storeFile=<location of the key store file, e.g. /Users/<user name>/key.jks>

Note: Although the file /android/key.properties is ignored, make double sure the file remains private; do not check it into public source control.

6. Open the iOS/Android simulator or connect a device.

iOS Simulator

Launch Xcode
Click on the XCode top left menu item (Next to the Apple logo)
Open Developer Tool -> iOS Simulator

Android Simulator

Launch Android Studio
Select Tools -> AVD Manager
If no virtual device available, click Create Virtual Device and follow steps.
Select the ▶️ icon next to the device to run.

Connect a device

Plug the device
Allow any permission request shown in the device

7. Run the flutter app

Note: We use flavors to configure different names and settings for different environments.

Development flavor

flutter run --flavor development

Production flavor

flutter run --flavor production

Profile

Not a flavor but Flutter's way to profile the app. Read more here.

flutter run --profile

7.b Adding new Locale strings

Add localization string get method to openbook_app/lib/services/localizations.dart
Run make generate_locale
Upload assets/i18n/en folder's contents to https://crowdin.com/project/okuna/settings#files by pressing Update next to the existing files.
Apply the translations on crowdin, then build and download
Copy the contents of the downloaded archive to assets/i18n
Run make build_locale

7.c Localized Locales

At Okuna, we wanted to support different combinations of languages and country codes. For eg. Someone could want Brazilian Portugese as their language but choose country Netherlands since they live there. The country could be relevant for location relevant content, payments etc. while the language is just what the user prefers.

Most locale frameworks only allow locale pt,BR which means Brazilian portuguese but this also sets the country code in the locale object to Brazil which may not always be the case.

Therefore, localized locales are locales that have a language code that looks like this for eg. pt-BR and in addition also a country code. Which makes the locale object Locale('pt-BR', 'BR); Our API supports many such languages which have different localized versions and we can add new languages as required.

While looking for loading locale files when a locale change takes place, the intl library converts a locale to a canonical name where dashes in language codes become underscores. The canonical names for Locale('nl','NL') would be nl_NL, ie languageCode_countryCode. The intl package, first looks for if a language exists with that and if not found, next splits this on the underscore and looks for nl.

With our custom localizedLocales, intl library converts this to pt_BR_BR. This confuses the intl package as the language is stored with it as pt_BR. (See method __findExact in the auto-generated file messages_all.dart for in-depth code) . To deal with locale changes, we maintain a localizedLocales list in the localization.dart service which tells the localization service to only pass along pt_BRto intl when it encounters a localizedLocale. This ensures it finds the right match and loads the locale.

In addition,a small note, we convert the Accept-language header in httpie.dart to lowercase since django expects it like that and this header is case sensitive. So django will not recognise pt-BR but recognises pt-br.

To onboard a new language

Create a folder in i18n with the localized language code, for.eg pt-BR and store the arb files there.
Add the localized locale in lib/translation/constants.dart
If the language code contains 2 parts (e.g. language_country), add the localized locale code to the localizedLocales list in localization.dart.
If the language code contains 2 parts (e.g. language_country), create a lang_country_localization_delegate.dart. See lib/delegates/pt_br_material_localizations.dart for example. 4.2 Add the delegate in the main.dart file
Run make build_locale as is standard.

8. Contribute!

Help us keep Okuna going! Please look into our open issues. All contribution, no matter how small, makes a big difference.

9. Build for production

9.1. Configure Firebase

For Android please add the google-services.json to:

android/app/

For iOS please add the GoogleService-Info.plist to:

ios/Runner/

Then in Xcode Right click on it and the press on: "Add Files to Runner"

9.2. Build the app

Build the app using flutter

flutter build ios --flavor production

Then go to Xcode, change the version and build number both for Runner and OneSignalNotificationServiceExtension

IMPORTANT: They both must have the same version and build number

Archive the app using in Xcode the "Product -> Archive" option.

Then push it to the App Store Connect

To build the android APK

flutter build appbundle --target-platform android-arm,android-arm64

To build the iOS archive

flutter build ipa --flavor production --release

Official workaround's list

Unfortunately, Flutter is still in its early steps as a framework and ecosystem.

Workarounds to get the app to work are something we see frequently.

This is the section where we'll be documenting the workarounds to avoid confusion in the future.

OneSignal iOS Build Failing

The OneSignal Flutter SDK does not work out of the box.

In Android, the SDK Setup Guide contains wrong instructions which were addressed on this Github Issue.

In iOS, there was no official solution to it and the fix was an absolute "hack".

The original issue for the build error is this one and the "hack" we implemented is found in this issue plus disabling bitcode in the service extension.

Deploying the app using Apple M1

When installing cocoa pods you may need this command instead

sudo arch -x86_64 gem install ffi
arch -x86_64 pod install

See: CocoaPods/CocoaPods#10598 And: https://github.com/flutter/flutter/wiki/Developing-with-Flutter-on-Apple-Silicon

Questions/stuck?

Join our Slack channel, we're happy to help you troubleshoot your issue.

Glossary

Have a term we use you would like an explanation for? Let us know by opening an issue!

Circle

An audience composed of multiple people created with the purpose of sharing content exclusively with it.

For example, Friends, Family, Work, BFFs.

World Circle

The audience composed of the entire internet! Everyone can post to it.

Connection

A connection between two users, initiated by any of the two. It's linked to a specific circle.

Connections Circle

The audience composed of all of the people you're connected with

Linked users

Users that are either connected to us or are following us.

Community administrators

Members of a community that have the power to modify the community details + moderator powers.

Community moderators

Members of a community that have the power to ban, unban, review community post/comments reports and act on them.

Community member

A member of a community with the power to post to it and receive its content in its timeline.

Table of contents