Cada extensión debe tener documentación que les enseñe a los usuarios qué hace y cómo usarla.
La documentación mínima y obligatoria es este conjunto de tres archivos de Markdown:
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
Además, te recomendamos proporcionar los siguientes documentos:
- Un archivo
READMEpara el repositorio público de la extensión - Instructivos, guías y referencias de mayor extensión que se publicaron en tu sitio web y
tengan vinculación a tu
PREINSTALL.md
Para conocer algunas prácticas recomendadas, además de expresiones y estructuras comunes, te recomendamos revisar los archivos disponibles con las Extensiones de Firebase oficiales.
Crea un archivo README
El directorio de la extensión puede contener un archivo README. Ten en cuenta que el comando firebase ext:dev:init no genera uno automáticamente.
Sin embargo, Firebase CLI admite el siguiente comando de conveniencia para generar automáticamente un archivo README con contenido extraído de los archivos extension.yaml y PREINSTALL.md:
firebase ext:info ./path/to/extension --markdown > README.md
Todos los archivos README de las Extensiones de Firebase oficiales se generan con este comando.
Agrega información de instalación
Después de escribir o generar un archivo README, agrégale la información de la instalación. Puedes usar el siguiente fragmento como plantilla:
--- ## 🧩 Install this extension ### Console [][install-link] [install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id /extension_name ### Firebase CLI ```bash firebase ext:installpublisher_id /extension_name --project=[your-project-id] ``` > Learn more about installing extensions in the Firebase Extensions documentation: > [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console), > [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli) ---
Escribe un archivo PREINSTALL
El archivo PREINSTALL es la descripción general de la extensión, una especie de página de “marketing”.
¿Qué contiene este archivo?
- Descripción completa de la funcionalidad de la extensión
- Lista de requisitos, como la configuración de la base de datos o el acceso a un servicio que no es de Google (ejemplo)
- Descripción breve de las tareas previas a la instalación y sus instrucciones
- Descripción breve de las tareas posteriores a la instalación (ejemplo). Las instrucciones detalladas se encuentran en
POSTINSTALL - Descripción breve de las implicaciones de facturación (comienza con texto estándar)
¿Dónde se muestra este contenido al usuario?
Firebase console">
Firebase console">
- En la página de la extensión, en extensions.dev
- En el repositorio de código fuente de la extensión (dentro del directorio de la extensión)
- Como parte del archivo README de la extensión (si usas la marca
--markdown > README.md
Los archivos PREINSTALL no pueden acceder a los valores de los parámetros de la extensión, por lo que no debes esperar que las referencias de parámetros se procesen con valores reales.
¿Cuáles son algunas de las prácticas recomendadas?
- Si es posible, limita el contenido del archivo
PREINSTALLa una página. - Proporciona el nivel de detalle que el usuario final necesita saber antes de instalar la extensión.
- Incluye instrucciones detalladas en el archivo
POSTINSTALLo en otros archivos complementarios. - Menciona brevemente si proporcionas otras herramientas o secuencias de comandos para admitir la extensión.
Texto estándar útil para PREINSTALL
Te recomendamos utilizar la mayor cantidad de texto estándar posible para tu extensión. Proporcionamos algunos ejemplos, pero lo más importante es asegurarse de que se incluyan todos los servicios facturados por Google y por terceros.
Puedes usar los siguientes recursos para encontrar los detalles correctos de los precios de los productos:
Para todas las extensiones, incluye esta sección para ayudar a los usuarios a comprender las implicaciones de facturación:
Billing
This extension uses other Firebase or Google Cloud services which may have
associated charges:
* <list Google services / products that your extension uses>
* <list Firebase services that your extension uses>
* Cloud Secret Manager <if the extension uses secret params>
* Cloud Functions
When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)
<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.
Escribe un archivo POSTINSTALL
El archivo POSTINSTALL es la página de instrucciones detalladas para después de la instalación de la extensión.
¿Qué contiene este archivo?
- Instrucciones detalladas para cualquier tarea obligatoria posterior a la instalación, como configurar reglas de seguridad de Firebase o agregar código del cliente (ejemplo)
- Instrucciones genéricas para probar la extensión instalada de inmediato (por ejemplo, “Ve a la consola y realiza esta acción”)
- Información básica sobre la activación de la extensión, especialmente para las extensiones activadas por solicitudes HTTP
- Instrucciones breves para supervisar la extensión instalada (comienza con texto estándar)
¿Dónde se muestra este contenido al usuario?
Firebase console">
Firebase console">
En Firebase console, después de que un usuario instale tu extensión (en la tarjeta de detalles de la extensión instalada)
- Asegúrate de revisar cómo se muestra el contenido de
POSTINSTALL. Para ello, instala la extensión en un proyecto real.
- Asegúrate de revisar cómo se muestra el contenido de
En el repositorio de código fuente de la extensión (dentro del directorio de la extensión)
Los archivos POSTINSTALL pueden acceder a los valores de los parámetros y a muchas variables relacionadas con la función para la extensión. Cuando se muestra el contenido de POSTINSTALL en
Firebase console, se muestran los valores reales en lugar de las referencias de parámetros
o variables. Obtén más información sobre cómo hacer referencia a parámetros y variables en el archivo POSTINSTALL.
¿Cuáles son algunas de las prácticas recomendadas?
- El contenido completo del archivo
POSTINSTALLdebe ser conciso pero descriptivo. - Divide el contenido con encabezados para separar las tareas o los conceptos distintos.
- Considera publicar instrucciones detalladas para un flujo de trabajo o una tarea específicos en tu sitio web (ejemplo) o en archivos de Markdown complementarios del repositorio de extensiones (ejemplo).
- Haz referencias a parámetros y variables relacionadas con funciones para que el usuario pueda ver sus valores configurados en el contexto de las instrucciones.
Haz referencia a parámetros y variables
Después de la instalación, Firebase console muestra el contenido del archivo POSTINSTALL de la extensión. Si haces referencia a parámetros y variables relacionadas con funciones (consulta la tabla a continuación) en el archivo POSTINSTALL, la consola propagará estas referencias con los valores reales para la instancia instalada.
Accede a los valores de parámetros configurados en el archivo POSTINSTALL con la siguiente sintaxis: ${param:PARAMETER_NAME}
También puedes hacer referencia a las siguientes variables relacionadas con funciones solo en el archivo POSTINSTALL. Firebase admite estas variables para que puedas brindar orientación a los usuarios con más facilidad después de la instalación. Solo están disponibles para su uso en el archivo POSTINSTALL porque los valores de estas variables no están disponibles hasta después de la instalación.
En esta tabla function-name es el valor del campo name en el objeto del recurso de la función dentro de extension.yaml.
| Referencia para la variable relacionada con la función | Descripción | Valor de la variable (propagado automáticamente por Firebase después de la instalación de la extensión) |
|---|---|---|
${function:function-name.location}
|
||
| Ubicación en la que se implementa la función | Valor de ejemplo:us-central1 |
|
${function:function-name.name}
|
||
| Nombre de la función implementada final, que incluye el ID de instancia de la extensión |
Formato generalizado: Valor de ejemplo: |
|
${function:function-name.url}
(solo aplicable para funciones de HTTP) |
||
| URL de la función implementada final, a la que el código del cliente puede realizar solicitudes HTTP |
Formato generalizado:
Valor de ejemplo: |
|
Texto estándar útil para POSTINSTALL
Te recomendamos utilizar la mayor cantidad de texto estándar posible para tu extensión.
Para todas las extensiones, incluye la siguiente sección para ayudar a los usuarios a supervisar la extensión instalada:
Monitoring
As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.
Documenta cómo activar una extensión
En la documentación para el usuario de la extensión, debes indicar a los usuarios cómo activar la extensión. Estas instrucciones pueden ser tan detalladas como sea necesario, pero ten en cuenta las prácticas recomendadas para redactar un archivo POSTINSTALL.
Para obtener orientación sobre cómo proporcionar estas instrucciones, expande la siguiente sección que corresponde a tu extensión.
Extensiones activadas por eventos en segundo plano
Los usuarios pueden activar una extensión activada por eventos en segundo plano de varias maneras, según los productos involucrados.
Realiza cambios directamente en la consola
Puedes indicar a los usuarios que realicen cambios para activar la extensión directamente en Firebase console, especialmente para la prueba inicial de tu extensión. Por ejemplo, supongamos que la extensión crea un nuevo documento de Cloud Firestore cada vez que se crea un nuevo usuario de Firebase Authentication. Puedes indicar a los usuarios que prueben una instancia instalada de tu extensión. Para ello, agrega manualmente un nuevo usuario de Authentication en la consola. Luego, podrán ver el nuevo documento creado en la sección Cloud Firestore de la consola.
Agrega un código del cliente
Cuando corresponda, también puedes indicar a tus usuarios cómo agregar un código del cliente para activar la extensión. Debes dirigir a los usuarios a la documentación oficial de las API que tendrán que usar. También puedes incluir apps de muestra o muestras de clientes compilados para ayudar a los usuarios a integrar la extensión en sus aplicaciones (consulta la extensión Distributed Counter para ver un ejemplo).
Extensiones activadas por solicitudes HTTP
Para que los usuarios puedan activar funciones mediante solicitudes HTTP (y, por lo tanto, la extensión), debes proporcionarles el nombre o la URL de la función implementada.
El nombre de la función implementada final no es el mismo que el name que especificaste en el objeto de recurso de la función dentro de extension.yaml. Para admitir varias instalaciones de la misma extensión en un proyecto, Firebase cambia el nombre de la función con este formato: ext-extension-instance-id-function-name
Las siguientes viñetas son texto estándar sugerido para incluir en el archivo POSTINSTALL de la extensión. Después de la instalación, la consola de Firebase
muestra el contenido del archivo POSTINSTALL y propaga estas referencias
con los valores configurados reales para la instancia instalada. Por ejemplo, si definiste una función llamada yourFunction, puedes incluir lo siguiente (según corresponda):
Para funciones de HTTP
onRequestTo trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.Para funciones de HTTP que admiten llamadas (
onCall)This extension is implemented as an HTTP callable function. To call it from your client app, follow the instructions in the [callable functions documentation](https://firebase.google.com/docs/functions/callable#call_the_function). The name of the function to call is **`${function:yourFunction.name}`**, and its region is **`${function:yourFunction.location}`**.
Escribe un archivo CHANGELOG
¿Qué contiene este archivo?
Toda extensión debe tener un archivo CHANGELOG.md que documente los cambios
incluidos en cada versión nueva de la extensión que publiques. Coloca cada versión
en un encabezado de nivel 2 (##), de lo contrario, puedes usar
el formato de Markdown que quieras.
El siguiente ejemplo es un extracto de una de las extensiones oficiales:
## Version 0.1.3 feature - Support deletion of directories (issue #148). ## Version 0.1.2 feature - Add a new param for recursively deleting subcollections in Cloud Firestore (issue #14). fixed - Fixed "cold start" errors experienced when the extension runs after a period of inactivity (issue #48). ## Version 0.1.1 Initial release of the _Delete User Data_ extension.
¿Dónde se muestra este contenido al usuario?
- En Firebase console y la CLI, cuando los usuarios actualicen a la versión nueva de tu extensión (Firebase y la CLI solo muestran los cambios que se aplicarían si el usuario completara la actualización).
- El repositorio del código fuente de tu extensión (dentro del directorio de la extensión)