Uzantınız için kullanıcı dokümanları oluşturun

Her uzantının, kullanıcılara uzantının ne işe yaradığını ve nasıl kullanılacağını öğreten dokümanları olmalıdır.

Gerekli minimum dokümanlar, aşağıdaki üç Markdown dosyasından oluşur:

  • PREINSTALL.md
  • POSTINSTALL.md
  • CHANGELOG.md

Ayrıca şunları da üretebilirsiniz:

  • Uzantıların herkese açık deposu için README dosyası.
  • Kendi web sitenizde yayınlanan ve PREINSTALL.md'ünüze bağlı uzun eğitici içerikler, kılavuzlar ve referanslar

En iyi uygulamalar, yaygın ifade ve yapıları öğrenmek için resmi Firebase uzantılarıyla kullanılabilen dosyaları incelemenizi öneririz.

README dosyası oluşturma

Uzantı dizininizde isteğe bağlı olarak bir README dosyası bulunabilir. firebase ext:dev:init komutunun sizin için otomatik olarak bir tane oluşturmadığını unutmayın.

Bununla birlikte, Firebase CLI, extension.yaml dosyanızdan ve PREINSTALL.md dosyanızdan alınan içeriği içeren bir README dosyasını otomatik olarak oluşturmak için aşağıdaki kolaylık komutunu destekler:

firebase ext:info ./path/to/extension --markdown > README.md

Resmi Firebase uzantılarının tüm README dosyaları bu komut kullanılarak oluşturulur.

Kurulum bilgileri ekleme

README dosyasını yazdıktan veya oluşturduktan sonra yükleme bilgilerini ekleyin. Şablon olarak aşağıdaki snippet'i kullanabilirsiniz:

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][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 dosyası yazma

PREINSTALL dosyası, uzantınıza genel bakış sunan bir tür "pazarlama" sayfasıdır.

Bu dosyada ne tür bir içerik var?

  • Uzantı işlevinizin kapsamlı açıklaması
  • Veritabanı kurulumu veya Google dışı bir hizmete erişim gibi ön koşulların listesi (örnek)
  • Kurulum öncesi görevlerin ve talimatlarının kısa açıklaması
  • Yükleme sonrası görevlerin kısa açıklaması (örnek) (ayrıntılı talimatlar POSTINSTALL bölümüne eklenir)
  • Faturalandırmayla ilgili sonuçların kısa açıklaması (standart metin ile başlayın)

Bu içerik kullanıcıya nerede gösteriliyor?

<span class=Firebase konsolu">
Firebase konsoluna içerik ön yükleme

<span class=Firebase Konsolu">

PREINSTALL dosyaları, uzantının parametre değerlerine erişemez. Bu nedenle, parametre referanslarının gerçek değerlerle oluşturulmasını bekleyemezsiniz.

En iyi uygulamalardan bazıları nelerdir?

  • Mümkünse PREINSTALL dosyasının tüm içeriğini bir sayfanın altında tutun
  • Nihai kullanıcının uzantıyı yüklemeden önce kesinlikle bilmesi gereken ayrıntı düzeyini sağlayın
  • Ayrıntılı talimatları POSTINSTALL dosyasına veya diğer ek dosyalara ekleyin
  • Uzantı için başka araçlar veya komut dosyaları sağlayıp sağlamadığınızı kısaca belirtin

Eklentiniz için geçerli olduğunda aşağıdaki standart metnin mümkün olduğunca fazlasını kullanmanızı öneririz. Bazı örnekler verdik ancak en önemli nokta, Google ve Google dışı faturalandırılan tüm hizmetlerin listelenmesini sağlamaktır.

Doğru ürün fiyatlandırması ayrıntılarını bulmak için aşağıdaki kaynakları kullanabilirsiniz:

Tüm uzantılarda, kullanıcılarınızın faturalandırmayla ilgili sonuçları anlamasına yardımcı olmak için bu bölümü ekleyin:

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 dosyası yazma

POSTINSTALL dosyası, uzantınızın ayrıntılı kurulum sonrası talimat sayfasıdır.

Bu dosyada ne tür bir içerik var?

  • Firebase güvenlik kurallarını ayarlama veya istemci tarafı kod ekleme gibi zorunlu kurulum sonrası görevler için ayrıntılı talimatlar (örnek)
  • Yüklenen uzantıyı hemen denemeye yönelik genel talimatlar (ör. "Konsola gidin ve bunu yapın")
  • Özellikle HTTP isteğiyle tetiklenen uzantılar için uzantının nasıl tetikleneceğiyle ilgili temel bilgiler
  • Yüklenen uzantının nasıl izleneceğine dair kısa talimatlar (standart metin ile başlayın)

Bu içerik kullanıcıya nerede gösteriliyor?

<span class=Firebase konsolu">
Firebase konsolunda yükleme sonrası içerik

<span class=Firebase Konsolu">

  • Kullanıcılar uzantınızı yükledikten sonra Firebase konsolunda (yüklü uzantının ayrıntı kartında)

  • Uzantınıza ait kaynak kod deponuz (uzantı dizininde)

POSTINSTALL dosyaları, uzantı için parametre değerlerine ve işlevle ilgili çeşitli değişkenlere erişebilir. POSTINSTALL içeriği Firebase konsolunda görüntülendiğinde parametre veya değişken referansları yerine gerçek değerler gösterilir. POSTINSTALL dosyanızda parametrelere ve değişkenlere referans verme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

En iyi uygulamalardan bazıları nelerdir?

  • POSTINSTALL dosyasının tüm içeriği kısa ve öz, ancak açıklayıcı olmalıdır.
  • Farklı görevleri veya kavramları ayırmak için başlıkları kullanarak içeriği bölümlere ayırın.
  • Belirli bir iş akışı veya görevle ilgili ayrıntılı talimatları web sitenizde (örnek) ya da uzantı deposundaki ek Markdown dosyalarında (örnek) yayınlayabilirsiniz.
  • Kullanıcının yapılandırılmış değerleri talimatlar bağlamında görebilmesi için parametrelere ve işlevle ilgili değişkenlere referans verin.

Parametrelere ve değişkenlere referans verme

Yükleme işleminden sonra Firebase konsolu, uzantının POSTINSTALL dosyasının içeriğini gösterir. POSTINSTALL dosyanızda parametrelere ve işlevle ilgili değişkenlere (aşağıdaki tabloya bakın) referans verirseniz konsol bu referansları, yüklü örneğin gerçek değerleriyle doldurur.

Aşağıdaki söz dizimini kullanarak POSTINSTALL dosyasındaki yapılandırılmış parametre değerlerine erişin: ${param:PARAMETER_NAME}

Aşağıdaki işlevle ilgili değişkenlere yalnızca POSTINSTALL dosyanızda de referans verebilirsiniz. Firebase, yükleme sonrası kullanıcılarınıza daha kolay yol gösterebilmeniz için bu değişkenleri destekler. Bu değişkenlerin değerleri yükleme işleminden sonra kullanılabildiği için yalnızca POSTINSTALL dosyasında kullanılabilirler.

Bu tabloda function-name, işlevin extension.yaml içindeki kaynak nesnesinde bulunan name alanının değeridir.

İşlevle ilgili değişken için referans Açıklama Değişken değer (uzantı yüklendikten sonra Firebase tarafından otomatik olarak doldurulur)
${function:function-name.location}
İşlevin dağıtıldığı konum Örnek değer:
us-central1
${function:function-name.name}
Uzantının örnek kimliğini içeren nihai yayılmış işlevin adı

Genelleştirilmiş biçim:
ext-extension-instance-id-function-name

Örnek değer:
ext-my-awesome-extension-6m31-yourFunctionName

${function:function-name.url} (yalnızca HTTP işlevleri için geçerlidir)
Müşteri kodunun HTTP isteği gönderebileceği nihai dağıtılmış işlevin URL'si

Genelleştirilmiş biçim:
https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function

Örnek değer:
https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Eklentiniz için geçerli olduğunda aşağıdaki standart metnin mümkün olduğunca fazlasını kullanmanızı öneririz.

Tüm uzantılarda, kullanıcılarınızın yüklü uzantılarını izlemelerine yardımcı olmak için aşağıdaki bölümü ekleyin:

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.

Uzantıların nasıl tetikleneceğini belgeleme

Uzantı kullanıcı dokümanlarınızda, kullanıcılarınıza uzantınızı nasıl tetikleyecekleri konusunda talimat vermeniz gerekir. Bu talimatlar, gerekli olduğunu düşündüğünüz kadar ayrıntılı olabilir ancak POSTINSTALL dosyası yazmayla ilgili en iyi uygulamaları göz önünde bulundurun. Bu talimatları nasıl sağlayacağınızla ilgili yardım için aşağıdaki, uzantınızla ilgili bölümü genişletin.

Kullanıcılarınız, ilgili ürünlere bağlı olarak arka planda etkinlik tetikleyici uzantıları çeşitli şekillerde tetikleyebilir.

Doğrudan konsolda değişiklik yapma

Kullanıcılarınıza, özellikle uzantınızı ilk kez test ederken uzantıyı tetikleyen değişiklikleri doğrudan Firebase konsolunda yapmalarını söyleyebilirsiniz. Örneğin, uzantınızın yeni bir Firebase Authentication kullanıcı oluşturulduğunda yeni bir Cloud Firestore dokümanı oluşturduğunu varsayalım. Konsolda manuel olarak yeni bir Authentication kullanıcı ekleyerek kullanıcılarınıza uzantınızın yüklü bir örneğini test etmelerini söyleyebilirsiniz. Ardından, konsolun Cloud Firestore bölümünde oluşturulan yeni belgeyi gözlemleyebilirler.

İstemci tarafı kod ekleme

Uygun olduğunda, kullanıcılarınıza uzantınızı tetiklemek için istemci tarafı kod ekleme konusunda talimat verebilirsiniz. Kullanıcıları, kullanmaları gereken API'lerin resmi belgelerine yönlendirmeniz gerekir. Kullanıcılarınızın uzantıyı uygulamalarına entegre etmesine yardımcı olmak için örnek uygulamalar veya derlenmiş istemci örnekleri de ekleyebilirsiniz (örnek için Dağıtılmış Sayaç uzantısına bakın).

Kullanıcılarınızın HTTP isteğiyle tetiklenen bir işlevi (ve dolayısıyla uzantıyı) tetikleyebilmesi için onlara dağıtılan işlevin adını veya URL'sini sağlamanız gerekir.

Son dağıtılan işlevin adı, extension.yaml içindeki işlevin kaynak nesnesinde belirttiğiniz name ile aynı değil. Firebase, bir projede aynı uzantının birden çok kez yüklenmesini sağlamak için işlevi şu biçimde yeniden adlandırır: ext-extension-instance-id-function-name.

Aşağıdaki maddeler, uzantınızın POSTINSTALL dosyasına eklenecek standart metindir. Yüklemeden sonra Firebase konsolu, POSTINSTALL dosyasının içeriğini gösterir ve bu referansları, yüklü örnek için yapılandırılmış gerçek değerlerle doldurur. Örneğin, yourFunction adlı bir işlev tanımladıysanız aşağıdakileri ekleyebilirsiniz (geçerli olduğunda):

  • HTTP onRequest işlevleri için

    To trigger this extension, make a request to or visit the following URL:
**`${function:yourFunction.url}`**.

  • HTTP çağrılabilir (onCall) işlevler için

    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 dosyası yazma

Bu dosyada ne tür bir içerik var?

Her uzantının, yayınladığınız uzantınızın her yeni sürümünde yer alan değişiklikleri belgeleyen bir CHANGELOG.md dosyası olmalıdır. Her sürümü 2. düzey bir başlığın (##) altına koyun. Dilerseniz istediğiniz Markdown biçimlendirmesini kullanabilirsiniz.

Aşağıdaki örnek, resmi uzantılardan birinden alınmıştır:

## 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.

Bu içerik kullanıcıya nerede gösteriliyor?

  • Firebase konsolunda ve CLI'de, kullanıcılar uzantınızın yeni sürümlerine yükselttiğinde. Firebase Konsolu ve CLI, yalnızca kullanıcı yükseltmeyi tamamlarsa geçerli olacak değişiklikleri gösterir.
  • Uzantınızın kaynak kodu deposu (uzantı dizininde).