Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

Create and handle custom event triggers

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:

  1. Install an extension that provides one or more custom events.
  2. Handle an event type by deploying an onCustomEventPublished handler. In this function, parse the payload returned in the CloudEvent 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) => { ... });