모든 확장 프로그램에는 사용자에게 확장 프로그램의 기능과 사용 방법을 설명하는 문서가 있어야 합니다.
최소한의 필수 문서는 다음과 같은 세 가지 마크다운 파일로 이루어져 있습니다.
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
또한 다음 항목의 생성을 고려해야 합니다.
- 확장 프로그램의 공개 저장소용
README파일 - 자체 웹사이트에 게시되었으며
PREINSTALL.md에 연결된 긴 형식의 튜토리얼, 가이드, 참조
몇 가지 권장사항과 일반적인 문구 및 구조를 알아보려면 공식 Firebase 확장 프로그램에서 사용할 수 있는 파일을 검토하는 것이 좋습니다.
README 만들기
확장 프로그램 디렉터리는 선택적으로 README를 포함할 수 있습니다. firebase ext:dev:init 명령어는 자동으로 생성되지 않습니다.
하지만 Firebase CLI는 extension.yaml 파일과 PREINSTALL.md 파일에서 가져온 콘텐츠가 포함된 README 파일을 자동으로 생성하기 위해 다음과 같은 편의 명령어를 지원합니다.
firebase ext:info ./path/to/extension --markdown > README.md
공식 Firebase 확장 프로그램의 모든 README 파일은 이 명령어를 사용하여 생성됩니다.
설치 정보 추가
README를 작성하거나 생성한 후 README에 설치 정보를 추가합니다. 다음 스니펫을 템플릿으로 사용할 수 있습니다.
--- ## 🧩 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) ---
PREINSTALL 파일 쓰기
PREINSTALL 파일은 확장 프로그램의 개요로, 일종의 '마케팅' 페이지입니다.
이 파일에는 어떤 콘텐츠가 있나요?
- 확장 프로그램의 기능에 대한 포괄적인 설명
- 데이터베이스 설정 또는 Google 이외의 서비스에 대한 액세스 권한과 같은 기본 요건 목록(예시)
- 설치 전 태스크 및 안내에 대한 간략한 설명
- 설치 후 태스크에 대한 간략한 설명(예시)(자세한 안내는
POSTINSTALL참조) - 결제의 영향에 대한 간략한 설명(상용구 텍스트로 시작)
이 콘텐츠는 어디에 표시되나요?
Firebase console">의 설치 전 콘텐츠 이미지
Firebase console">의 설치 전 큰 콘텐츠 이미지
- 확장 프로그램 페이지(extensions.dev)
- 확장 프로그램의 소스 코드 저장소(확장 프로그램 디렉터리 내부)
- 확장 프로그램의 README(Firebase CLI
--markdown > README.md
PREINSTALL 파일은 확장 프로그램의 매개변수 값에 액세스할 수 없으므로 매개변수 참조가 실제 값과 함께 렌더링되지 않아야 합니다.
권장사항은 무엇인가요?
- 가능한 경우
PREINSTALL파일의 전체 콘텐츠를 한 페이지에 유지 - 확장 프로그램을 설치하기 전에 최종 사용자가 반드시 알아야 하는 세부정보 수준 제공
POSTINSTALL파일 또는 기타 보조 파일에 자세한 안내 입력- 확장 프로그램을 지원하는 다른 도구나 스크립트를 제공하는지 간략히 언급
유용한 PREINSTALL 상용구 텍스트
다음 상용구 텍스트는 가능한 한 많이 사용하는 것이 좋습니다(확장 프로그램에 해당하는 경우). 몇 가지 예를 제공했지만 가장 중요한 점은 Google 청구 서비스 및 Google 이외의 청구 서비스를 모두 표시하는 것입니다.
다음 리소스를 사용하여 올바른 제품 가격 책정 세부정보를 확인할 수 있습니다.
모든 확장 프로그램에 대해 사용자가 결제의 의미를 잘 이해할 수 있도록 다음 섹션을 포함하세요.
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>.
POSTINSTALL 파일 쓰기
POSTINSTALL 파일은 확장 프로그램의 자세한 설치 후 안내 페이지입니다.
이 파일에는 어떤 콘텐츠가 있나요?
- Firebase 보안 규칙 설정 또는 클라이언트 측 코드 추가와 같은 설치 후 필수 태스크에 대한 자세한 안내(예시)
- 설치된 확장 프로그램을 즉시 사용해 보는 방법에 대한 일반적인 지침(예: '콘솔로 이동한 후 수행')
- 확장 프로그램(특히 HTTP 요청에 의해 트리거되는 확장 프로그램)을 트리거하는 방법에 대한 기본 정보
- 설치된 확장 프로그램을 모니터링하는 방법에 대한 간략한 안내(상용구 텍스트로 시작)
이 콘텐츠는 어디에 표시되나요?
Firebase console">의 설치 후 콘텐츠 이미지
Firebase console">의 설치 후 큰 콘텐츠 이미지
사용자가 확장 프로그램을 설치한 후 Firebase 콘솔(설치된 확장 프로그램의 세부정보 카드)
- 실제 프로젝트에 확장 프로그램을 설치하여
POSTINSTALL콘텐츠의 표시를 검토하세요.
- 실제 프로젝트에 확장 프로그램을 설치하여
확장 프로그램의 소스 코드 저장소(확장 프로그램 디렉터리 내부)
POSTINSTALL 파일은 확장 프로그램의 매개변수 값과 여러 함수 관련 변수에 액세스할 수 있습니다. Firebase 콘솔에 POSTINSTALL 콘텐츠가 표시되면 매개변수 또는 변수 참조 대신 실제 값이 표시됩니다. POSTINSTALL 파일에서 매개변수 및 변수를 참조하는 방법을 아래에서 자세히 알아보세요.
권장사항은 무엇인가요?
POSTINSTALL파일의 전체 콘텐츠를 간결하되, 알아보기 쉽게 유지합니다.- 제목을 사용하여 콘텐츠를 개별 태스크 또는 개념으로 구분합니다.
- 웹사이트(예) 또는 확장 프로그램 저장소 내 추가 마크다운 파일(예)에 특정 워크플로 또는 태스크에 대한 자세한 안내를 게시합니다.
- 사용자가 안내의 맥락에서 구성된 값을 볼 수 있도록 매개변수 및 함수 관련 변수를 참조합니다.
매개변수 및 변수 참조
설치 후 Firebase 콘솔에 확장 프로그램의 POSTINSTALL 파일 콘텐츠가 표시됩니다. POSTINSTALL 파일의 매개변수와 함수 관련 변수(아래 표 참조)를 참조하는 경우 콘솔은 이러한 참조를 설치된 인스턴스의 실제 값으로 채웁니다.
다음 구문을 사용하여 POSTINSTALL 파일에 구성된 매개변수 값에 액세스합니다. ${param:PARAMETER_NAME}
POSTINSTALL 파일에서만 다음 함수 관련 변수를 참조할 수도 있습니다. Firebase는 설치 후 사용자에게 보다 쉽게 안내를 제공할 수 있도록 이러한 변수를 지원합니다. 이 변수의 값은 설치 후에 사용할 수 있으므로 POSTINSTALL 파일에서만 사용할 수 있습니다.
이 표에서 function-name은 extension.yaml 내 함수 리소스 객체의 name 필드 값입니다.
| 함수 관련 변수에 대한 참조 | 설명 | 변수 값(확장 프로그램 설치 후 Firebase에서 자동으로 입력) |
|---|---|---|
${function:function-name.location}
|
||
| 함수가 배포된 위치 |
값 예시:us-central1
|
|
${function:function-name.name}
|
||
| 확장 프로그램의 인스턴스 ID를 포함하는,배포된 최종 함수의 이름 |
일반적인 형식:
값 예시: |
|
${function:function-name.url}
(HTTP 함수에만 적용됨)
|
||
| 클라이언트 코드가 HTTP 요청을 수행할 수 있는, 배포된 최종 함수의 URL |
일반적인 형식:
값 예시: |
|
유용한 POSTINSTALL 상용구 텍스트
다음 상용구 텍스트는 가능한 한 많이 사용하는 것이 좋습니다(확장 프로그램에 해당하는 경우).
모든 확장 프로그램에 대해 사용자가 설치된 확장 프로그램을 모니터링할 수 있도록 다음 섹션을 포함합니다.
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.
확장 프로그램을 트리거하는 방법 문서화
확장 프로그램의 사용자 문서에 확장 프로그램을 트리거하는 방법을 설명해야 합니다. 이 안내는 필요한 만큼 자세히 설명할 수 있지만 POSTINSTALL 파일 작성 권장사항을 참고하세요.
이러한 안내를 제공하는 방법에 대해 알아보려면 아래에서 확장 프로그램에 적용되는 섹션을 펼치세요.
백그라운드 이벤트에 의해 트리거되는 확장 프로그램
사용자는 관련된 제품에 따라 다양한 방식으로 백그라운드 이벤트에 의해 트리거되는 확장 프로그램을 트리거할 수 있습니다.
콘솔에서 직접 변경
특히 확장 프로그램을 처음 테스트할 때 Firebase 콘솔에서 직접 확장 프로그램을 트리거하는 변경 작업을 수행하도록 사용자에게 안내할 수 있습니다. 예를 들어 새 Firebase Authentication 사용자가 생성될 때마다 확장 프로그램에서 새 Cloud Firestore 문서를 만든다고 가정해 보겠습니다. 콘솔에서 새 Authentication 사용자를 수동으로 추가하여 확장 프로그램의 설치된 인스턴스를 테스트하도록 사용자에게 안내할 수 있습니다. 그런 다음 콘솔의 Cloud Firestore 섹션에서 생성된 새 문서를 볼 수 있습니다.
클라이언트 측 코드 추가
해당되는 경우 사용자에게 클라이언트 측 코드를 추가하여 확장 프로그램을 트리거하는 방법을 안내할 수도 있습니다. 사용자가 사용해야 하는 API의 공식 문서로 사용자를 안내해야 합니다. 또한 사용자가 확장 프로그램을 앱에 통합할 수 있도록 샘플 앱 또는 컴파일된 클라이언트 샘플을 포함할 수도 있습니다(예시를 보려면 분산 카운터 확장 프로그램 참조).
HTTP 요청에 의해 트리거되는 확장 프로그램
사용자가 HTTP 요청에 의해 트리거되는 함수(및 확장 프로그램)를 트리거할 수 있도록 배포된 함수의 이름 또는 URL을 제공해야 합니다.
마지막으로 배포된 함수의 이름은 extension.yaml 내의 함수 리소스 객체에 지정한 name과 다릅니다. Firebase는 동일한 확장 프로그램을 한 프로젝트에 여러 번 설치할 수 있도록 함수의 이름을 ext-extension-instance-id-function-name
확장 프로그램의 POSTINSTALL 파일에 포함하면 좋은 상용구 텍스트는 다음과 같습니다. 설치 후 Firebase 콘솔은 POSTINSTALL 파일의 콘텐츠를 표시하고 이러한 참조를 설치된 인스턴스에 대해 구성된 실제 값으로 채웁니다. 예를 들어 yourFunction이라는 함수를 정의한 경우 다음을 포함할 수 있습니다(해당하는 경우).
HTTP
onRequest함수To trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.HTTP 호출 가능(
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}`**.
CHANGELOG 파일 작성
이 파일에는 어떤 콘텐츠가 있나요?
모든 확장 프로그램에는 게시하는 각 확장 프로그램의 새 버전에 포함된 변경사항을 문서화하는 CHANGELOG.md 파일이 있어야 합니다. 각 버전을 레벨 2 헤더(##) 아래에 배치합니다. 그렇지 않으면 원하는 마크다운 형식을 사용할 수 있습니다.
다음 예는 공식 확장 프로그램 중 하나에서 발췌한 것입니다.
## 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.
이 콘텐츠는 어디에 표시되나요?
- 사용자가 새 버전의 확장 프로그램으로 업그레이드하는 경우 Firebase 콘솔 및 CLI에 표시됩니다. Firebase 콘솔 및 CLI에는 사용자가 업그레이드를 완료할 경우에 적용되는 변경사항만 표시됩니다.
- 확장 프로그램의 소스 코드 저장소(확장 프로그램 디렉터리 내부)