With Cloud Functions v2, you can trigger functions in response to custom events. These are events provided by special or additional event providers, as opposed to the Firebase events natively supported by the Firebase SDK for Cloud Functions.
During the public preview, available custom events are provided by Firebase Extensions. You can install an extension in your app and then respond to custom events in this basic flow:
- Install an extension that provides one or more custom events.
- Handle an event type by deploying an
onCustomEventPublished
handler. In this function, parse the payload returned in theCloudEvent
object, and perform whatever custom logic your app requires.
For example, an extension designed to help apps process large images might emit an event on the completion of image resizing. Apps with this extension installed could handle the completion event by updating links in the app to point to resized versions of the image.
All custom events conform to the CloudEvents JSON event format. For key information such as the list of available events and the details of the event payload, refer to a particular extension's documentation.
Handle a custom event
Once you have discovered a custom event available from an installed extension,
you can handle that event with the
onCustomEventPublished
handler. First, import this handler from the Eventarc SDK along with the
Firebase Admin SDK for Node.js for your custom logic and the logger
SDK for
handling errors:
const {onCustomEventPublished} = require("firebase-functions/v2/eventarc");
const logger = require("firebase-functions/logger");
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");
In your function code, pass in the event name as shown for the example function onimageresized
:
exports.onimageresized = onCustomEventPublished(
"firebase.extensions.storage-resize-images.v1.complete",
(event) => {
logger.info("Received image resize completed event", event);
// For example, write resized image details into Firestore.
return getFirestore()
.collection("images")
.doc(event.subject.replace("/", "_")) // original file path
.set(event.data); // resized images paths and sizes
});
For each particular extension, the payload returned in the event object provides
data you can use to perform custom logic for your application flow. In this
case, the function uses the Admin SDK to copy metadata about the resized
image to a collection in Cloud Firestore, obtaining the filename from the
subject
provided by the event, and saving metadata from the data
provided
by the event.
Handle an event on a non-default channel
The example above assumes that the image completion event is published on the
default channel, in the default location us-central1
as specified in the
extension. In cases where a custom event is published on a non-default channel,
you'll need to specify the channel in your function code. For example, if you
want to handle events that are published in a non-default channel for the
us-west1
location, you need to specify the channel as shown:
import { onCustomEventPublished } from "firebase-functions/v2/eventarc";
export const func = onCustomEventPublished(
{
eventType: "firebase.extensions.storage-resize-images.v1.complete",
channel: "locations/us-west1/channels/firebase",
region: "us-west1",
},
(event) => { ... });