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.

Minimum, gerekli belgeler şu üç Markdown dosyasından oluşur:

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

Ayrıca, aşağıdaki prodüksiyonlardan da yararlanabilirsiniz:

• 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 uygulamalardan bazılarını, yaygın ifadeleri ve yapıyı öğrenmek için mevcut dosyaları gözden geçirme resmi Firebase uzantıları ekleyin.

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 KSA, aşağıdaki kolaylık komutunu destekler: web sitenizden alınan içerik barındıran bir README dosyasını otomatik olarak extension.yaml dosyası ve PREINSTALL.md dosyanız:

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

için tüm BENİOKU dosyaları resmi Firebase uzantısı üretilir.

Kurulum bilgilerini ekleyin

BENİOKU dosyası yazdıktan veya oluşturduktan sonra bu alana yükleme bilgilerini ekleyin. Siz ş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 sunucuya erişim gibi ön koşulların listesi hizmet (örnek)
• Kurulum öncesi görevlerin kısa açıklamaları ve talimatları
• Kurulum sonrası görevlerin kısa açıklaması (örnek) (ayrıntılı talimatlar POSTINSTALL içindedir)
• Faturalandırma etkilerinin kısa açıklaması ( ortak metin)

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

Firebase konsolu">

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

Firebase konsolu">

• extensions.dev adresindeki uzantının sayfasında.
• Uzantınız için kaynak kodu deponuz (uzantı dizininin içinde)
• Uzantının README'sinin bir parçası olarak (Firebase KSA'yı kullanıyorsanız) --markdown > README.md flag)

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

Bu konudaki en iyi uygulamalardan bazıları nelerdir?

• PREINSTALL dosyasının tüm içeriğini tek bir sayfanın altında tutun, mümkünse
• Son kullanıcının mutlaka bilmesi gereken ayrıntı düzeyini sağlama uzantıyı yüklemeden önce
• 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. Birkaç örnek verdik ama en fazla temel nokta, Google ve Google dışı faturalandırılan tüm hizmetlerin, listelendi.

Ürün fiyatlandırmayla ilgili doğru ayrıntıları 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ırmayı anlamasına yardımcı olmak amacıyla bu bölümü ekleyin. çıkarım:

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 ayrıntılı yükleme sonrası görüntüsü eğitim sayfası.

Bu dosyada hangi içerik var?

• Yükleme sonrası gerekli görevler için ayrıntılı talimatlar, ör. Firebase güvenlik kuralları ayarlama veya istemci taraflı kod ekleme (örnek)
• Denemenin hemen nasıl başlatılacağına ilişkin genel talimatlar yüklü uzantı (örneğin, "konsola git, ardından bunu yap")
• 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österilir?

Firebase konsolu">

Firebase konsolunda içerik sonrası yükleme

Firebase konsolu">

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

  • POSTINSTALL içeriğini şu tarihe kadar gösterdiğinizden emin olun: uzantınızı gerçek bir şekilde ekleyebilirsiniz.

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

POSTINSTALL dosyaları, parametre değerlerine ve işlevle ilgili çeşitli değerlere erişebilir değişkenlerini ekleyin. POSTINSTALL içeriği Firebase konsolunda parametre yerine gerçek değerler görüntülenir veya değişken referansları bulunmalıdır. Parametre referanslarını ve referans verilerini karşılaştırma değişkenleri POSTINSTALL dosyanıza ekleyin.

Bu konudaki 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).
• Referans parametreler ve işlevle ilgili değişkenler Böylece kullanıcı, yapılandırılmış değerlerini talimatlar bağlamında görür.

Parametreleri ve değişkenleri referans alma

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 (veritabanı gibi) yolunu veya işlev URL'sini içeriyorsa) cümleler ve bölümler hazırlar. Bu en iyi uygulama, metinlerin POSTINSTALL dosyasının içeriği hazır olduğunda Firebase konsolunu gerçek değerlerle oluşturulur.

POSTINSTALL dosyasındaki parametre değerlerine şu söz dizimi: ${param:PARAMETER_NAME}

Ayrıca, yalnızca POSTINSTALL dosyası kullanılabilir. Firebase bu değişkenleri destekler. Böylece: kullanıcılarınıza yükleme sonrası daha kolay rehberlik sağlayabilir. 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}
	Yer fonksiyonun dağıtıldığı yer	Örnek değer: us-central1
${function:function-name.name}
	Aşağıdakini içeren son dağıtılan işlevinin adı: uzantının örnek kimliği	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ılar için, kullanıcılarınızın izleme yapmasına yardımcı olmak amacıyla 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ı dokümanlarında kullanıcılarınıza ve uzantınızı nasıl tetikleyeceğinizi öğreneceksiniz. Bu talimatlarda gerektiğini unutmayın, ancak bir e-tablo yazmak için en iyi uygulamaları POSTINSTALL dosyası. 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, Örneğin, uzantınızın her seferinde yeni bir Cloud Firestore dokümanı oluşturduğunu yeni bir Firebase Authentication kullanıcısı oluşturulur. Kullanıcılarınıza deneme amaçlı olarak Manuel olarak yeni bir Authentication kullanıcısı ekleyerek uzantınızın yüklü bir örneğini görebilirsiniz kontrol edin. Böylece, oluşturulan yeni dokümanı Cloud Firestore bölümüne gidin.

İstemci tarafı kod ekleyin

Uygun olduğunda kullanıcılarınıza istemci tarafı kodu ekleme konusunda talimat da verebilirsiniz kullanın. 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ği ile 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. Alıcı: bir projede aynı uzantının birden fazla yüklemesini barındırma, Firebase işlevi şu biçimde yeniden adlandırır: ext-extension-instance-id-function-name.

Aşağıdaki maddeler, uzantının POSTINSTALL dosyasına ekleyin. 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 adında bir işlev tanımladıysanız aşağıdaki (uygun durumlarda):

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

ziyaret edin.

Önemli: Kullanıcılarınızın HTTP isteği tarafından tetiklenen bir uzantıyı kullanabilmesi için önce 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 hangi içerik var?

Her uzantının değişiklikleri belgeleyen bir CHANGELOG.md dosyası olmalıdır dahil edilir. Her sürümü ekleyin 2. düzey başlık altında (##); Markdown'ı kullanabilir istediğiniz biçimlendirmeyi kullanın.

Aşağıdaki örnekte, resmi uzantıların birinden bir alıntı verilmiştir:

## 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ısına sahip olur. Firebase konsolu ve CLI, yalnızca kullanıcı yeni sürüme geçirme işlemini tamamlarsa geçerli olur.
• Uzantınızın kaynak kodu deposu (uzantı dizininin içinde).