Your extension's specification file (
extension.yaml
) contains your extension's
metadata, declares the resources created by the extension and the APIs and
access required by the extension, and defines any user-configured parameters
provided by the extension.
The tables on this page describe the fields available for an
extension.yaml
file.
Basic and identifying information
name: your-extension-name
version: 1.0.0 # Semantic versioning (semver)
specVersion: v1beta # Always "v1beta"
license: Apache-2.0 # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true # Always "true"
displayName: Your extension name
description: >-
Description of the extension. (One or two
sentences.)
icon: icon.png
tags: [tag, anothertag]
sourceUrl: https://github.com/your-org/your-repo # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md
author:
authorName: Your Company
email: extensions@example.com
url: https://example.com/
contributors:
- authorName: Your Name
- authorName: Another Contributor
email: colleague@example.net
url: https://github.com/their-org/
Basic fields
|
name
string
(required)
|
Identifier for the extension.
Can only contain lowercase letters, numbers, and dashes; 40 character
limit.
Note:
This value is used to generate the extension's
instance ID (which is then used to generate the names of the
extension's service account and the extension-specific resources).
|
version
string
(required)
|
Version of the extension.
Must follow semver versioning (for example, 1.2.0).
|
specVersion
string
(required)
|
Version of the Firebase Extensions specification.
Current value:
v1beta
|
license
string
(optional)
|
License for the extension.
Your extension must be licensed using
Apache-2.0
.
|
billingRequired
boolean
(optional)
|
Whether the services used by the extension require a paid-tier
Firebase billing account.
Always set to
true
.
|
displayName
string
(optional)
|
Friendly display name for the extension (3-5 words).
40 character limit.
|
description
string
(optional)
|
Brief description of the task your extension performs (~1 sentence).
|
icon
string
(optional)
|
File to use as your extension's icon on
extensions.dev
and
the Firebase console.
This file must be a square PNG between 512x512 and 1024x1024 pixels.
Put the file in the same directory as
extension.yaml
; you
cannot specify a subdirectory.
Keep the following guidelines in mind when designing an icon for your
extension:
- Select background and artwork colors that are appropriate for your
brand.
- Keep your icon colors simple, using only 2 colors. Multiple colors
can make your icon visually overwhelming.
- For the same reason, don't use gradients in your icon. Gradients
are hard to discern at small sizes and make the icon visually
complex.
- Use simple, unique imagery that communicates your extension’s
functionality.
- If your company builds multiple extensions, don't use your logo as
the icon. Users will have difficulty distinguishing between your
extensions.
- Make the artwork graphic and bold. Don't use delicate or elaborate
art, which will not render well at smaller sizes.
- Don't include words that explain what your extension does. Text is
often illegible at smaller sizes.
|
tags
list of strings
(optional)
|
Tags to help users discover your extension.
The following tags map to categories on Extensions Hub:
marketing
,
messaging
,
payments
,
search
,
shipping
,
social
,
utilities
,
ai
|
sourceUrl
string
(optional)
|
Public URL where the extension directory can be accessed.
|
releaseNotesUrl
string
(optional)
|
Public URL where the release notes for the extension can be accessed.
|
author
one author object
(optional)
|
Primary author and point of contact for the extension.
author:
authorName: Your Company
email: extensions@example.com
url: https://example.com/
Author fields
|
authorName
string
(required)
|
Name of the author.
Can be a person, company, organization, etc.
|
email
string
(optional)
|
Email address of the author.
|
url
string
(optional)
|
Public URL where information about the author can be accessed.
|
|
contributors
list of author objects
(optional)
|
Any additional contributing authors for the extension.
contributors:
- authorName: Your Name
- authorName: Another Contributor
email: colleague@example.net
url: https://github.com/their-org/
Author fields
|
authorName
string
(required)
|
Name of the author.
Can be a person, company, organization, etc.
|
email
string
(optional)
|
Email address of the author.
|
url
string
(optional)
|
Public URL where information about the author can be accessed.
|
|
Firebase and Google Cloud APIs
These fields specify the Firebase and Google APIs the extension uses. When users
install the extension, they can elect to automatically enable these APIs in
their project.
apis:
- apiName: apiname.googleapis.com
reason: Explanation of why the extension uses this API
- apiName: anotherapiname.googleapis.com
reason: Explanation of why the extension uses this API
API fields
|
apiName
string
(required)
|
Name of the Google API
Must correspond to the
Service name
field as listed on each
API's overview page
(
example
) in the
Google Cloud API Library
|
reason
string
(required)
|
Brief description of why the extension needs to use this API
|
IAM roles
These fields specify the Cloud IAM roles the extension requires. The service
account provisioned for the extension is granted these roles.
You can only specify one of the
supported roles
.
roles:
- role: product.role
reason: Explanation of why the extension needs this level of access
- role: anotherproduct.role
resource: projects/${project_id}/resource_type/*
reason: Explanation of why the extension needs this level of access
Role fields
|
role
string
(required)
|
Name of the IAM role needed for the extension to operate
Must be one of the
supported roles
|
reason
string
(required)
|
Brief description of why the extension needs the access granted by
this role
|
resource
string
(optional)
|
Limit the scope of the role to this resource.
If omitted, defaults to
projects/${project_id}
.
See
Reduce
the scope of roles
.
|
External services
These fields specify the non-Firebase and non-Google services the extension uses
(typically REST APIs). The Firebase Extensions platform does not provide any
means of automatically enabling or performing authorization for these services.
externalServices:
- name: Example API
pricingUri: https://developers.example.com/pricing
- name: Another Example API
pricingUri: https://developers.example.com/pricing
External services fields
|
name
string
(required)
|
Name of the external service needed for the extension to operate
|
pricingUri
string
(required)
|
URI to pricing information for the service
|
User-configurable parameters
These fields define the parameters that the extension makes available for users
to configure.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What do you want to set PARAM_ID to?
This is a longer description of the parameter, often phrased as a prompt
to the user.
- param: ANOTHER_PARAM_ID
label: Short description of the parameter
description: >
What do you want to set ANOTHER_PARAM_ID to?
This is a longer description of the parameter.
example: example-input
validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
validationErrorMessage:
Must be a hyphen-delimited string of alphabetic characters
default: default-value
required: false
immutable: true
Parameter fields
|
param
string
(required)
|
Name of the parameter. You use this name to reference the parameter
value in code.
|
label
string
(required)
|
Short description for the parameter. Displayed to the user when they're
prompted for the parameter's value.
|
description
string
(optional)
|
Detailed description for the parameter. Displayed to the user when
they're prompted for the parameter's value.
Supports Markdown.
|
example
string
(optional)
|
Example value for the parameter.
|
default
string
(optional)
|
Default value for the parameter if the user leaves the parameter's value
blank.
|
validationRegex
string
(optional)
|
Regular expression for validation of the parameter's user-configured
value.
Google RE2
syntax
.
|
validationErrorMessage
string
(optional)
|
Error message to display if regex validation fails.
|
required
boolean
(optional)
|
Defines whether the user can submit an empty string when they're
prompted for the parameter's value. Defaults to
true
.
|
immutable
boolean
(optional)
|
Defines whether the user can change the parameter's value after
installation (such as if they reconfigure the extension). Defaults to
false
.
Note:
If you define a "location" parameter for the deployed
functions of your extension, set this field to
true
.
|
type
string
(optional)
|
The parameter type. Special parameter types might have additional
requirements or different UI presentation. See the following sections.
|
Selectable and multi-selectable parameters
Selectable and multi-selectable parameters prompt users to choose from a list of
predefined options.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
Do you want to enable the option?
type: select
options:
- label: Yes
value: true
- label: No
value: false
- param: ANOTHER_PARAM_ID
label: Short description of the parameter
description: >-
Which options do you want to enable?
type: multiselect
options:
- value: red
- value: green
- value: blue
Multiple-choice parameter fields
|
type
string
|
select
or
multiselect
Specifies that the parameter can be one value (
select
)
or several values (
multiselect
) selected from a set of
predefined choices
|
options
list of options
(required)
|
The options from which the user can choose
Option fields
|
value
string
(required)
|
One of the values the user can choose. This is the value you get
when you read the parameter value in code.
|
label
string
(optional)
|
Short description of the selectable option. If omitted, defaults
to
value
.
|
|
Selectable resource parameters
Selectable resource parameters prompt users to select a resource (database
instance, storage bucket, etc.) from their project.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
Which resource do you want to use?
type: selectresource
resourceType: product.googleapis.com/ResourceType
Resource parameter fields
|
type
string
|
selectresource
Specifies that the parameter represents a project resource
|
resourceType
string
(required)
|
The type of resource to prompt the user to select.
Valid values:
storage.googleapis.com/Bucket
firestore.googleapis.com/Database
firebasedatabase.googleapis.com/DatabaseInstance
However, only Cloud Storage buckets currently have a selection UI
(other resource types are presented as free-form text input fields).
|
Secret parameters
User-provided secret values (such as API keys) are handled differently:
- Secret values are stored using Cloud Secret Manager. Only authorized clients
(such as an installed instance of an extension) can access these values.
- When users are prompted to provide these values, their input is not displayed.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What is the secret value?
type: secret
Secret parameter fields
|
type
string
|
secret
Specifies that the parameter is a secret value
|
Cloud Function resources
These fields declare the Cloud Functions included in an extension. The resource
declaration syntax looks a little different between 1st-gen and 2nd-gen
functions, which can coexist in an extension.
1st-gen Cloud Functions
resources:
- name: functionName
type: firebaseextensions.v1beta.function
description: >-
Description of what the function does. (One or two
sentences.)
properties:
runtime: runtime-version
eventTrigger:
eventType: google.product.event
resource: projects/_/resource/specifier
Resource fields
|
name
string
(required)
|
User-friendly name for the exported function.
If you don't specify the
entryPoint
property (see
below), this value must match the name of the function in your
functions source code.
The final name of the
deployed
function will be in the
following format:
ext-
extension-instance-id
-
name
.
|
type
string
(required)
|
For a 1st-gen function resource:
firebaseextensions.v1beta.function
|
description
string
(required)
|
Brief description of what task the function performs for the
extension.
|
properties
(required)
|
1st-gen Cloud Functions properties. The most important properties
are listed below, but you can find the complete list in the
Cloud
Functions reference
.
Properties
|
location
(optional)
|
Location to which to deploy the function. Defaults to
us-central1
|
entryPoint
(optional)
|
Name of the exported function within your functions source code
that the extension should look for. Defaults to the value of
name
, above.
|
sourceDirectory
(optional)
|
Directory that contains your
package.json
at its
root. The file for your functions source code must be in this
directory. Defaults to
functions
Note:
The
main
field of
package.json
specifies the file for your
functions source code (like
index.js
).
|
timeout
(optional)
|
The function's maximum execution time.
- Default:
60s
- Max value:
540s
|
availableMemoryMb
(optional)
|
Amount of memory in MB available for the function.
- Default:
256
- Valid values:
128
,
256
,
512
,
1024
, and
2048
|
runtime
(recommended)
|
Runtime environment for the function.
|
httpsTrigger
or
eventTrigger
or
scheduleTrigger
or
taskQueueTrigger
(one of these function trigger types is required)
|
See
Write
Cloud Functions for an extension
for specific information
about each trigger type.
|
|
2nd-gen Cloud Functions
resources:
- name: functionName
type: firebaseextensions.v1beta.v2function
description: >-
Description of what the function does. (One or two
sentences.)
properties:
buildConfig:
runtime: nodejs16
serviceConfig:
availableMemory: 512M
eventTrigger:
eventType: google.firebase.firebasealerts.alerts.v1.published
triggerRegion: global
eventFilters:
- attribute: alerttype
value: crashlytics.newFatalIssue
Resource fields
|
name
string
(required)
|
User-friendly name for the exported function.
If you don't specify the
entryPoint
property (see
below), this value must match the name of the function in your
functions source code.
The final name of the
deployed
function will be in the
following format:
ext-
extension-instance-id
-
name
.
|
type
string
(required)
|
For a 2nd-gen function resource:
firebaseextensions.v1beta.v2function
|
description
string
(required)
|
Brief description of what task the function performs for the
extension.
|
properties
(required)
|
2nd-gen Cloud Functions properties. The most important properties
are listed below, but you can find the complete list in the
Cloud
Functions reference
.
Properties
|
location
(optional)
|
Location to which to deploy the function. Defaults to
us-central1
|
sourceDirectory
(optional)
|
Directory that contains your
package.json
at its
root. The file for your functions source code must be in this
directory. Defaults to
functions
Note:
The
main
field of
package.json
specifies the file for your
functions source code (like
index.js
).
|
There are also three object-type fields with their own properties:
buildConfig properties
|
buildConfig.runtime
(recommended)
|
Runtime environment for the function.
|
buildConfig.entryPoint
(optional)
|
Name of the exported function within your functions source code
that the extension should look for. Defaults to the value of
name
, above.
|
serviceConfig properties
|
serviceConfig.timeoutSeconds
(optional)
|
The function's maximum execution time.
- Default:
60
- Max value:
540
|
serviceConfig.availableMemory
(optional)
|
The amount of memory available for a function. Defaults to
256M
. Supported units are
k
,
M
,
G
,
Mi
,
Gi
.
If no unit is supplied, the value is interpreted as bytes.
|
eventTrigger properties
|
eventTrigger.eventType
(required)
|
The type of event to listen for. See
Write Cloud
Functions for an extension
for the event types available for
each product.
|
eventTrigger.eventFilters
(optional)
|
Filters that further limit the events to listen to. For example,
you could only listen to events matching a specific resource
pattern. See
Write Cloud
Functions for an extension
for information on filtering each
type of event.
|
eventTrigger.channel
(optional)
|
The name of the channel associated with the trigger in
projects/{project}/locations/{location}/channels/{channel}
format. If you omit this property, the function will listen for
events on the project's default channel.
|
eventTrigger.triggerRegion
(optional)
|
The trigger will only receive events originating in this region.
It can be the same region as the function, a different region or
multi-region, or the global region. If not provided, defaults to
the same region as the function.
|
|
Lifecycle events
Lifecycle events let you specify functions that will run when a user installs,
updates, or configure an instance of your extension.
See
Handle your extension's lifecycle events
.
lifecycleEvents:
onInstall:
function: myTaskFunction
processingMessage: Describes the task being completed
onUpdate:
function: myOtherTaskFunction
processingMessage: Describes the task being completed
onConfigure:
function: myOtherTaskFunction
processingMessage: Describes the task being completed
Lifecycle event fields
|
onInstall
(optional)
|
Specifies a function that runs when a user installs the
extension.
Function specification
|
function
string
(required)
|
Name of the task queue-triggered function that will handle
the event.
This function must be declared in the
resources
section and have
taskQueue
defined.
|
processingMessage
string
(required)
|
Message to display in the Firebase console while the task is in
progress.
|
|
onUpdate
(optional)
|
Specifies a function that runs when a user updates the
extension.
Function specification
|
function
string
(required)
|
Name of the task queue-triggered function that will handle
the event.
This function must be declared in the
resources
section and have
taskQueue
defined.
|
processingMessage
string
(required)
|
Message to display in the Firebase console while the task is in
progress.
|
|
onConfigure
(optional)
|
Specifies a function that runs when a user re-configures the
extension.
Function specification
|
function
string
(required)
|
Name of the task queue-triggered function that will handle
the event.
This function must be declared in the
resources
section and have
taskQueue
defined.
|
processingMessage
string
(required)
|
Message to display in the Firebase console while the task is in
progress.
|
|
Custom events (Eventarc)
Custom events are events that your extension emits to allow users to insert
their own logic into your extension. See the Eventarc section in
Add user hooks to an extension
.
events:
- type: publisher-id.extension-name.version.event-name
description: Description of the event
- type: publisher-id.extension-name.version.another-event-name
description: Description of the other event
Custom event fields
|
type
string
(required)
|
The type identifier of the event. Construct the identifier out of 3-4
dot-delimited fields: the publisher ID, extension name, and event name
fields are required; the version field is recommended. Choose a unique
and descriptive event name for each event type you publish.
|
description
string
(required)
|
Description of the event.
|