Skip to content

Commit e8425c5

Browse files
dri-richarddri-richard
authored
App options (#5)
* Read optional app initialisation options * Disable FirebaseInitProvider on Android if firebase.no_auto_init is specified * Update documentation with description of optional parameter to init()
1 parent af890eb commit e8425c5

File tree

4 files changed

+364
-285
lines changed

4 files changed

+364
-285
lines changed

‎docs/index.md‎

Lines changed: 114 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,114 @@
1-
---
2-
title: Defold Firebase documentation
3-
brief: This manual covers how to setup and use Firebase products in Defold.
4-
---
5-
6-
# Defold Firebase documentation
7-
8-
This extension allows you to interact with Firebase in a uniform way for games on iOS and Android. The extension contains the core functionality to create and initialise a Firebase application. The various Firebase products are available in individual extensions:
9-
10-
* [Firebase Analytics](https://github.com/defold/extension-firebase-analytics)
11-
* [Firebase Remote Config](https://github.com/defold/extension-firebase-remoteconfig)
12-
13-
14-
## Setup
15-
### 1. Firebase setup
16-
The steps below taken from the [official Google Firebase Guides](https://firebase.google.com/docs/cpp/setup).
17-
18-
#### 1.1 Create a Firebase project
19-
* Create a Firebase project in the [Firebase console](https://console.firebase.google.com/), if you don't already have one. Click Add project. If you already have an existing Google project associated with your mobile app, select it from the Project name drop down menu. Otherwise, enter a project name to create a new project.
20-
* Optional: Edit your Project ID. Your project is given a unique ID automatically, and it's used in publicly visible Firebase features such as database URLs and your Firebase Hosting subdomain. You can change it now if you want to use a specific subdomain.
21-
* Follow the remaining setup steps and click Create project (or Add Firebase if you're using an existing project) to begin provisioning resources for your project. This typically takes a few minutes. When the process completes, you'll be taken to the project overview.
22-
23-
#### 1.2 Setup for Android
24-
* Click Add Firebase to your Android app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
25-
* When prompted, enter your app's package name. It's important to enter the package name your app is using; this can only be set when you add an app to your Firebase project.
26-
* During the process, you'll download a `google-services.json` file. You can download this file again at any time.
27-
28-
#### 1.3 Setup for iOS
29-
* Click Add Firebase to your iOS app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
30-
* When prompted, enter your app's bundle ID. It's important to enter the bundle ID your app is using; this can only be set when you add an app to your Firebase project.
31-
* During the process, you'll download a `GoogleService-Info.plist` file. You can download this file again at any time.
32-
33-
### 2. Defold setup
34-
#### 2.1 Add project dependencies
35-
You can use the extension in your own project by adding this project as a [Defold library dependency](http://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add:
36-
37-
[https://github.com/defold/extension-firebase/archive/master.zip](https://github.com/defold/extension-firebase/archive/master.zip)
38-
39-
Or point to the ZIP file of a [specific release](https://github.com/defold/extension-firebase/releases) (recommended!).
40-
41-
#### 2.2 Setup for Android
42-
43-
* Run `generate_xml_from_google_services_json.py` or `generate_xml_from_google_services_json.exe` (both from Firebase C++ SDK) to convert the previously downloaded `google-services.json` to an Android resource XML:
44-
45-
```
46-
$ ./generate_xml_from_google_services_json.py -i google-services.json -o google-services.xml
47-
```
48-
49-
* Copy the generated `google-services.xml` file to a folder structure like this:
50-
51-
```
52-
<project_root>
53-
|
54-
+-bundle
55-
|
56-
+-android
57-
|
58-
+-res
59-
|
60-
+-values
61-
|
62-
+-google-services.xml
63-
```
64-
65-
* Open `game.project` and set the `Bundle Resources` entry under the `Project` section to `/bundle` to match the folder created in the step above. Read more about the `Bundle Resources` setting in the [Defold manual](https://www.defold.com/manuals/project-settings/#_project).
66-
67-
68-
#### 2.3 Setup for iOS
69-
* Copy the generated `GoogleService-Info.plist` file to a folder structure like this:
70-
71-
```
72-
<project_root>
73-
|
74-
+-bundle
75-
|
76-
+-ios
77-
|
78-
+-GoogleService-Info.plist
79-
```
80-
81-
* Open `game.project` and set the `Bundle Resources` entry under the `Project` section to `/bundle` to match the folder created in the step above. Read more about the `Bundle Resources` setting in the [Defold manual](https://www.defold.com/manuals/project-settings/#_project).
82-
83-
84-
## Usage
85-
86-
```lua
87-
function init(self)
88-
-- use firebase only if it is supported on the current platform
89-
if firebase then
90-
local ok, err = firebase.init()
91-
if not ok then
92-
print(err)
93-
return
94-
end
95-
96-
-- firebase is ready to use!
97-
98-
-- installation auth token can be used for configuring test devices for A/B tests
99-
firebase.get_installation_auth_token(function(self, token)
100-
print("installation auth token is " .. token)
101-
end)
102-
end
103-
end
104-
```
105-
106-
## Source code
107-
108-
The source code is available on [GitHub](https://github.com/defold/extension-firebase)
109-
110-
111-
112-
## API reference
1+
---
2+
title: Defold Firebase documentation
3+
brief: This manual covers how to setup and use Firebase products in Defold.
4+
---
5+
6+
# Defold Firebase documentation
7+
8+
This extension allows you to interact with Firebase in a uniform way for games on iOS and Android. The extension contains the core functionality to create and initialise a Firebase application. The various Firebase products are available in individual extensions:
9+
10+
* [Firebase Analytics](https://github.com/defold/extension-firebase-analytics)
11+
* [Firebase Remote Config](https://github.com/defold/extension-firebase-remoteconfig)
12+
13+
14+
## Setup
15+
### 1. Firebase setup
16+
The steps below taken from the [official Google Firebase Guides](https://firebase.google.com/docs/cpp/setup).
17+
18+
#### 1.1 Create a Firebase project
19+
* Create a Firebase project in the [Firebase console](https://console.firebase.google.com/), if you don't already have one. Click Add project. If you already have an existing Google project associated with your mobile app, select it from the Project name drop down menu. Otherwise, enter a project name to create a new project.
20+
* Optional: Edit your Project ID. Your project is given a unique ID automatically, and it's used in publicly visible Firebase features such as database URLs and your Firebase Hosting subdomain. You can change it now if you want to use a specific subdomain.
21+
* Follow the remaining setup steps and click Create project (or Add Firebase if you're using an existing project) to begin provisioning resources for your project. This typically takes a few minutes. When the process completes, you'll be taken to the project overview.
22+
23+
#### 1.2 Setup for Android
24+
* Click Add Firebase to your Android app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
25+
* When prompted, enter your app's package name. It's important to enter the package name your app is using; this can only be set when you add an app to your Firebase project.
26+
* During the process, you'll download a `google-services.json` file. You can download this file again at any time.
27+
28+
#### 1.3 Setup for iOS
29+
* Click Add Firebase to your iOS app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
30+
* When prompted, enter your app's bundle ID. It's important to enter the bundle ID your app is using; this can only be set when you add an app to your Firebase project.
31+
* During the process, you'll download a `GoogleService-Info.plist` file. You can download this file again at any time.
32+
33+
### 2. Defold setup
34+
#### 2.1 Add project dependencies
35+
You can use the extension in your own project by adding this project as a [Defold library dependency](http://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add:
36+
37+
[https://github.com/defold/extension-firebase/archive/master.zip](https://github.com/defold/extension-firebase/archive/master.zip)
38+
39+
Or point to the ZIP file of a [specific release](https://github.com/defold/extension-firebase/releases) (recommended!).
40+
41+
#### 2.2 Setup for Android
42+
43+
* Run `generate_xml_from_google_services_json.py` or `generate_xml_from_google_services_json.exe` (both from Firebase C++ SDK) to convert the previously downloaded `google-services.json` to an Android resource XML:
44+
45+
```
46+
$ ./generate_xml_from_google_services_json.py -i google-services.json -o google-services.xml
47+
```
48+
49+
* Copy the generated `google-services.xml` file to a folder structure like this:
50+
51+
```
52+
<project_root>
53+
|
54+
+-bundle
55+
|
56+
+-android
57+
|
58+
+-res
59+
|
60+
+-values
61+
|
62+
+-google-services.xml
63+
```
64+
65+
* Open `game.project` and set the `Bundle Resources` entry under the `Project` section to `/bundle` to match the folder created in the step above. Read more about the `Bundle Resources` setting in the [Defold manual](https://www.defold.com/manuals/project-settings/#_project).
66+
67+
68+
#### 2.3 Setup for iOS
69+
* Copy the generated `GoogleService-Info.plist` file to a folder structure like this:
70+
71+
```
72+
<project_root>
73+
|
74+
+-bundle
75+
|
76+
+-ios
77+
|
78+
+-GoogleService-Info.plist
79+
```
80+
81+
* Open `game.project` and set the `Bundle Resources` entry under the `Project` section to `/bundle` to match the folder created in the step above. Read more about the `Bundle Resources` setting in the [Defold manual](https://www.defold.com/manuals/project-settings/#_project).
82+
83+
84+
## Usage
85+
86+
```lua
87+
function init(self)
88+
-- use firebase only if it is supported on the current platform
89+
if firebase then
90+
local ok, err = firebase.init()
91+
if not ok then
92+
print(err)
93+
return
94+
end
95+
96+
-- firebase is ready to use!
97+
98+
-- installation auth token can be used for configuring test devices for A/B tests
99+
firebase.get_installation_auth_token(function(self, token)
100+
print("installation auth token is " .. token)
101+
end)
102+
end
103+
end
104+
```
105+
106+
It is possible to override the values within GoogleService-Info.plist/google-services.xml by passing an optional table of options to init(). See the [Defold manual](https://defold.com/extension-firebase/api/) for details but be aware of implications for analytics as described in Google's [Firebase documentation](https://firebase.google.com/docs/projects/multiprojects#reliable-analytics)
107+
108+
## Source code
109+
110+
The source code is available on [GitHub](https://github.com/defold/extension-firebase)
111+
112+
113+
114+
## API reference

‎firebase/api/firebase.script_api‎

Lines changed: 33 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,33 @@
1-
- name: firebase
2-
type: table
3-
desc: Functions and constants for interacting with Firebase
4-
5-
members:
6-
- name: init
7-
type: function
8-
desc: Initialise Firebase
9-
10-
return:
11-
- name: success
12-
type: boolean
13-
desc: Indicates if initialisation was successful
14-
- name: error
15-
type: string
16-
desc: Error message if initialisation failed
17-
18-
- name: get_installation_auth_token
19-
type: function
20-
desc: Get the Firebase Installation auth token
21-
22-
parameters:
23-
- name: callback
24-
type: function
25-
desc: Function to invoke with the auth token (self, token)
1+
- name: firebase
2+
type: table
3+
desc: Functions and constants for interacting with Firebase
4+
5+
members:
6+
- name: init
7+
type: function
8+
desc: Initialise Firebase
9+
10+
parameters:
11+
- name: options
12+
optional: true
13+
type: table
14+
desc: Optional table with initialisation parameters to use instead of those specified in google-services.xml/plist
15+
When passing this, disable creation of the default Firebase App by specifying firebase.no_auto_init in game.project
16+
Valid keys in the table are api_key, app_id, database_url, messaging_sender_id, project_id, storage_bucket. All values are strings.
17+
18+
return:
19+
- name: success
20+
type: boolean
21+
desc: Indicates if initialisation was successful
22+
- name: error
23+
type: string
24+
desc: Error message if initialisation failed
25+
26+
- name: get_installation_auth_token
27+
type: function
28+
desc: Get the Firebase Installation auth token
29+
30+
parameters:
31+
- name: callback
32+
type: function
33+
desc: Function to invoke with the auth token (self, token)

‎firebase/manifests/android/AndroidManifest.xml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
3+
xmlns:tools="http://schemas.android.com/tools"
4+
package="{{android.package}}">
5+
<uses-sdk android:minSdkVersion="{{android.minimum_sdk_version}}" android:targetSdkVersion="{{android.target_sdk_version}}" />
6+
<application>
7+
{{#firebase.no_auto_init}}
8+
<provider
9+
android:name="com.google.firebase.provider.FirebaseInitProvider"
10+
android:authorities="{{android.package}}.firebaseinitprovider"
11+
tools:node="remove"
12+
/>
13+
{{/firebase.no_auto_init}}
14+
</application>
15+
</manifest>

0 commit comments

Comments
 (0)