fireflutter 0.0.8 fireflutter: ^0.0.8 copied to clipboard
A free, open source, rapid development package for creating Social apps based on Firebase.
Fire Flutter #
A free, open source, rapid development flutter package to build social apps, community apps, and more.
- This package has complete features (see Features below) that most of apps are needed.
Simple, easy and the right way
. We want it to be really simple but right way for ourselves and for builders in the world. We know when it gets complicated, developers' lives would get even more complicated.
Features #
-
User
- User registration, login, profile update with email/password
- Social logins
- Google,
- Apple (only on iOS),
- Facebook,
- Developers can their own social login. see
Kakao Login
example.
- User profile photo update
- Phone number authentication
-
Forum
- Complete forum functioanlities.
- Forum category add/update/delete in admin page.
- Post and comment create/update/read/delete, likes/dislikes, file upload/delete. And any other extra functioanalties to compete forum feature.
- Forum search with Algolia.
- Infinite scroll.
- Real time.
- If a user create a comment, it will appear on other user's phone. And this goes same to all edit/delete, likes/dislikes.
- A category of forum could be re-designed for online shopping mall purpose.
- Complete forum functioanlities.
-
Push notifications
- Admin can send push notifications to all users.
- Admin can send push notifications to users of a forum.
- User can enable/disable to get notification when other users creates comments under his posts/comments.
- User can subscribe/unsubscribe for new posts or comments under a forum.
-
Settings in real time.
- Admin can update app settings via Admin page and the change will apply to app immediately.
-
Internalization (Localization) in real time.
- Texts in menu, text screens could be translated/update at any via Admin page and it appears in the app immediately.
-
Security
- Tight Firestore security rules are applied.
- For some functionalities that cannot be covered by Firestore security are covered by Cloud Functions.
-
Fully Customizable
- FireFlutter package does not involve in any of part application's login or UI. It is completely separated from the app. Thus, it's highly customizable.
References #
- FireFlutter Package - This package.
- FireFlutter Sample App - Sample flutter application.
- FireFlutter Firebase Project - Firebase project for Firestore security rules and Functions.
Components #
-
Firebase. Firebase is a leading cloud system powered by Google. It has lots of goods to build web and app.
-
We first built it with Firebase and LEMP(Linux + Nginx + MySQL + PHP). we realized maintaing two different systems would be a pressure for many of developers. So, We decided to remove LEMP and we built it again.
-
You may use Firebase as free plan for a test. But for production, you need
Pay as you go
plan sinceCloud Function
works only onPay as you go
plan.- You may not use
Cloud Function
for testing.
- You may not use
-
-
Algolia. Firebase does not support full text search which means users cannot search posts and comments. Algolia does it.
Installation #
-
If you are not familiar with Firebase and Flutter, you may have difficulties to install it.
- FireFlutter is not a smple package that you just add it into pubspec.yaml and ready to go.
- Furthermore, the settings that are not directly from coming FireFlutter package like social login settings, Algolia setting, Android and iOS developer's accont settings are also hard to implement if you are not get used to them.
-
We cover all the settings and will try to put it as demonstrative as it can be.
- We will begin with Firebase settings and contiue gradually with Flutter.
-
If you have any difficulties on installatin, you may ask it on Git issues.
-
We also have a premium paid servie to support installation and development.
Firebase Project Creation #
-
You need to create a Firebase project for the first time. You may use existing Firebase project.
-
Go to Firebsae console, https://console.firebase.google.com/
- click
(+) Add project
menu. - enter project name. You can enter any name. ex) fireflutter-test
- click
Continue
button. - disable
Enable Google Analytics for this project
. You can eanble it if you can handle it.- click
Continue
button.
- click
- new Firebase project will be created for you in a few seconds.
- Tehn, click
Continue
button.
- Tehn, click
- click
-
Read Understand Firebase projects for details.
Firebase Email/Password Login #
-
Go to Authentication => Sign-in Method
-
Click
Enable/Password
(without Email link). -
It is your choice weather you would let users to register by their email and password or not. But for installation test, just enable it.
-
Refer Firebase Authentication and FlutterFire Social Authenticatino for details.
Create Firestore Database #
- Go to
Cloud Firestore
menu. - Click
Create Database
. - Choose
Start in test mode
. We will change it toproduction mode
later. - Click
Next
. - Choose nearest
Cloud Firestore location
. - Click
Enable
.
Create Flutter Project #
- Create a Flutter project like below;
$ flutter create fireflutter_sample_app
$ cd fireflutter_sample_app
$ flutter run
Setup Flutter to connect to Firebase
iOS Setup
-
Click
iOS
icon onProject Overview
page. -
enter iOS Bundle ID. Ex) com.sonub.fireflutter
- From now on, we assume that your iOS Bundle ID is
com.sonub.fireflutter
.
- From now on, we assume that your iOS Bundle ID is
-
click
Register app
. -
click
Download GoogleService-Info.plist
- And save it under
fireflutter_sample_app/ios/Runner
folder.
- And save it under
-
click
Next
. -
click
Next
again. -
click
Next
again. -
click
Continue to console
. -
open
fireflutter_sample_app/ios/Runner.xcworkspace
with Xcode. -
click
Runner
on the top of left pane. -
click
Runner
on TARGETS. -
edit
Bundle Identifier
tocom.sonub.fireflutter
. -
set
iOS 11.0
under Deployment Info. -
Darg
fireflutter_sample_app/ios/Runner/GoogleService-Info.plist
file underRunner/Runner
on left pane of Xcode. -
Close Xcode.
-
You may want to test if the settings are alright.
- Open VSCode and do FireFlutter Initialization do some registration code. see User Registration for more details.
Android Setup
Flutter Installation #
- Add
fireflutter
to pubspec.yaml - see our sample flutter app.
Firebase Social Login #
-
Under Authentication => Sign-in Methods, Enable
- Email/Password
- Apple
- Phone All of them are optional. You may only enable those you want to provide for user login.
-
Settings for Firebase Social login are in Android and iOS platform already done app. You need to set the settings on Apple, Facebook.
- If you are not going to use the sample app, you need to setup by yourself.
-
Refer Firebase Authentication and FlutterFire Social Authenticatino for details.
Firestore and Functions #
- Enable(Start) Cloud Firestore by clicking the menu.
- Choose
protected mode
- Choose your region.
- Refer Cloud Firestore for details.
Firestore security and Functions Settings. #
-
Firestore needs security rules and Functions needs functions to support FireFlutter package.
- If you wish, you can continue without this settings. But it's not secure and some functionality may not work.
-
Install firebase tools.
# npm install -g firebase-tools
$ cd firebase
$ firebase login
- Git clone(or fork) https://github.com/thruthesky/fireflutter-firebase and install with
npm i
- Update Firebase project ID in
.firebaserc ==> projects ==> default
. - Save
Firebase SDK Admin Service Key
tofirebase-service-account-key.json
. - Run
firebase deploy --only firestore,functions
. You will need FirebasePay as you go
plan to deploy it.
Push Notification #
-
Settings of push notification on Android and iOS platform are done in the sample app.
- If you are not going to use the sample app, you need to setup by yourself.
-
Refer Firestore Messaging
Security Rules Testing #
- If you wish to test Firestore security rules, you may do so with the following;
Run Firebase emualtor first.
$ firebase emulators:start --only firestore
run the tests.
$ npm run test
$ npm run test:basic
$ npm run test:user
$ npm run test:admin
$ npm run test:category
$ npm run test:post
$ npm run test:comment
$ npm run test:vote
$ npm run test:user.token
Funtions Test #
- If you whish to test Functins, you may do so with the following;
$ cd functions
$ npm test
Localization
-
To add a language, the language needs to be set in Info.plist of iOS platform. No setting is needed on Android platform.
-
you need to add the translation under Firestore
translations
collection. -
you need to use it in your app.
-
Localization could be used for menus, texts in screens.
Algolia Installation #
- There are two settings for Algolia.
- First, you need to put ALGOLIA_ID(Application ID), ALGOLIA_ADMIN_KEY, ALGOLIA_INDEX_NAME in
firebase-settings.js
.- deploy with
firebase deploy --only functions
. - For testing, do
npm run test:algolia
.
- deploy with
- Second, you need to add(or update) ALGOLIA_APP_ID(Application ID), ALGOLIA_SEARCH_KEY(Search Only Api Key), ALGOLIA_INDEX_NAME in Firestore
settings/app
document. Optionally, you can put the settings insideFireFlutter.init()
. - Algolia free account give you 10,000 free search every months. This is good enough for small sized projects.
Admin Account Setting #
- Any user who has
isAdmin
property withtrue
. - Admin property is protected by Firestore security rules and cannot be edited by client app.
App Management #
- The app management here is based on the sample code and app.
- FireFlutter is a flutter package to build social apps and is fully customizable. When you may build your own customized app, we recommend to use our sample codes.
App Settings #
- Developers can set default settings on
FireFlutter.init()
. - Admin can overwrite all the settings by updating Firestore
settings
docuemnts.
Internalization (Localization) #
-
Menus and page contents can be translated depending on user's device. Or developer can put a menu to let users to choose their languages.
-
When admin update the translation text in Firestore
translations
collectin, the will get the update in real time. The app, should update the screen. -
The localization is managed by
GetX
package that is used for routing and state management on the sample code.
Forum Management #
Forum Category Management
- You can create forum categories in admin screen.
For Developers #
General Setup #
- Add latest version of FireFlutter in pubspec.yaml
- Add latest version of GetX.
- We have chosen
GetX
package for routing, state management, localization and other functionalities.- GetX is really simple. We recommed you to use it.
- All the code explained here is with GetX.
- You may choose different packages and that's very fine.
- We have chosen
FireFlutter Initialization
- Open
main.dart
- Add the following code;
import 'package:fireflutter/fireflutter.dart';
FireFlutter ff = FireFlutter();
void main() async {
await ff.init();
runApp(MainApp());
}
-
The variable
ff
is an instace ofFireFlutter
and should be shared across all the screens. -
Create a
global_variables.dart
on the same folder of main.dart.- And move the
ff
variable intoglobal_variables.dart
.
- And move the
-
The complete code is on fireflutter-initialization branch of sample app.
-
todo: app settings
-
todo: translations
Add GetX to main.dart
- To add GetX to Flutter app,
- open main.dart
- split
Home Screen
intolib/screens/home/home.screen.dart
. - and replace
MaterialApp
withGetMaterialApp
. - add
initialRotue: 'home'
- add HomeScreen to route.
- To see the complete code, visit getx branch of sample app.
Firestore Structure #
-
Principle. Properties and sub collections(documents) of a document should be under that document.
-
users/{uid}
is user's private data document.users/{uid}/meta/public
is user's public data document.users/{uid}/meta/tokens
is where the user's tokens are saved.
-
/posts/{postId}
is the post document./posts/{postId}/votes/{uid}
is the vote document of each user./posts/{postId}/comments/{commentId}
is the comment document under of the post document.
Coding Guidelines #
null
event will be fired for the first time onFireFlutter.userChange.listen
.auth
event will be fired for the first time onFirebaseAuth.authChagnes
.
User #
- Private user information is saved under
/users/{uid}
documentation. - User's notification subscription information is saved under
/users/{uid}/meta/public
documents. - Push notification tokens are saved under
/users/{uid}/meta/tokens
document.
User Email And Password Registration
-
Do General Setup.
-
Create register screen with
lib/screens/register/register.screen.dart
file. -
Put a route named
register
-
And put a button for opening register screen.
-
Then, add email input box, password input box and a submit button.
- For the complete code, see register branch in sample app.
-
When the submit button is pressed, you would write codes like below for the user to actually register into Firebase.
try {
User user = await ff.register({
'email': emailController.text,
'password': passwordController.text,
'displayName': displayNameController.text,
'favoriteColor': favoriteColorController.text
});
// register success. App may redirect to home screen.
} catch (e) {
// do error handling
}
- After registration, you will see there is a new record under Users in Firebase console => Authentication page.
Forum #
- To fetch posts and listing, you need to declare
ForumData
object.- How to declare forum data.
class ForumScreen extends StatefulWidget {
@override
_ForumScreenState createState() => _ForumScreenState();
}
class _ForumScreenState extends State<ForumScreen> {
ForumData forum;
@override
void initState() {
super.initState();
forum = ForumData(
category: Get.arguments['category'], // Category of forum
/// [render] callback will be invoked on post/comment/file CRUD and fetching posts.
render: (RenderType x) {
if (mounted) setState(() => null);
},
);
}
}
Logic for Vote #
- Post voting and comment voting have same logic and same(similiar) document structure.
- Choice of vote could be one of
empty string('')
,like
,dislike
. Otherwise, permission error will happen. - When a user votes for the first time, choice must be one of
like
ordislike
. Otherwise, permission error will happen. - Properties names of like and dislike in post and comment documents are in plural forms that are
likes
anddislikes
. likes
anddislikes
may not exists in the document or could be set to 0.- For votes under post,
/posts/{postId}/votes/{uid}
is the document path. - For votes under comments,
/posts/{postId}/comments/{commentId}/votes/{uid}
is the document path. - User can vote on his posts and comments.
- A user voted
like
and the user votelike
again, he means, he wants to cancel the vote. The client should save empty string(''). - A user voted
like
and the user votedislike
, thenlikes
will be decreased by 1 anddislikes
will be increased by 1. - Admin should not fix vote document manually, since it may produce wierd results.
- Voting works asynchronously.
- When a user votes in the order of
like => dislike => like => dislike
, the server(Firestore) may receive in the order oflike => like => dislike => dislike
since it is asynchronous. So, client app should block the user not to vote again while voting is in progress.
- When a user votes in the order of
Push Notification #
- Must be enableNotification
true
on main on FireFlutter init- to handble notification you can pass method via notificationHandler.
ff.init(
enableNotification: true,
notificationHandler: (Map<String, dynamic> notification,
Map<String, dynamic> data, NotificationType type) {
// do something here.
// display, alert, move to specific page
},
);
Social Login #
Google Login
- You can use the social Login by calling signInWithGoogle.
RaisedButton(
child: Text('Google Sign-in'),
onPressed: ff.signInWithGoogle,
)
Facebook Login
- Follow the instructions on how to setup Facebook project.
RaisedButton(
child: Text('Facebook Sign-in'),
onPressed: ff.signInWithFacebook,
);
Apple Login
- Follow the instructions on how to setup Apple project.
- Enable
Apple
in Sign-in Method.
SignInWithAppleButton(
onPressed: () async {
try {
await ff.signInWithApple();
Get.toNamed(RouteNames.home);
} catch (e) {
Service.error(e);
}
},
),
External Logins #
Kakao Login
- Kakao login is completely separated from
fireflutter
since it is not part ofFirebase
.- The sample app has an example code on how to do
Kakao login
and link toFirebase Auth
account.
- The sample app has an example code on how to do
I18N #
-
The app's i18n is managed by
GetX
i18n feature. -
If you want to add another language,
- Add the language code in
Info.plist
- Add the language on
translations
- Add the lanugage on
FireFlutter.init()
- Add the language on
FireFlutter.settingsChange
- Add the language on Firebase
settings
collection.
- Add the language code in
-
Default i18n translations(texts) can be set through
FireFlutter
initializatin and is overwritten by thetranslations
collection of Firebase. The Firestore is working offline mode, so overwriting with Firestore translation would happen so quickly.
Settings #
-
Default settings can be set through
FireFlutter
initialization and is overwritten bysettings
collection of Firebase. The Firestore is working offline mode, so overwriting with Firestore translation would happen so quickly. -
If
show-phone-verification-after-login
is set to true, then users who do not have their phone numbers will be redirected to phone verification page.- Developers can customize it by putting 'skip' button.
-
If
create-phone-verified-user-only
is set to true, only the user who verified thier phone numbers can create posts and comments.