Create and handle custom event triggers

With Cloud Functions (2nd gen), 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 . Via custom event triggers, your app can respond to events provided by Firebase Extensions , or you can publish your own custom events and trigger functions in response to them.

All custom events conform to the CloudEvents JSON event format and are published to Eventarc . Eventarc usage fees apply.

Trigger functions with custom events

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

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

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

In another 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.

Publish an event to a channel

Eventarc events are published into channels . Channels are a way to group related events and manage access permissions. When you install an extension or deploy a function that consumes custom events, Firebase automatically creates a default channel named firebase in the us-central1 region. The Firebase Admin SDK provides an eventarc subpackage for publishing to channels.

To publish an event from a trusted server (or another function) using the default 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 the environment variable EVENTARC_CLOUD_EVENT_SOURCE , which specifies the source of the event. If you are publishing events outside of Cloud Functions for Firebase , you'll need to explicitly add the source field in your event payload.

Handle custom events

You can handle all custom events, including extensions events, with the onCustomEventPublished or on_custom_event_published handlers. First, import this handler from the Eventarc SDK along with the Firebase Admin SDK :

  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" 
 ); 
 
  index 
 . 
 js 
 
 
 

  from 
  
 firebase_admin 
  
 import 
 firestore 
 , 
 initialize_app 
 from 
  
 firebase_functions 
  
 import 
 eventarc_fn 
 main 
 
 
 . 
 py