Blog Studio Go to console

    Reference for extension.yaml

    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.
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: