Cada extensión debe tener documentación que enseñe a los usuarios qué hace la extensión y cómo usarla.
La documentación mínima requerida es este conjunto de tres archivos de rebajas:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
Además, también deberías considerar producir:
- Un archivo
READMEpara el repositorio público de la extensión. - Tutoriales, guías y referencias más extensos publicados en su propio sitio web y vinculados en su
PREINSTALL.md.
Para conocer algunas de las mejores prácticas y frases y estructuras comunes, recomendamos revisar los archivos disponibles con las extensiones oficiales de Firebase .
Creando un LÉAME
Su directorio de extensión puede contener opcionalmente un archivo README. Tenga en cuenta que el comando firebase ext:dev:init no genera uno automáticamente.
Sin embargo, Firebase CLI admite el siguiente comando conveniente para generar automáticamente un archivo README que contenga contenido extraído de su archivo extension.yaml y su archivo PREINSTALL.md :
firebase ext:info ./path/to/extension --markdown > README.md
Todos los archivos README para las extensiones oficiales de Firebase se generan con este comando.
Agregar información de instalación
Después de escribir o generar un archivo README, agréguele información de instalación. Puede utilizar 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:install publisher_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) ---
Escribir un archivo PREINSTALL
El archivo PREINSTALL es la descripción general de su extensión, un tipo de página de "marketing".
¿Qué contenido hay en este archivo?
- Descripción completa de la funcionalidad de su extensión
- Lista de requisitos previos, como la configuración de la base de datos o el acceso a un servicio que no sea de Google ( ejemplo )
- Breve descripción de las tareas previas a la instalación y sus instrucciones.
- Breve descripción de cualquier tarea posterior a la instalación ( ejemplo ) (las instrucciones detalladas se encuentran en
POSTINSTALL) - Breve descripción de las implicaciones de facturación (comience con el texto estándar )
¿Dónde se muestra este contenido al usuario?
- En la página de la extensión en extensions.dev .
- Su repositorio de código fuente para su extensión (dentro del directorio de extensiones)
- Como parte del archivo README de la extensión (si usa Firebase CLI
--markdown > README.md
Los archivos PREINSTALL no pueden acceder a los valores de los parámetros de la extensión, por lo que no debe esperar que las referencias de parámetros se representen con los valores reales.
¿Cuáles son algunas de las mejores prácticas?
- Mantenga el contenido completo del archivo
PREINSTALLen menos de una página , si es posible - Proporcione el nivel de detalle que un usuario final necesita saber antes de instalar la extensión.
- Coloque instrucciones detalladas en el archivo
POSTINSTALLu otros archivos complementarios. - Mencione brevemente si proporciona otras herramientas o scripts para admitir la extensión.
Recomendamos utilizar la mayor cantidad posible del siguiente texto repetitivo, según corresponda para su extensión. Hemos proporcionado algunos ejemplos, pero el punto más importante es garantizar que se incluyan todos los servicios facturados por Google y los que no son de Google.
Puede utilizar los siguientes recursos para encontrar los detalles correctos del precio del producto:
Para todas las extensiones, incluya esta sección para ayudar a sus 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>.
Escribir un archivo POSTINSTALL
El archivo POSTINSTALL es la página de instrucciones detallada posterior a la instalación de su extensión.
¿Qué contenido hay en este archivo?
- Instrucciones detalladas para cualquier tarea posterior a la instalación requerida , como configurar reglas de seguridad de Firebase o agregar código del lado del cliente ( ejemplo )
- Instrucciones genéricas sobre cómo probar inmediatamente la extensión instalada (por ejemplo, "ve a la consola y luego haz esto")
- Información básica sobre cómo activar la extensión, especialmente para extensiones activadas por solicitud HTTP
- Instrucciones breves sobre cómo monitorear la extensión instalada (comience con texto repetitivo )
¿Dónde se muestra este contenido al usuario?
En Firebase console después de que un usuario instala su extensión (en la tarjeta de detalles de la extensión instalada)
- Asegúrese de revisar la visualización del contenido
POSTINSTALLinstalando su extensión en un proyecto real .
- Asegúrese de revisar la visualización del contenido
Su repositorio de código fuente para su extensión (dentro del directorio de extensiones)
Los archivos POSTINSTALL pueden acceder a los valores de los parámetros y varias variables relacionadas con funciones para la extensión. Cuando el contenido POSTINSTALL se muestra en Firebase console, se muestran los valores reales en lugar de las referencias de parámetros o variables. Obtenga más información a continuación sobre cómo hacer referencia a parámetros y variables en su archivo POSTINSTALL .
¿Cuáles son algunas de las mejores prácticas?
- Mantenga el contenido completo del archivo
POSTINSTALLconciso, pero descriptivo. - Seccione el contenido utilizando títulos para separar distintas tareas o conceptos.
- Considere publicar instrucciones detalladas para un flujo de trabajo o tarea específica en su sitio web ( ejemplo ) o en archivos de rebajas complementarios dentro del repositorio de extensiones ( ejemplo ).
- Parámetros de referencia y variables relacionadas con funciones para que el usuario vea sus valores configurados en el contexto de las instrucciones.
Parámetros y variables de referencia
Después de la instalación, Firebase console muestra el contenido del archivo POSTINSTALL de la extensión. Si hace referencia a parámetros y variables relacionadas con funciones (consulte la tabla a continuación) en su archivo POSTINSTALL , la consola completa estas referencias con los valores reales de la instancia instalada.
Acceda a los valores de parámetros configurados en el archivo POSTINSTALL utilizando la siguiente sintaxis:${param: PARAMETER_NAME }
También puede hacer referencia a las siguientes variables relacionadas con funciones únicamente en su archivo POSTINSTALL . Firebase admite estas variables para que puedas brindar orientación más fácilmente a tus usuarios 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 de recurso de la función dentro de extension.yaml .
| Referencia para variables relacionadas con funciones | Descripción | Valor de variable (rellenado automáticamente por Firebase después de la instalación de la extensión) |
|---|---|---|
${function: function-name .location} | ||
| Ubicación donde 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 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: | |
Recomendamos utilizar la mayor cantidad posible del siguiente texto repetitivo, según corresponda para su extensión.
Para todas las extensiones, incluya la siguiente sección para ayudar a sus usuarios a monitorear su 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.
Documentar cómo activar una extensión
En la documentación de usuario de su extensión, debe instruir a sus usuarios sobre cómo activar su extensión. Estas instrucciones pueden ser tan detalladas como crea necesario, pero tenga en cuenta las mejores prácticas para escribir un archivo POSTINSTALL . Para obtener orientación sobre cómo proporcionar estas instrucciones, expanda la sección a continuación que se aplica a su extensión.
Sus usuarios pueden activar una extensión activada por eventos en segundo plano de varias maneras, según los productos involucrados.
Realizar cambios directamente en la consola.
Puedes indicar a tus usuarios que realicen cambios que activen la extensión directamente en Firebase console, especialmente para la prueba inicial de tu extensión. Por ejemplo, digamos que su extensión crea un nuevo documento de Cloud Firestore cada vez que se crea un nuevo usuario de Firebase Authentication. Puede indicar a sus usuarios que prueben una instancia instalada de su extensión agregando manualmente un nuevo usuario de autenticación en la consola. Luego podrán observar el nuevo documento creado en la sección Cloud Firestore de la consola.
Agregar código del lado del cliente
Cuando corresponda, también puede instruir a sus usuarios sobre cómo agregar código del lado del cliente para activar su extensión. Debe dirigir a los usuarios a la documentación oficial de las API que necesitarán utilizar. También puede incluir aplicaciones de muestra o muestras de clientes compiladas para ayudar a sus usuarios a integrar la extensión en su aplicación (consulte la extensión Distributed Counter para ver un ejemplo).
Para que sus usuarios puedan activar una función activada por solicitud HTTP (y, por lo tanto, la extensión), debe proporcionarles el nombre de la función implementada o su URL .
El nombre de la función implementada final no es el mismo que el name que especificó en el objeto de recurso de la función dentro de extension.yaml . Para dar cabida a varias instalaciones de la misma extensión en un proyecto, Firebase cambia el nombre de la función a este formato:ext- extension-instance-id - function-name .
Las siguientes viñetas son texto repetitivo sugerido para incluir en el archivo POSTINSTALL de su extensión. Después de la instalación, Firebase console muestra el contenido del archivo POSTINSTALL y completa estas referencias con los valores configurados reales para la instancia instalada. Por ejemplo, si definió una función denominada yourFunction , podría incluir lo siguiente (según corresponda):
Para funciones HTTP
onRequestTo trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.Para funciones HTTP invocables (
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}`**.
Escribir un archivo CHANGELOG
¿Qué contenido hay en este archivo?
Cada extensión debe tener un archivo CHANGELOG.md que documente los cambios incluidos en cada nueva versión de su extensión que publique. Coloque cada versión bajo un encabezado de nivel 2 ( ## ); de lo contrario, puedes usar cualquier formato de Markdown que desees.
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 CLI, cuando los usuarios actualizan a nuevas versiones de su extensión. Firebase console y CLI muestran solo los cambios que entrarían en vigor si el usuario completara la actualización.
- El repositorio de código fuente de su extensión (dentro del directorio de extensiones).