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

Her uzantının kullanıcılara uzantının ne olduğunu öğreten dokümanlara sahip olması gerekir. ve nasıl kullanılacağını inceleyeceğiz.

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

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

Ayrıca şunları da üretebilirsiniz:

• Uzantının herkese açık deposu için bir README dosyası.
• Kendi web sitenizde yayınlanan daha uzun eğitici içerikler, kılavuzlar ve referanslar PREINSTALL.md içinde bağlantı oluşturuldu.

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

BENİOKU METNİ oluşturuluyor

Uzantı dizininiz isteğe bağlı olarak bir BENİOKU dizini içerebilir. Lütfen firebase ext:dev:init komutu sizin için otomatik olarak bir kod oluşturmaz.

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

BENİOKU dosyası yazdıktan veya oluşturduktan sonra bu alana 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ı yazılıyor

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

Bu dosyada hangi içerik var?

• Uzantınızın işlevine dair kapsamlı açıklama
• Veritabanı kurulumu veya Google dışı bir hizmete erişim gibi ön koşulların listesi (örnek)
• Kurulum öncesi görevlerin kısa açıklaması ve talimatları
• Kurulum sonrası görevlerin kısa açıklaması (örnek) (ayrıntılı talimatlar POSTINSTALL içindedir)
• Faturalandırmayla ilgili sonuçların kısa açıklaması (standart metin ile başlayın)

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

Firebase konsolu">

Firebase konsoluna içerik ön yükleme

Firebase konsolu">

• extensions.dev adresindeki uzantının sayfasında.
• Uzantınıza ait kaynak kod deponuzdan (uzantı dizininde)
• Uzantının README dosyasında (Firebase CLI --markdown > README.md işaretini kullanıyorsanız)

PREINSTALL dosyaları, uzantının parametre değerlerine erişemediğinden parametre referanslarının gerçek değerlerle oluşturulmasını beklememelidir.

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 ek dosyalar
• Kampanyanızı destekleyecek başka araçlar veya komut dosyaları sağlayıp sağlamadığınızı kısaca uzantı

Faydalı PREINSTALL ortak metni

Aşağıdaki ortak metinlerden mümkün olduğunca çoğunu kullanmanızı öneririz: geçerli olur. 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:

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

Tüm uzantılarda, kullanıcılarınızın faturalandırmayla ilgili sonuçları anlamaları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 hangi 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 (örneğin, "Konsola gidin ve bunu yapın")
• Uzantının nasıl tetikleneceğiyle ilgili, özellikle de HTTP isteğiyle tetiklenen uzantılar
• Yüklü uzantının nasıl izleneceğine ilişkin kısa talimatlar ( ortak metin)

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

Firebase konsolu">

Firebase konsolunda yükleme sonrası içerik

Firebase Konsolu">

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

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

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

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 parametre yerine gerçek değerler görüntülenir referansları veya değişken referansları bulunmaktadır. 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ğini kısa ama açıklayıcı tutun.
• Farklı görevleri ayırmak için başlıklar kullanarak içeriği bölümlere ayırın bahsedeceğiz.
• Belirli bir web sitesi için ayrıntılı talimatlar yayınlayabilir web sitenizdeki iş akışı veya görev (örnek) veya uzantı deposundaki ek Markdown dosyalarında (örnek).
• 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 konsolunda uzantının POSTINSTALL dosyasına ekleyin. Parametrelere ve işlevle ilgili reklamlara başvuruyorsanız POSTINSTALL dosyanıza, aşağıdaki tabloya bakın, ardından konsola 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 parametreye veya değişkene cümlelerin ve bölümlerin sonundan referans verin. 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öz dizimini kullanarak POSTINSTALL dosyasında 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. Bunlar yalnızca POSTINSTALL dosyasında kullanılabilir, çünkü bu değişkenlerin değerleri yüklenene kadar kullanılamaz.

Bu tabloda function-name, name alanına işlevinin extension.yaml içindeki kaynak nesnesi.

İş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 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)
	İstemci kodunun dağıtılabileceği son dağıtılan işlevin URL'si HTTP isteklerinde bulunma	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 ortak metni

Aşağıdaki ortak metinlerden mümkün olduğunca çoğunu kullanmanızı öneririz: geçerli olur.

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ını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ın nasıl sağlanacağıyla ilgili yardım için aşağıdaki bölümü genişletin: geçerlidir.

Arka plan etkinliği tarafından tetiklenen uzantılar

Kullanıcılarınız arka plan etkinliği tarafından tetiklenen bir uzantıyı çeşitli şekillerde tetikleyebilir. değişiklik gösterir.

Doğrudan konsolda değişiklik yapma

Kullanıcılarınıza doğrudan Google Etiket Yöneticisi'nin Firebase konsolunu kullanın. Ö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ı resmi belgelere yönlendirmeniz gerekir. API'ları seçiyorlar. Ayrıca örnek uygulamalar veya entegre etmesine yardımcı olmak için, derlenen istemci örneklerinden (bkz. Dağıtılmış Sayaç uzantısı bakın).

HTTP isteğiyle tetiklenen uzantılar

Böylece kullanıcılarınız HTTP istek tarafından tetiklenen bir işlevi (ve dolayısıyla uzantısına sahip olduğunda, onlara dağıtılan işlevin name veya URL.

Dağıtılan nihai işlevin adı name extension.yaml içindeki işlevin kaynak nesnesinde belirtilir. 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 eklenecek standart metindir. Yükleme işleminden sonra Firebase konsolu POSTINSTALL dosyasının içeriğini gösterir ve bu referansları doldurur Bu değer, yüklenen örneğin gerçek yapılandırılmış değerleriyle değiştirilir. Ö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}`**.
  

Ö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 sağlayabileceğiniz ayrıntılı talimatlar ortak metindedir örnekleri inceleyin.

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ü koy 2. düzey başlık altında (##); Markdown'ı kullanabilir istediğiniz biçimlendirmeyi kullanın.

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österilir?

• 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ı dizininin içinde).