- 一定要看英文文档,中文文档可能更新不及时
- 官方各个模块的JS的API文档
集成
前端集成
Web端
- 官网在新建web app的时候会给一个example,引入两个script即可。如果是npm进行管理可以直接
npm install --save firebased
- 对于私有数据,我们需要创建规则来限制前端的访问,通过后端生成的令牌来进行验证signInWithCustomToken
1 | import firebase from "firebase/app"; // 使用时这样引入,这句话必须有 |
后端集成
如果前端需要读取私有数据,那么后端需要为前端创建自定义令牌createCustomToken
下面的认证文件
项目名-firebase-adminsdk-xxxxx.json
来自于firebase console -> Project settings -> Service accounts -> Firebase Admin SDK -> Generate new private key
,是所有SDK都需要的后端只需要
npm install --save firebase-admin
即可
1 | import * as admin from 'firebase-admin' |
PHP集成
安装方式(需要ext-grpc扩展)
1
2
3
4
5如果仅仅使用firestore可以只安装某个组件
composer require google/cloud-firestore --with-all-dependencies # 加这个参数防止guzzlehttp/psr7版本错误
一次安装所有
composer require google/cloud --with-all-dependencies使用方式
1
2
3
4
5
6# export GOOGLE_APPLICATION_CREDENTIALS=认证文件路径
$firestore = new FirestoreClient();
$document = $firestore->document('users/123');
$document->set([
'name' => 'test'
]);
Cloud Messaging(Push Notification/APNs)
firebase-admin-node
- 强烈建议在开发时先使用这个包进行测试,因为这个包能够返回非常详细的错误信息,特别是证书没配置对这些信息,而且这个包在使用代理的情况下工作很好,不会像移动端那样,有时候连代理不行,有时候不连代理不行
1 | import * as admin from 'firebase-admin' |
证书配置
- 证书配置在
firebase console -> Project settings -> Cloud Messaging -> ios app configuration
- 证书有两种,
APNs Authentication Key
和APNs Certificates
,两者任选其一(如果两者都有默认会使用前者),貌似现在更建议用前者,而且前者没有过期时间,可以参考这里How to Create an iOS APNs Auth Key,也是相当简单的,创建一个Apns的key,然后下载p8证书,然后上传到firebase后台即可,后者的话过期时间是一年。需要这样做:- Apple Developer后台,选择你的bundle id,然后点击里面的
Push Notification
权限的Edit
就能创建development和production证书了,但是创建证书需要一个Request文件,需要在你自己的电脑上创建这个文件才行 - Mac -> Keychain -> 左上角菜单Keychain Access -> Certificate Assistant -> Request a Certificate From a Certificate Authority…
- 创建后下载,然后上传到firebase后台即可
- Apple Developer后台,选择你的bundle id,然后点击里面的
- 要获取apple的team ID,需要在
Developer
后台点击Membership
查看,参考Locate your Team ID
移动端配置
- 安卓端需要
google-services.json
文件,ios端需要GoogleService-Info.plist
文件,都通过firebase console -> Project settings -> General
中创建Add app
添加对应平台的APP,然后下载对应文件即可
Firebase Auth管理用户
- 可以直接使用firebase的用户系统
- 需要注意的是用户相关的几个action的邮箱模版是不能改变的,例如注册等,如果要自定义,只能自己写个后端,生成电子邮件操作链接
1 | firebase.auth().createUserWithEmailAndPassword(email, password) // 创建用户 |
Firestore Database
结构设计
尽量像GraphQL那样按照前端需要的来设计结构而不是直接把后端的db结构搬上去
可以使用嵌套的collection设计,例如,前端需要读取当前用户的notifications列表,可以这样设计:
1
2
3
4
5
6users集合
- username字段
- avatar字段
- notifications集合 # 嵌套集合,这样能够将notifications限制到当前user中去,而不用单独在最外层建一个collection,查询的时候还得多一个条件;另一方面,相比于直接在user里面添加一个array字段,它又能用到collection的一些语法,例如我们监听collection但是不能监听指定的字段,如果是一个子字段每次user中的任何字段变动都得返回所有东西;这样即使前端只监听user,并不会响应其notifications的事件。减少了读写次数且减少了数据里那个,而且好查询一点,前端只需要"users/{id}/notifications"即可。互相不会干扰
- read字段
- time字段
读写限制
- 开发前先看一下读写限制,至少在设计数据结构以及读写逻辑的时候能够少踩一些坑
- 文档的最大持续写入速率为1次/1秒(超过会报错
Deadline Exceeded
) - 文档每天的免费读写次数分别为5万次,文档删除次数为2万次
认证规则
安全规则
1 | rules_version = '2'; |
数据读写
数据写入
1 | const doc = db.doc('collection_name/doc_id') |
数据读取
where
支持的查询运算符有:<
、<=
、==
、>
、>=
、!=
、array-contains
、array-contains-any
、in
(数组中最多10个元素)、not-in
(数组中最多10个元素)如果要将等式运算符
==
与范围运算符(除==
以外的几个)结合使用,必须创建复合索引,否则会报错仅能对单个字段执行范围比较,并且一个复合查询中最多只能包含一个
array-contains
子句,例如citiesRef.where("state", ">=", "CA").where("population", ">", 100000) test.firestore.js
是无效的
1 | var citiesRef = db.collection("cities"); // 定义要查询的集合 |
侦听实时更新
- 在建立侦听的第一次会直接获取一份文档快照
- PHP客户端库不支持实时监听器
1 | // 监听单个文档 |
在CloudFirestore中构建在线状态系统
- 由于得依赖Cloud Functions,所以没去实践,不过我想Cloud Functions就是一个实时运行的方法,如果只是本地服务端去代替这一块感觉有可能
Nhost: 开源的firebase替代品
TroubleShooting
- TypeError: instance.INTERNAL.registerComponent is not a function 需要
npm install @firebase/app --save
- firebase发送消息出现
firebae Requested entity was not found.
: 一般是证书没配置好 - MismatchSenderId: 一般是证书选错了,可能选到了其他项目的证书,或者移动端选择了其他项目的证书