Skip to content

Commit 1ca5eeb

Browse files
OmbuwebOmbuweb
authored
docs(firebase-functions): update (#201)
1 parent 0931d1e commit 1ca5eeb

File tree

1 file changed

+122
-21
lines changed

1 file changed

+122
-21
lines changed

‎packages/firebase-functions/README.md

Lines changed: 122 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,54 @@
11
# @nativescript/firebase-functions
22

3-
```cli
4-
npm install @nativescript/firebase-functions
5-
```
3+
## Contents
4+
* [Intro](#intro)
5+
* [Set up your app for Firebase](#set-up-your-app-for-firebase)
6+
* [Add the Firebase Functions SDK to your app](#add-the-firebase-functions-sdk-to-your-app)
7+
* [Use @nativescript/firebase-functions](#use-nativescriptfirebase-functions)
8+
* [Calling an endpoint](#calling-an-endpoint)
9+
* [Set and access regional Cloud Functions endpoints](#set-and-access-regional-cloud-functions-endpoints)
10+
* [Set regional function endpoint](#set-regional-function-endpoint)
11+
* [Access regional function endpoint](#access-regional-function-endpoint)
12+
* [Test Cloud Functions with a local emulator](#test-cloud-functions-with-a-local-emulator)
13+
* [API](#api)
14+
* [Functions class](#functions-class)
15+
* [ios](#ios)
16+
* [android](#android)
17+
* [app](#app)
18+
* [constructor()](#constructor)
19+
* [httpsCallable()](#httpscallable)
20+
* [useEmulator()](#useemulator)
21+
22+
## Intro
23+
This plugin allows you to use [Firebase Cloud Functions](https://firebase.google.com/docs/functions) with NativeScript.
624

7-
## What does it do
25+
[![image](https://img.youtube.com/vi/vr0Gfvp5v1A/hqdefault.jpg)](https://www.youtube.com/watch?v=vr0Gfvp5v1A)
826

9-
Firebase Cloud Functions let you automatically run backend code in response to events triggered by Firebase features and HTTPS requests. Your code is stored in Google's cloud and runs in a managed environment. There's no need to manage and scale your own servers.
27+
## Set up your app for Firebase
1028

11-
[![image](https://img.youtube.com/vi/vr0Gfvp5v1A/hqdefault.jpg)](https://www.youtube.com/watch?v=vr0Gfvp5v1A)
29+
- To set up and initialize Firebase for your NativeScript app, follow the instructions on the documentation of the [@nativescript/firebase-core](../firebase-core/) plugin.
30+
31+
<!-- ## Create your Firestore database
1232
13-
After you write and deploy a function, Google's servers begin to manage the function immediately. You can fire the function directly with an HTTP request, via the Cloud Functions module, or in the case of background functions, Google's servers will listen for events and run the function when it is triggered.
33+
To create your Firestore database, follow the instructions at [Create a Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart#create). -->
1434

15-
For more information on use cases, view the [Firebase Cloud Functions](https://firebase.google.com/docs/functions/use-cases) documentation.
35+
## Add the Firebase Functions SDK to your app
36+
37+
To add the Cloud Firebase Functions SDK to your app, install the `@nativescript/firebase-functions` plugin by running the following command in the root directory of your project.
38+
39+
```cli
40+
npm install @nativescript/firebase-functions
41+
```
1642

17-
## Usage
43+
## Use @nativescript/firebase-functions
1844

19-
The Cloud Functions module provides the functionality to directly trigger deployed HTTPS callable functions, without worrying about security or implementing a HTTP request library.
45+
The Cloud Functions module provides the functionality to directly trigger deployed HTTPS callable functions, without worrying about security or implementing an HTTP request library.
2046

21-
Functions deployed to Firebase have unique names, allowing you to easily identify which endpoint you wish to send a request to. To learn more about deploying Functions to Firebase, view the Writing & Deploying Functions documentation.
47+
Functions deployed to Firebase have unique names, allowing you to easily identify which endpoint you wish to send a request to.
2248

2349
## Calling an endpoint
2450

25-
Assuming we have a deployed a callable endpoint named listProducts, to call the endpoint the library exposes a httpsCallable method. For example:
51+
Assuming we have to deploy a callable endpoint named `listProducts`. To call the endpoint, the library exposes a `httpsCallable` method. For example:
2652

2753
```ts
2854
// Deployed HTTPS callable
@@ -34,7 +60,7 @@ exports.listProducts = functions.https.onCall(() => {
3460
});
3561
```
3662

37-
Within the application, the list of products returned can be directly accessed:
63+
Within the application, the list of products returned can be directly accessed by passing the name of the endpoint to the `httpsCallable` method:
3864

3965
```ts
4066
import { firebase } from '@nativescript/firebase-core';
@@ -48,14 +74,17 @@ firebase()
4874
});
4975
```
5076

51-
## Regional Cloud Functions
77+
## Set and access regional Cloud Functions endpoints
78+
5279
Cloud Functions are _regional_, which means the infrastructure that runs your Cloud Function is located in specific regions.
5380

54-
By default, functions run in the _us-central1_ region. View the [supported regions](https://firebase.google.com/docs/functions/locations).
81+
By default, functions run in the `us-central1` region. To see supported regions, see [supported regions](https://firebase.google.com/docs/functions/locations#supported_regions).
82+
83+
### Set regional function endpoint
5584

56-
To run functions in a different region, after initializing Firebase App set the region using _firebase().app().functions(region)_.
85+
To run functions in a different region after initializing Firebase App, set the region using `firebase().app().functions(region)`.
5786

58-
Regional function endpoint example (using _europe-west2_ region ):
87+
The code below shows an example of setting a regional function endpoint(`europe-west2`):
5988
```ts
6089
// Deployed HTTPS callable
6190
exports.listProducts = functions.region("europe-west2").https.onCall(() => {
@@ -66,7 +95,9 @@ exports.listProducts = functions.region("europe-west2").https.onCall(() => {
6695
});
6796
```
6897

69-
To access the regional function endpoint:
98+
### Access regional function endpoint
99+
100+
To access a regional function endpoint, call the `firebase().app().functions(region)` method on the Firebase App instance:
70101
```ts
71102
import { firebase } from '@nativescript/firebase-core';
72103
import '@nativescript/firebase-functions';
@@ -83,17 +114,87 @@ firebase()
83114
});
84115
```
85116

86-
## Using an emulator
117+
## Test Cloud Functions with a local emulator
87118

88-
Whilst developing your application with Cloud Functions, it is possible to run the functions inside of a local emulator.
119+
Whilst developing your application with Cloud Functions, you can run the functions inside of a local emulator.
89120

90-
To call the emulated functions, call the useEmulator method exposed by the library:
121+
To call the emulated functions, connect the Cloud Functions to a local emulator by calling the [useEmulator](#useemulator) method on the `Functions` instance with the host and port of the emulator.
91122

92123
```ts
93124
import { firebase } from '@nativescript/firebase-core';
94125
firebase().functions().useEmulator('localhost', 5000);
95126
```
96127

128+
## API
129+
### Functions class
130+
131+
#### ios
132+
```ts
133+
functionsIOs: FIRFunctions = firebase.functions().ios;
134+
```
135+
A `readonly` property that returns the native iOS `FIRFunctions` instance.
136+
137+
---
138+
#### android
139+
```ts
140+
functionsAndroid: com.google.firebase.functions.FirebaseFunctions = firebase.functions().android;
141+
```
142+
143+
A `readonly` property that returns the native Android `com.google.firebase.functions.FirebaseFunctions` instance.
144+
145+
---
146+
#### app
147+
```ts
148+
app: FirebaseApp = firebase().functions().app;
149+
```
150+
151+
A `readonly` property that returns the FirebaseApp instance associated with the Functions instance.
152+
153+
---
154+
#### constructor()
155+
```ts
156+
functions: Functions = new Functions(app);
157+
```
158+
Creates a new Functions instance.
159+
160+
| Parameter | Type | Description |
161+
| --- | --- | --- |
162+
| `app` | `FirebaseApp` | An _optional_ FirebaseApp instance to use. |
163+
164+
---
165+
#### httpsCallable()
166+
```ts
167+
task: HttpsCallable = firebase().functions().httpsCallable(name, options);
168+
169+
httpsCallable(data).then((response: HttpsCallableResult) => {
170+
// Do something with the response
171+
}).catch((error: HttpsCallableError) => {
172+
console.log(error.code, error.message, error.details);
173+
174+
});
175+
```
176+
Returns a task function that can be called with optional data. The task function returns a Promise that will be resolved with the result(`HttpsCallableResult`) of the function execution. If the task fails, the Promise will be rejected with an [HttpsCallableError](https://github.com/NativeScript/firebase/blob/main/packages/firebase-functions/index.d.ts#L6-L10).
177+
178+
| Parameter | Type | Description |
179+
| --- | --- | --- |
180+
| `name` | `string` | The name of the reference to the Callable HTTPS trigger. |
181+
| `options` | [HttpsCallableOptions](https://github.com/NativeScript/firebase/blob/main/packages/firebase-functions/common.ts#L5-L7) | An _optional_ object that sets the length of timeout, in `seconds`, for calls for this `Functions` instance. |
182+
183+
---
184+
185+
#### useEmulator()
186+
```ts
187+
firebase().functions().useEmulator(host, port);
188+
```
189+
Allows you to test Cloud Functions locally by connecting to the emulator.
190+
191+
| Parameter | Type | Description |
192+
| --- | --- | --- |
193+
| `host` | `string` | The host of the emulator to connect to. |
194+
| `port` | `number` | The port of the emulator to connect to. |
195+
196+
---
197+
97198
## License
98199

99200
Apache License Version 2.0

0 commit comments

Comments
 (0)