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?
- 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
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:
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?
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ı gerçek bir projeye yükleyerek
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.
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: Örnek değer: | |
${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: Örnek değer: |
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.
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).
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çinTo trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.
HTTP çağrılabilir (
onCall
) işlevleri içinThis 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 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).