Skip to content

Commit 6b48a68

Browse files
SalakarSalakar
committed
Merge remote-tracking branch 'origin/master'
2 parents 5968ee1 + 9213d40 commit 6b48a68

13 files changed

+534
-888
lines changed

‎README.md

+29-888
Large diffs are not rendered by default.

‎docs/api/analytics.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Analytics
2+
3+
Integrating Firebase analytics is super simple using Firestack. A number of methods are provided to help tailor analytics specifically for your
4+
own app. The Firebase SDK includes a number of pre-set events which are automatically handled, and cannot be used with custom events:
5+
6+
```
7+
'app_clear_data',
8+
'app_uninstall',
9+
'app_update',
10+
'error',
11+
'first_open',
12+
'in_app_purchase',
13+
'notification_dismiss',
14+
'notification_foreground',
15+
'notification_open',
16+
'notification_receive',
17+
'os_update',
18+
'session_start',
19+
'user_engagement',
20+
```
21+
22+
#### logEvent(event: string, params?: Object)
23+
24+
Log a custom event with optional params. Can be synchronous or return a Promise
25+
26+
```javascript
27+
firestack.analytics()
28+
.logEvent('clicked_advert', { id: 1337 })
29+
.then(() => {
30+
console.log('Event has been logged successfully');
31+
});
32+
```
33+
34+
#### setAnalyticsCollectionEnabled(enabled: boolean)
35+
36+
Sets whether analytics collection is enabled for this app on this device.
37+
38+
```javascript
39+
firestack.analytics()
40+
.setAnalyticsCollectionEnabled(false);
41+
```
42+
43+
#### setCurrentScreen(screenName: string, screenClassOverride: string)
44+
45+
Sets the current screen name, which specifies the current visual context in your app.
46+
47+
```javascript
48+
firestack.analytics()
49+
.setCurrentScreen('user_profile');
50+
```
51+
52+
#### setMinimumSessionDuration(miliseconds: number)
53+
54+
Sets the minimum engagement time required before starting a session. The default value is 10000 (10 seconds).
55+
56+
```javascript
57+
firestack.analytics()
58+
.setMinimumSessionDuration(15000);
59+
```
60+
61+
#### setSessionTimeoutDuration(miliseconds: number)
62+
63+
Sets the duration of inactivity that terminates the current session. The default value is 1800000 (30 minutes).
64+
65+
```javascript
66+
firestack.analytics()
67+
.setSessionTimeoutDuration(900000);
68+
```
69+
70+
#### setUserId(id: string)
71+
72+
Gives a user a uniqiue identificaition.
73+
74+
```javascript
75+
const id = firestack.auth().currentUser.uid;
76+
77+
firestack.analytics()
78+
.setUserId(id);
79+
```
80+
81+
#### setUserProperty(name: string, value: string)
82+
83+
Sets a key/value pair of data on the current user.
84+
85+
```javascript
86+
firestack.analytics()
87+
.setUserProperty('nickname', 'foobar');
88+
```

‎docs/api/authentication.md

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Authentication
2+
3+
Firestack handles authentication for us out of the box, both with email/password-based authentication and through oauth providers (with a separate library to handle oauth providers).
4+
5+
> Android requires the Google Play services to installed for authentication to function.
6+
7+
## Local Auth
8+
9+
#### [onAuthStateChanged(event: Function)](https://firebase.google.com/docs/reference/js/firebase.auth.Auth#onAuthStateChanged)
10+
11+
Listen for changes in the users auth state (logging in and out).
12+
13+
```javascript
14+
firestack.auth().onAuthStateChanged((evt) => {
15+
// evt is the authentication event, it contains an `error` key for carrying the
16+
// error message in case of an error and a `user` key upon successful authentication
17+
if (!evt.authenticated) {
18+
// There was an error or there is no user
19+
console.error(evt.error)
20+
} else {
21+
// evt.user contains the user details
22+
console.log('User details', evt.user);
23+
}
24+
})
25+
.then(() => console.log('Listening for authentication changes'))
26+
```
27+
28+
#### offAuthStateChanged()
29+
30+
Remove the `onAuthStateChanged` listener.
31+
This is important to release resources from our app when we don't need to hold on to the listener any longer.
32+
33+
```javascript
34+
firestack.auth().offAuthStateChanged()
35+
```
36+
37+
#### [createUserWithEmailAndPassword(email: string, password: string)](https://firebase.google.com/docs/reference/js/firebase.auth.Auth#createUserWithEmailAndPassword)
38+
39+
We can create a user by calling the `createUserWithEmailAndPassword()` function.
40+
The method accepts two parameters, an email and a password.
41+
42+
```javascript
43+
firestack.auth().createUserWithEmailAndPassword('[email protected]', '123456')
44+
.then((user) => {
45+
console.log('user created', user)
46+
})
47+
.catch((err) => {
48+
console.error('An error occurred', err);
49+
})
50+
```
51+
52+
#### [signInWithEmailAndPassword(email: string, password: string)](https://firebase.google.com/docs/reference/js/firebase.auth.Auth#signInWithEmailAndPassword)
53+
54+
To sign a user in with their email and password, use the `signInWithEmailAndPassword()` function.
55+
It accepts two parameters, the user's email and password:
56+
57+
```javascript
58+
firestack.auth().signInWithEmailAndPassword('[email protected]', '123456')
59+
.then((user) => {
60+
console.log('User successfully logged in', user)
61+
})
62+
.catch((err) => {
63+
console.error('User signin error', err);
64+
})
65+
```
66+
67+
#### [signInAnonymously()](https://firebase.google.com/docs/reference/js/firebase.auth.Auth#signInAnonymously)
68+
69+
Sign an anonymous user. If the user has already signed in, that user will be returned.
70+
71+
```javascript
72+
firestack.auth().signInAnonymously()
73+
.then((user) => {
74+
console.log('Anonymous user successfully logged in', user)
75+
})
76+
.catch((err) => {
77+
console.error('Anonymous user signin error', err);
78+
})
79+
```
80+
81+
#### signInWithProvider()
82+
83+
We can use an external authentication provider, such as twitter/facebook for authentication. In order to use an external provider, we need to include another library to handle authentication.
84+
85+
> By using a separate library, we can keep our dependencies a little lower and the size of the application down.
86+
87+
#### signInWithCustomToken()
88+
89+
To sign a user using a self-signed custom token, use the `signInWithCustomToken()` function. It accepts one parameter, the custom token:
90+
91+
```javascript
92+
firestack.auth().signInWithCustomToken(TOKEN)
93+
.then((user) => {
94+
console.log('User successfully logged in', user)
95+
})
96+
.catch((err) => {
97+
console.error('User signin error', err);
98+
})
99+
```
100+
101+
#### [updateUserEmail()](https://firebase.google.com/docs/reference/js/firebase.User#updateEmail)
102+
103+
We can update the current user's email by using the command: `updateUserEmail()`.
104+
It accepts a single argument: the user's new email:
105+
106+
```javascript
107+
firestack.auth().updateUserEmail('[email protected]')
108+
.then((res) => console.log('Updated user email'))
109+
.catch(err => console.error('There was an error updating user email'))
110+
```
111+
112+
#### [updateUserPassword()](https://firebase.google.com/docs/reference/js/firebase.User#updatePassword)
113+
114+
We can update the current user's password using the `updateUserPassword()` method.
115+
It accepts a single parameter: the new password for the current user
116+
117+
```javascript
118+
firestack.auth().updateUserPassword('somethingReallyS3cr3t733t')
119+
.then(res => console.log('Updated user password'))
120+
.catch(err => console.error('There was an error updating your password'))
121+
```
122+
123+
#### [updateUserProfile()](https://firebase.google.com/docs/auth/web/manage-users#update_a_users_profile)
124+
125+
To update the current user's profile, we can call the `updateUserProfile()` method.
126+
It accepts a single parameter:
127+
128+
* object which contains updated key/values for the user's profile.
129+
Possible keys are listed [here](https://firebase.google.com/docs/auth/ios/manage-users#update_a_users_profile).
130+
131+
```javascript
132+
firestack.auth()
133+
.updateUserProfile({
134+
displayName: 'Ari Lerner'
135+
})
136+
.then(res => console.log('Your profile has been updated'))
137+
.catch(err => console.error('There was an error :('))
138+
```
139+
140+
#### [sendPasswordResetWithEmail()](https://firebase.google.com/docs/auth/web/manage-users#send_a_password_reset_email)
141+
142+
To send a password reset for a user based upon their email, we can call the `sendPasswordResetWithEmail()` method.
143+
It accepts a single parameter: the email of the user to send a reset email.
144+
145+
```javascript
146+
firestack.auth().sendPasswordResetWithEmail('[email protected]')
147+
.then(res => console.log('Check your inbox for further instructions'))
148+
.catch(err => console.error('There was an error :('))
149+
```
150+
#### [deleteUser()](https://firebase.google.com/docs/auth/web/manage-users#delete_a_user)
151+
152+
It's possible to delete a user completely from your account on Firebase.
153+
Calling the `deleteUser()` method will take care of this for you.
154+
155+
```javascript
156+
firestack.auth()
157+
.deleteUser()
158+
.then(res => console.log('Sad to see you go'))
159+
.catch(err => console.error('There was an error - Now you are trapped!'))
160+
```
161+
162+
#### getToken()
163+
164+
If you want user's token, use `getToken()` method.
165+
166+
```javascript
167+
firestack.auth()
168+
.getToken()
169+
.then(res => console.log(res.token))
170+
.catch(err => console.error('error'))
171+
```
172+
173+
#### [signOut()](https://firebase.google.com/docs/reference/js/firebase.auth.Auth#signOut)
174+
175+
To sign the current user out, use the `signOut()` method.
176+
It accepts no parameters
177+
178+
```javascript
179+
firestack.auth()
180+
.signOut()
181+
.then(res => console.log('You have been signed out'))
182+
.catch(err => console.error('Uh oh... something weird happened'))
183+
```
184+
185+
186+
#### getCurrentUser()
187+
188+
Although you _can_ get the current user using the `getCurrentUser()` method, it's better to use this from within the callback function provided by `listenForAuth()`.
189+
However, if you need to get the current user, call the `getCurrentUser()` method:
190+
191+
```javascript
192+
firestack.auth()
193+
.getCurrentUser()
194+
.then(user => console.log('The currently logged in user', user))
195+
.catch(err => console.error('An error occurred'))
196+
```
197+
198+
## Social Auth
199+
200+
TODO

‎docs/api/cloud-messaging.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/api/database.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/api/events.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/api/presence.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/api/server-value.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/api/storage

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/firebase-setup.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Firebase Setup
2+
3+
The Firestack library is intended on making it easy to work with [Firebase](https://firebase.google.com/) and provides a small native shim to the Firebase native code.
4+
5+
To add Firebase to your project, make sure to create a project in the [Firebase console](https://firebase.google.com/console)
6+
7+
![Create a new project](http://d.pr/i/17cJ2.png)
8+
9+
Each platform uses a different setup method after creating the project.
10+
11+
## iOS
12+
13+
After creating a Firebase project, click on the [Add Firebase to your iOS app](http://d.pr/i/3sEL.png) and follow the steps from there to add the configuration file. You do _not_ need to set up a cocoapods project (this is already done through firestack). Make sure not to forget the `Copy Files` phase in iOS.
14+
15+
[Download the Firebase config file](https://support.google.com/firebase/answer/7015592) and place it in your app directory next to your app source code:
16+
17+
![GoogleService-Info.plist](http://d.pr/i/1eGev.png)
18+
19+
Once you download the configuration file, make sure you place it in the root of your Xcode project. Every different Bundle ID (aka, even different project variants needs their own configuration file).
20+
21+
Lastly, due to some dependencies requirements, Firestack supports iOS versions 8.0 and up. Make sure to update the minimum version of your iOS app to `8.0`.
22+
23+
## Android
24+
25+
There are several ways to setup Firebase on Android. The _easiest_ way is to pass the configuration settings in JavaScript. In that way, there is no setup for the native platform.
26+
27+
### google-services.json setup
28+
If you prefer to include the default settings in the source of your app, download the `google-services.json` file provided by Firebase in the _Add Firebase to Android_ platform menu in your Firebase configuration console.
29+
30+
Next you'll have to add the google-services gradle plugin in order to parse it.
31+
32+
Add the google-services gradle plugin as a dependency in the *project* level build.gradle
33+
`android/build.gradle`
34+
```java
35+
buildscript {
36+
// ...
37+
dependencies {
38+
// ...
39+
classpath 'com.google.gms:google-services:3.0.0'
40+
}
41+
}
42+
```
43+
44+
In your app build.gradle file, add the gradle plugin at the VERY BOTTOM of the file (below all dependencies)
45+
`android/app/build.gradle`
46+
```java
47+
apply plugin: 'com.google.gms.google-services'
48+
```
49+
50+
## Usage
51+
52+
After creating a Firebase project and installing the library, we can use it in our project by importing the library in our JavaScript:
53+
54+
```javascript
55+
import Firestack from 'react-native-firestack'
56+
```
57+
58+
We need to tell the Firebase library we want to _configure_ the project. Firestack provides a way to configure both the native and the JavaScript side of the project at the same time with a single command:
59+
60+
```javascript
61+
const firestack = new Firestack();
62+
```
63+
64+
We can pass _custom_ options by passing an object with configuration options. The configuration object will be generated first by the native configuration object, if set and then will be overridden if passed in JS. That is, all of the following key/value pairs are optional if the native configuration is set.
65+
66+
| option | type | Default Value | Description |
67+
|----------------|----------|-------------------------|----------------------------------------|
68+
| debug | bool | false | When set to true, Firestack will log messages to the console and fire `debug` events we can listen to in `js` |
69+
| bundleID | string | Default from app `[NSBundle mainBundle]` | The bundle ID for the app to be bundled with |
70+
| googleAppID | string | "" | The Google App ID that is used to uniquely identify an instance of an app. |
71+
| databaseURL | string | "" | The database root (i.e. https://my-app.firebaseio.com) |
72+
| deepLinkURLScheme | string | "" | URL scheme to set up durable deep link service |
73+
| storageBucket | string | "" | The Google Cloud storage bucket name |
74+
| androidClientID | string | "" | The Android client ID used in Google AppInvite when an iOS app has it's android version |
75+
| GCMSenderID | string | "" | The Project number from the Google Developer's console used to configure Google Cloud Messaging |
76+
| trackingID | string | "" | The tracking ID for Google Analytics |
77+
| clientID | string | "" | The OAuth2 client ID for iOS application used to authenticate Google Users for signing in with Google |
78+
| APIKey | string | "" | The secret iOS API key used for authenticating requests from our app |
79+
80+
For instance:
81+
82+
```javascript
83+
const configurationOptions = {
84+
debug: true
85+
};
86+
const firestack = new Firestack(configurationOptions);
87+
firestack.on('debug', msg => console.log('Received debug message', msg))
88+
```

0 commit comments

Comments
 (0)