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 bir dokümanı olmalıdır.

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

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

Ayrıca şunları da üretmeyi düşünebilirsiniz:

• Uzantının herkese açık deposu için bir README dosyası.
• Kendi web sitenizde yayınlanan ve PREINSTALL.md sayfanızda bağlantısı verilen daha uzun eğitimler, kılavuzlar ve referanslar

En iyi uygulamalardan bazılarını, yaygın ifadeleri ve yapıyı öğrenmek için resmi Firebase uzantılarla sunulan dosyaları incelemenizi öneririz.

BENİOKU dosyası oluşturma

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

Ancak Firebase KSA, extension.yaml dosyanızdan ve PREINSTALL.md dosyanızdan alınan içeriği barındıran bir README dosyasını otomatik olarak üretmek için aşağıdaki kolaylık komutunu destekler:

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

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

Kurulum bilgileri ekleme

README dosyası yazdıktan veya oluşturduktan sonra yükleme bilgilerini ekleyin. Aşağıdaki snippet'i şablon olarak 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ı yazılıyor

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

Bu dosyada hangi içerikler var?

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

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

Firebase console">

Firebase konsolunda önceden yüklenmiş içerik

Firebase konsolu">

• extensions.dev adresindeki uzantı sayfasında.
• Uzantınızın kaynak kodu deposu (uzantı dizininin içinde)
• Uzantının README dosyasının bir parçası olarak (Firebase CLI --markdown > README.md işaretini kullanıyorsanız)

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

Bu durumda önerilen en iyi uygulamalara örnekler verebilir misiniz?

• Mümkünse PREINSTALL dosyasının tüm içeriğini bir sayfadan az tutun.
• Uzantıyı yüklemeden önce son kullanıcının mutlaka bilmesi gereken ayrıntıları sağlayın.
• Ayrıntılı talimatları POSTINSTALL dosyasına veya diğer ek dosyalara ekleyin.
• Uzantıyı desteklemek için başka araçlar veya komut dosyaları sağlıyorsanız kısaca bahsedin.

Faydalı PREINSTALL standart metin

Uzantınız için geçerli olduğu ölçüde, aşağıdaki şablon metnin mümkün olduğunca büyük bir kısmını kullanmanızı öneririz. Bazı örnekler verdik ancak en önemli nokta, Google tarafından faturalandırılan ve faturalandırılmayan tüm hizmetlerin listelenmesidir.

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

• Google Cloud ürün fiyat listesi
• Firebase fiyatlandırmasına genel bakış

Tüm uzantılar için, kullanıcılarınızın faturalandırmayla ilgili sonuçları anlamasına yardımcı olmak amacıyla 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ı yazılıyor

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

Bu dosyada hangi içerikler var?

• Firebase güvenlik kurallarını ayarlama veya istemci tarafı kodu ekleme gibi gerekli yükleme sonrası görevler için ayrıntılı talimatlar (örnek)
• Yüklenen uzantıyı hemen denemeyle ilgili genel talimatlar (ör. "Konsola gidin ve şunu yapın")
• Uzantının nasıl tetikleneceğiyle ilgili temel bilgiler (özellikle HTTP isteğiyle tetiklenen uzantılar için)
• Yüklü uzantının nasıl izleneceğine dair kısa talimatlar (standart metinle başlayın)

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

Firebase console">

Firebase konsolunda yükleme sonrası içerik

Firebase konsolu">

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

  • Uzantınızı gerçek bir projeye yükleyerek POSTINSTALL içeriğinin görünümünü inceleyin.

• Uzantınızın kaynak kodu deposu (uzantı dizininin içinde)

POSTINSTALL dosyaları, uzantıyla ilgili parametre değerlerine ve işleve bağlı çeşitli değişkenlere erişebilir. POSTINSTALL içeriği Firebase konsolunda gösterildiğinde, parametre veya değişken referansları yerine gerçek değerler gösterilir. POSTINSTALL dosyanızda parametre ve değişkenlere nasıl referans vereceğiniz hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

Bu durumda önerilen en iyi uygulamalara örnekler verebilir misiniz?

• POSTINSTALL dosyasının tüm içeriğini kısa ve öz, ancak açıklayıcı tutun.
• 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ğerlerini talimatlar bağlamında görmesi için referans parametreleri ve işlevle ilgili değişkenleri kullanın.

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.

İpucu: Uzun olabilecek değerler (ör. veritabanı yolu veya işlev URL'si) için cümlelerin ve bölümlerin sonunda parametreye ya da değişkene referans verin. Bu en iyi uygulama, POSTINSTALL dosyasının içeriği gerçek değerlerle oluşturulduğunda cümlelerin Firebase konsolunda daha kolay okunmasını sağlar.

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

Ayrıca, yalnızca POSTINSTALL dosyanızda işlevle ilgili aşağıdaki değişkenlere de başvurabilirsiniz. Firebase, yükleme sonrasında kullanıcılarınıza daha kolay rehberlik edebilmeniz için bu değişkenleri destekler. Bu değişkenlerin değerleri yükleme işleminden sonra kullanılabilir hale geldiğinden, değişkenler yalnızca POSTINSTALL dosyasında kullanılabilir.

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

İşlevle ilgili değişken için referans	Açıklama	Değişken değeri (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, dağıtılan son 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)
	İstemci kodunun HTTP istekleri gönderebileceği, dağıtılan nihai 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

Faydalı POSTINSTALL standart metin

Uzantınız için geçerli olduğu ölçüde, aşağıdaki şablon metnin mümkün olduğunca büyük bir kısmını kullanmanızı öneririz.

Tüm uzantılarda, kullanıcılarınızın yüklü uzantılarını izlemesine 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ınızın kullanıcı belgelerinde, kullanıcılarınıza uzantınızı nasıl tetikleyeceklerini açıklamanız 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ın nasıl sağlanacağıyla ilgili bilgi edinmek için uzantınızla ilgili aşağıdaki bölümü genişletin.

Arka planda etkinlikle tetiklenen uzantılar

Kullanıcılarınız, ilgili ürünlere bağlı olarak arka planda etkinlikle tetiklenen bir uzantıyı ç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 her yeni Firebase Authentication kullanıcısı oluşturulduğunda yeni bir Cloud Firestore belgesi oluşturduğunu varsayalım. Kullanıcılarınıza, konsolda manuel olarak yeni bir Authentication kullanıcısı ekleyerek 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 dokümanı inceleyebilirler.

İstemci tarafı kodu ekleme

Uygun durumlarda, kullanıcılarınıza uzantınızı tetiklemek için istemci tarafı kodunu nasıl ekleyecekleri konusunda da talimat verebilirsiniz. Kullanıcıları, kullanmaları gereken API'lerin resmi belgelerine yönlendirmeniz gerekir. Kullanıcılarınızın uzantıyı kendi uygulamalarına entegre etmelerine yardımcı olmak için örnek uygulamalar veya derlenmiş istemci örnekleri de ekleyebilirsiniz (örnek için Distributed Counter uzantısına bakın).

HTTP isteğiyle tetiklenen uzantılar

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.

Dağıtılan son işlevin adı, extension.yaml içindeki işlevin kaynak nesnesinde belirttiğiniz name ile aynı değildir. Firebase, bir projede aynı uzantının birden fazla yüklemesini barındırmak 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 eklemeniz için önerilen standart metinlerdir. Yükleme işleminden sonra Firebase konsolu, POSTINSTALL dosyasının içeriğini gösterir ve bu referansları, yüklenen örnek için yapılandırılmış gerçek değerlerle doldurur. Örneğin, yourFunction adında bir işlev tanımladıysanız aşağıdakileri ekleyebilirsiniz (uygun şekilde):

• 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şlevleri 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}`**.
  

Önemli: Kullanıcılarınızın HTTP isteğiyle tetiklenen bir uzantıyı kullanabilmesi için uzantı için dağıtılan işlevleri herkese açık hale getirmeleri gerekir. Kullanıcılarınıza vereceğiniz ayrıntılı talimatlar yukarıdaki standart metin örneklerinde yer almaktadır.

CHANGELOG dosyası yazma

Bu dosyada hangi içerikler var?

Her uzantıda, yayınladığınız her yeni sürümde yapılan değişiklikleri belgeleyen bir CHANGELOG.md dosyası bulunmalıdır. Her sürümü 2. düzey başlığın (##) altına yerleştirin. Bunun dışında istediğiniz Markdown biçimlendirmesini kullanabilirsiniz.

Aşağıdaki örnek, resmi uzantılardan birinden alınmış bir alıntıdı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österilir?

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