모든 확장 프로그램에는 사용자에게 확장 프로그램의 기능과 사용 방법을 설명하는 문서가 있어야 합니다.
최소한의 필수 문서는 다음과 같은 세 가지 마크다운 파일로 이루어져 있습니다.
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
또한 다음 항목의 생성을 고려해야 합니다.
- 확장 프로그램의 공개 저장소용
README파일 - 자체 웹사이트에 게시되었으며
PREINSTALL.md에 연결된 긴 형식의 튜토리얼, 가이드, 참조
몇 가지 권장사항과 일반적인 문구 및 구조를 알아보려면 공식 Firebase Extensions에서 제공하는 파일을 검토하는 것이 좋습니다.
README 만들기
확장 프로그램 디렉터리는 선택적으로 README를 포함할 수 있습니다. firebase ext:dev:init 명령어는 자동으로 생성되지 않습니다.
하지만 Firebase CLI는 extension.yaml 파일과 PREINSTALL.md 파일에서 가져온 콘텐츠가 포함된 README 파일을 자동으로 생성하기 위해 다음과 같은 편의 명령어를 지원합니다.
firebase ext:info ./path/to/extension --markdown > README.md
공식 Firebase Extensions의 모든 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: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) ---
PREINSTALL 파일 쓰기
PREINSTALL 파일은 확장 프로그램의 개요로, 일종의 '마케팅' 페이지입니다.
이 파일에는 어떤 콘텐츠가 있나요?
- 확장 프로그램의 기능에 대한 포괄적인 설명
- 데이터베이스 설정 또는 Google 이외의 서비스에 대한 액세스 권한과 같은 기본 요건 목록(예시)
- 설치 전 태스크 및 안내에 대한 간략한 설명
- 설치 후 태스크에 대한 간략한 설명(예시)(자세한 안내는
POSTINSTALL참조) - 결제의 영향에 대한 간략한 설명(상용구 텍스트로 시작)
이 콘텐츠는 어디에 표시되나요?
- 확장 프로그램 페이지(extensions.dev)
- 확장 프로그램의 소스 코드 저장소(확장 프로그램 디렉터리 내부)
- 확장 프로그램의 README(Firebase CLI
--markdown > README.md
PREINSTALL 파일은 확장 프로그램의 매개변수 값에 액세스할 수 없으므로 매개변수 참조가 실제 값과 함께 렌더링되지 않아야 합니다.
권장사항은 무엇인가요?
- 가능한 경우
PREINSTALL파일의 전체 콘텐츠를 한 페이지에 유지 - 확장 프로그램을 설치하기 전에 최종 사용자가 반드시 알아야 하는 세부정보 수준 제공
POSTINSTALL파일 또는 기타 보조 파일에 자세한 안내 입력- 확장 프로그램을 지원하는 다른 도구나 스크립트를 제공하는지 간략히 언급
POSTINSTALL 파일 쓰기
POSTINSTALL 파일은 확장 프로그램의 자세한 설치 후 안내 페이지입니다.
이 파일에는 어떤 콘텐츠가 있나요?
- Firebase 보안 규칙 설정 또는 클라이언트 측 코드 추가와 같은 설치 후 필수 태스크에 대한 자세한 안내(예시)
- 설치된 확장 프로그램을 즉시 사용해 보는 방법에 대한 일반적인 지침(예: '콘솔로 이동한 후 수행')
- 확장 프로그램(특히 HTTP 요청에 의해 트리거되는 확장 프로그램)을 트리거하는 방법에 대한 기본 정보
- 설치된 확장 프로그램을 모니터링하는 방법에 대한 간략한 안내(상용구 텍스트로 시작)
이 콘텐츠는 어디에 표시되나요?
사용자가 확장 프로그램을 설치한 후 Firebase Console의 설치된 확장 프로그램 세부정보 카드
- 실제 프로젝트에 확장 프로그램을 설치하여
POSTINSTALL콘텐츠의 표시 상태를 검토하세요.
- 실제 프로젝트에 확장 프로그램을 설치하여
확장 프로그램의 소스 코드 저장소(확장 프로그램 디렉터리 내부)
POSTINSTALL 파일은 확장 프로그램의 매개변수 값과 여러 함수 관련 변수에 액세스할 수 있습니다. Firebase Console에 POSTINSTALL 콘텐츠가 표시되면 매개변수 또는 변수 참조 대신 실제 값이 표시됩니다. POSTINSTALL 파일에서 매개변수 및 변수를 참조하는 방법을 아래에서 자세히 알아보세요.
권장사항은 무엇인가요?
POSTINSTALL파일의 전체 콘텐츠를 간결하되, 알아보기 쉽게 유지합니다.- 제목을 사용하여 콘텐츠를 개별 태스크 또는 개념으로 구분합니다.
- 웹사이트(예) 또는 확장 프로그램 저장소 내 추가 마크다운 파일(예)에 특정 워크플로 또는 태스크에 대한 자세한 안내를 게시합니다.
- 사용자가 안내의 맥락에서 구성된 값을 볼 수 있도록 매개변수 및 함수 관련 변수를 참조합니다.
매개변수 및 변수 참조
설치 후 Firebase Console에 확장 프로그램의 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 파일 작성 권장사항을 참고하세요.
이러한 안내를 제공하는 방법에 대해 알아보려면 아래에서 확장 프로그램에 적용되는 섹션을 펼치세요.
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 Console 및 CLI에 표시. Firebase Console 및 CLI에는 사용자가 업그레이드를 완료할 경우에 적용되는 변경사항만 표시됩니다.
- 확장 프로그램의 소스 코드 저장소(확장 프로그램 디렉터리 내부)