Uzantınız için kullanıcı belgeleri oluşturun

Her uzantının, kullanıcılara uzantının ne yaptığını ve nasıl kullanılacağını öğreten belgeleri olması gerekir.

Minimum, gerekli belge, bu üç işaretleme dosyasından oluşan settir:

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

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

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

Bazı en iyi uygulamaları ve yaygın ifadeleri ve yapıyı öğrenmek için resmi Firebase uzantılarında bulunan dosyaları incelemenizi öneririz.

README oluşturma

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

Ancak 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ına ait tüm README dosyaları bu komut kullanılarak oluşturulur.

Kurulum bilgilerini ekleyin

Bir README yazdıktan veya oluşturduktan sonra, ona kurulum bilgilerini ekleyin. Aşağıdaki pasajı ş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ı yazma

PREINSTALL dosyası, uzantınızın genel görünümüdür ve bir tür "pazarlama" sayfasıdır.

Bu dosyada hangi içerik var?

• Uzantınızın işlevselliğinin kapsamlı açıklaması
• Veritabanı kurulumu veya Google dışı bir hizmete erişim gibi önkoşulların listesi ( örnek )
• Kurulum öncesi görevlerin ve talimatlarının kısa açıklaması
• Kurulum sonrası görevlerin kısa açıklaması ( örnek ) (ayrıntılı talimatlar POSTINSTALL bulunmaktadır)
• Faturalandırmayla ilgili tüm sonuçların kısa açıklaması ( ortak metinle başlayın)

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

İçeriği Firebase konsoluna önceden yükleyin

• Extensions.dev'deki uzantı sayfasında.
• Uzantınız için kaynak kodu deponuz (uzantı dizininin içinde)
• Uzantının README'sinin bir parçası olarak (Firebase CLI'yi kullanıyorsanız --markdown > README.md işareti )

PREINSTALL dosyaları uzantının parametre değerlerine erişemez; dolayısıyla parametre referanslarının gerçek değerlerle oluşturulmasını beklememelisiniz.

En iyi uygulamalardan bazıları nelerdir?

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

Faydalı PREINSTALL ortak metin metni

Uzantınıza uygun olarak aşağıdaki ortak metinden mümkün olduğunca fazlasını kullanmanızı öneririz. Bazı örnekler verdik ancak en önemli nokta Google'ın ve Google'ın faturalandırmadığı tüm hizmetlerin listelendiğinden emin olmaktır.

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ış

Kullanıcılarınızın faturalandırmayla ilgili sonuçları anlamasına yardımcı olmak için tüm uzantılara 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 hangi içerik var?

• Firebase güvenlik kurallarını ayarlama veya istemci tarafı kodu ekleme gibi kurulum sonrası gerekli tüm görevlere ilişkin ayrıntılı talimatlar ( örnek )
• Yüklü uzantıyı hemen nasıl deneyeceğinize ilişkin genel talimatlar (örneğin, "konsola gidin, sonra bunu yapın")
• Özellikle HTTP isteğiyle tetiklenen uzantılar için uzantının nasıl tetikleneceğine ilişkin temel bilgiler
• Kurulu uzantının nasıl izleneceği ile ilgili kısa talimatlar ( ortak metinle başlayın)

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

Firebase konsolunda yükleme sonrası içerik

• Bir 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ü incelediğinizden emin olun.

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

POSTINSTALL dosyaları, uzantının 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örüntülenir. POSTINSTALL dosyanızdaki parametrelere ve değişkenlere nasıl başvuruda bulunacağınız hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

En iyi uygulamalardan bazıları nelerdir?

• POSTINSTALL dosyasının tüm içeriğini kısa ama açıklayıcı tutun.
• Farklı görevleri veya kavramları parçalara ayırmak için başlıkları kullanarak içeriği bölümlere ayırın.
• Belirli bir iş akışı veya göreve ilişkin ayrıntılı talimatları web sitenizde ( örnek ) veya uzantı deposundaki ek işaretleme dosyalarında ( örnek ) yayınlamayı düşünün.
• Kullanıcının yapılandırılmış değerlerini talimatlar bağlamında görebilmesi için referans parametreleri ve fonksiyonla ilgili değişkenler

Parametrelere ve değişkenlere referans verme

Kurulumdan sonra Firebase konsolu, uzantının POSTINSTALL dosyasının içeriğini görüntüler. POSTINSTALL dosyanızda parametrelere ve işlevle ilgili değişkenlere (aşağıdaki tabloya bakın) referans verirseniz, konsol bu referansları kurulu örneğin gerçek değerleri ile doldurur.

İpucu: Uzun olabilen değerler için (veritabanı yolu veya işlev URL'si gibi), cümlelerin ve bölümlerin sonunda parametreye veya değişkene başvurun. Bu en iyi uygulama, POSTINSTALL dosyasının içeriği gerçek değerlerle oluşturulduğunda Firebase konsolunda cümlelerin okunmasını kolaylaştırır.

Aşağıdaki sözdizimini 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 da başvurabilirsiniz. Firebase bu değişkenleri destekler, böylece kurulum sonrasında kullanıcılarınıza daha kolay rehberlik sağlayabilirsiniz. Bu değişkenlerin değerleri kurulum sonrasına kadar mevcut olmadığından bunlar yalnızca POSTINSTALL dosyasında kullanılabilir.

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

Fonksiyonla ilgili değişken için referans	Tanım	Değişken değer (uzantı kurulumundan 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, son dağıtılan işlevin adı	Genelleştirilmiş format: 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 yapabileceği son konuşlandırılan işlevin URL'si	Genelleştirilmiş format: 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

Yararlı POSTINSTALL ortak metin metni

Uzantınıza uygun olarak aşağıdaki ortak metinden mümkün olduğunca fazlasını kullanmanızı öneririz.

Kullanıcılarınızın yüklü uzantıları izlemelerine yardımcı olmak için tüm uzantılara 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.

Bir uzantının nasıl tetikleneceğini belgeleme

Uzantınızın kullanıcı belgelerinde, 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ı yazmaya yönelik en iyi uygulamaları aklınızda bulundurun. Bu talimatların nasıl sağlanacağına ilişkin rehberlik için aşağıdaki uzantınız için geçerli olan 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.

Değişiklikleri doğrudan konsolda yapın

Kullanıcılarınıza, özellikle uzantınızı ilk test etmeleri için doğrudan Firebase konsolunda uzantıyı tetikleyen değişiklikler yapma talimatı verebilirsiniz. Örneğin, yeni bir Firebase Authentication kullanıcısı oluşturulduğunda uzantınızın yeni bir Cloud Firestore belgesi oluşturduğunu varsayalım. Konsola manuel olarak yeni bir Kimlik Doğrulama kullanıcısı ekleyerek kullanıcılarınıza uzantınızın yüklü bir örneğini test etmeleri talimatını verebilirsiniz. Daha sonra konsolun Cloud Firestore bölümünde oluşturulan yeni belgeyi gözlemleyebilirler.

İstemci tarafı kodu ekle

Mümkün olduğunda, 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önlendirmelisiniz. 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).

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.

Son konuşlandırılan işlevin adı, işlevin extension.yaml içindeki kaynak nesnesinde belirttiğiniz name aynı değil. Bir projede aynı uzantının birden fazla kurulumuna uyum sağlamak için Firebase, işlevi şu biçimde yeniden adlandırır: ext- extension-instance-id - function-name .

Aşağıdaki madde işaretleri, uzantınızın POSTINSTALL dosyasına dahil edilmesi önerilen ortak metindir. Kurulumdan sonra Firebase konsolu POSTINSTALL dosyasının içeriğini görüntüler ve bu referansları kurulu örnek için gerçek yapılandırılmış değerlerle doldurur. Örneğin, yourFunction adında bir işlev tanımladıysanız aşağıdakileri (uygun olduğu şekilde) ekleyebilirsiniz:

• 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ı kullanabilmeleri için, uzantı için dağıtılan işlevleri herkesin erişimine açık hale getirmeleri gerekir. Kullanıcılarınıza sağlamanız gereken ayrıntılı talimatlar yukarıdaki ortak metin örneklerinde bulunmaktadır.

CHANGELOG dosyası yazma

Bu dosyada hangi içerik var?

Her uzantının, yayınladığınız uzantının her yeni sürümünde yer alan değişiklikleri belgeleyen bir CHANGELOG.md dosyası olması gerekir. Her sürümü 2. düzey başlığın ( ## ) altına yerleştirin; aksi takdirde istediğiniz Markdown formatını kullanabilirsiniz.

Aşağıdaki örnek resmi uzantılardan birinden 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österiliyor?

• Firebase konsolunda ve CLI'de, kullanıcılar uzantınızın yeni sürümlerine geçtiğinde. Firebase konsolu ve CLI, yalnızca kullanıcının yükseltmeyi tamamlaması durumunda geçerli olacak değişiklikleri görüntüler.
• Uzantınızın kaynak kodu deposu (uzantı dizininin içinde).