WithCloud Functions (2nd gen), you can trigger functions in response tocustomevents. These are events provided by special or additional event providers, asopposed to the Firebase events natively supported by theFirebase SDK forCloud Functions.Via custom event triggers, your app can respond to events provided byFirebase Extensions, or you can publish your own customevents and trigger functions in response to them.

All custom events conform to theCloudEvents JSON event formatand are published toEventarc.Eventarcusage fees apply.

Trigger functions with custom events

You can publish custom events (or obtain events from Firebase extensions) andtrigger functions in response to those events by implementing this basic flow:

1. Publish the desired events to an Eventarc channel, or identify availableevents provided by an extension that you have installed.
2. In your function code, subscribe to events on the Eventarc channel withan event handler.
3. In the function, parse the payload returned in theCloudEvent object and perform whatever custom logic your app requires.

For example, a game app might want to send notifications to users as they enteror leave the leaderboard of top ten competitors. This app could publishleaderboard events to the default channel, and then handle the event in afunction that sends targeted push notifications to users.

In anotherexample, an extension designed to help apps process large images might emit anevent on the completion of image resizing. Apps with this extension installedcould handle the completion event by updating links in the app to point toresized versions of the image.

Publish an event to a channel

Eventarc events are published intochannels.Channels are a way to group related events and manage accesspermissions. When you install an extension or deploy a function that consumescustom events, Firebase automatically creates a default channel namedfirebase in theus-central1 region. TheFirebase Admin SDK providesaneventarc subpackage for publishing to channels.

To publish an event from a trusted server (or another function) using thedefault channel:

import{getEventarc}from'firebase-admin/eventarc';getEventarc().channel().publish({type:'achieved-leaderboard',subject:'Welcome to the top 10',data:{message:'You have achieved the nth position in our leaderboard!  To see . . .'}});

In addition to automatically creating the default channel, Firebase sets theenvironment variableEVENTARC_CLOUD_EVENT_SOURCE, which specifies the sourceof the event. If you are publishing events outside ofCloud Functions for Firebase,you'll need to explicitly add thesource field in your event payload.

Handle custom events

You can handle all custom events, including extensions events, with theonCustomEventPublished oron_custom_event_publishedhandlers. First, import this handler from the Eventarc SDK along with theFirebase Admin SDK:

const{onCustomEventPublished}=require("firebase-functions/eventarc");constlogger=require("firebase-functions/logger");const{initializeApp}=require("firebase-admin/app");const{getFirestore}=require("firebase-admin/firestore");
index.js

fromfirebase_adminimportfirestore,initialize_appfromfirebase_functionsimporteventarc_fn
main.py

In your function code, pass in the event name as shown for the example function:

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.returngetFirestore().collection("images").doc(event.subject.replace("/","_"))// original file path.set(event.data);// resized images paths and sizes});
index.js

@eventarc_fn.on_custom_event_published(event_type="firebase.extensions.storage-resize-images.v1.complete")defonimageresized(event:eventarc_fn.CloudEvent)->None:print("Received image resize completed event: ",event.type)ifnotisinstance(event.subject,str):print("No 'subject' data.")return# For example, write resized image details into Firestore.firestore_client:google.cloud.firestore.Client=firestore.client()collection=firestore_client.collection("images")doc=collection.document(event.subject.replace("/","_"))# original file pathdoc.set(event.data)# resized images paths and sizes
main.py

For each particular extension, the payload returned in the event object providesdata you can use to perform custom logic for your application flow. In thiscase, the function uses theAdmin SDK to copy metadata about the resizedimage to a collection inCloud Firestore, obtaining the filename from thesubject provided by the event, and saving metadata from thedata providedby the event.

Publish and handle events on non-default channels

Custom channels can be useful for cases where you have special permission needsor other requirements, and don't want the same level of visibility and accessfor all events. You can create your own channels using theGoogle Cloud console. Publishing and subscribing for events must be done on the same channel.

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 youwant to handle events that are published in a non-default channel for theus-west1 location, you need to specify the channel as shown:

import{onCustomEventPublished}from"firebase-functions/v2/eventarc";exportconstfunc=onCustomEventPublished({eventType:"firebase.extensions.storage-resize-images.v1.complete",channel:"locations/us-west1/channels/firebase",region:"us-west1",},(event)=>{...});

@eventarc_fn.on_custom_event_published(event_type="firebase.extensions.storage-resize-images.v1.complete",channel="locations/us-west1/channels/firebase",region="us-west1")defonimageresizedwest(event:eventarc_fn.CloudEvent)->None:print("Received image resize completed event: ",event.type)# ...
main.py