Bu belgede, mesajları Firebase Cloud Messaging aracılığıyla uygulama sunucunuzdan istemci uygulamalarına aktarmak için kullanılan HTTP söz dizimine yönelik bir referans sağlanmaktadır.
Eski HTTP protokolünü kullanırken uygulama sunucunuzun tüm HTTP isteklerini bu uç noktaya yönlendirmesi gerekir:
https://fcm.googleapis.com/fcm/send
Kullanılabilir parametreler ve seçenekler aşağıdaki geniş kategorilere ayrılır:
Aşağı akış mesajı söz dizimi
Bu bölümde, Firebase Cloud Messaging'den aşağı akış mesajları göndermek ve HTTP yanıtlarını yorumlamak için kullanılan söz dizimi açıklanmaktadır.
Aşağı akış HTTP mesajları (JSON)
Aşağıdaki tabloda HTTP JSON mesajlarının hedefleri, seçenekleri ve yükü listelenmiştir.
Parametre | Kullanım | Açıklama | |
---|---|---|---|
Hedefler | |||
to |
İsteğe bağlı, dize |
Bu parametre, iletinin alıcısını belirtir.
Değer, bir cihazın kayıt jetonu, cihaz grubunun bildirim anahtarı veya tek bir konu ( |
|
registration_ids | İsteğe bağlı, dize dizisi |
Bu parametre, birden fazla kayıt jetonuna gönderilen bir çoklu yayın mesajının alıcısını belirtir.
Değer, çoklu yayın mesajının gönderileceği kayıt jetonları dizisi olmalıdır. Dizide en az 1, en fazla 1.000 kayıt jetonu bulunmalıdır. Tek bir cihaza mesaj göndermek için Çoklu yayın mesajlarına yalnızca HTTP JSON biçimi kullanıldığında izin verilir. |
|
condition |
İsteğe bağlı, dize | Bu parametre, mesaj hedefini belirleyen koşulların mantıksal ifadesini belirtir. Desteklenen koşul: "Konularda "konu" olarak biçimlendirilmiş konu. Bu değer büyük/küçük harfe duyarlı değildir. Desteklenen operatörler: |
|
notification_key Kullanımdan kaldırıldı |
İsteğe bağlı, dize | Bu parametrenin desteği sonlandırıldı. Bunun yerine, ileti alıcılarını belirtmek için |
|
Seçenekler | |||
collapse_key |
İsteğe bağlı, dize | Bu parametre, daraltılabilen bir ileti grubunu (ör. Mesajların hangi sırayla gönderileceğine dair herhangi bir garanti verilmediğini unutmayın. Not: Herhangi bir zamanda en fazla 4 farklı daraltma anahtarına izin verilir. Bu, FCM'nin istemci uygulaması başına aynı anda 4 farklı mesaj depolayabileceği anlamına gelir. Bu sayıyı aşarsanız FCM'nin hangi 4 daraltma anahtarını saklayacağı konusunda bir garanti verilmez. |
|
priority |
İsteğe bağlı, dize | İletinin önceliğini ayarlar. Geçerli değerler "normal" ve "yüksek"tir. Apple platformlarında Bunlar, APN 5 ve 10 önceliklerine karşılık gelir. Varsayılan olarak, bildirim mesajları yüksek öncelikli, veri mesajları ise normal öncelikli gönderilir. Normal öncelik, istemci uygulamasının pil tüketimini optimize eder ve acil teslimat gerekmiyorsa kullanılmalıdır. Normal önceliğe sahip mesajlar için uygulama, mesajı belirtilmeyen bir gecikmeyle alabilir. Yüksek öncelikli bir mesaj gönderildiğinde hemen gönderilir ve uygulama bir bildirim görüntüleyebilir. |
|
content_available |
İsteğe bağlı, boole | Apple platformlarında, APNs yükünde |
|
mutable_content |
İsteğe bağlı, JSON boole | Apple platformlarında, APNs yükünde |
|
time_to_live |
İsteğe bağlı, sayı | Bu parametre, cihaz çevrimdışıysa mesajın FCM depolama alanında ne kadar süre boyunca (saniye cinsinden) saklanması gerektiğini belirtir. Desteklenme süresi maksimum 4 hafta, varsayılan değer 4 haftadır. Daha fazla bilgi için Bir iletinin kullanım ömrünü ayarlama konusuna bakın. |
|
restricted_package_
(yalnızca Android) |
İsteğe bağlı, dize | Bu parametre, mesajı almak için kayıt jetonlarının eşleşmesi gereken uygulamanın paket adını belirtir. | |
dry_run |
İsteğe bağlı, boole | Bu parametre,
|
|
Yük | |||
data |
İsteğe bağlı, nesne | Bu parametre, mesaj yükünün özel anahtar/değer çiftlerini belirtir. Örneğin, Apple platformlarında mesaj APN'ler üzerinden gönderilirse özel veri alanlarını temsil eder. FCM ile gönderilirse Android'de bu, Anahtar, ayrılmış bir kelime ("from", "message_type" veya "google" ya da "gcm" ile başlayan herhangi bir kelime) olmamalıdır. Bu tabloda tanımlanan kelimelerin ( Dize türlerindeki değerlerin kullanılması önerilir. Nesnelerdeki veya dize dışı diğer veri türlerindeki (ör. tam sayılar ya da booleler) değerleri dizeye dönüştürmeniz gerekir. |
|
notification |
İsteğe bağlı, nesne | Bu parametre, bildirim yükünün önceden tanımlanmış, kullanıcı tarafından görülebilen anahtar/değer çiftlerini belirtir. Ayrıntılı bilgi için Bildirim yükü desteğine bakın.
Bildirim mesajı ve veri mesajı seçenekleri hakkında daha fazla bilgi için
Mesaj türleri bölümüne göz atın. Apple cihaza gönderilen mesaj için bildirim yükü sağlanırsa veya content_available seçeneği true olarak ayarlanırsa mesaj APN'ler üzerinden, aksi takdirde FCM aracılığıyla gönderilir.
|
Bildirim yükü desteği
Aşağıdaki tablolarda, iOS ve Android için bildirim mesajları oluşturmak amacıyla kullanılabilen önceden tanımlanmış anahtarlar listelenmiştir.
Parametre | Kullanım | Açıklama |
---|---|---|
title |
İsteğe bağlı, dize |
Bildirimin başlığı. Bu alan telefonlarda ve tabletlerde görünmez. |
body |
İsteğe bağlı, dize |
Bildirimin gövde metni. |
sound |
İsteğe bağlı, dize |
Cihaz bildirimi aldığında çalacak ses.
İstemci uygulamasının ana paketinde veya uygulamanın veri kapsayıcısının |
badge |
İsteğe bağlı, dize |
Ana ekrandaki uygulama simgesindeki rozetin değeri. Belirtilmezse rozet değiştirilmez.
|
click_action |
İsteğe bağlı, dize |
Kullanıcının bildirimi tıklamasıyla ilişkilendirilen işlem.
APNs yükünde |
subtitle |
İsteğe bağlı, dize |
Bildirimin alt başlığı. |
body_loc_key |
İsteğe bağlı, dize |
Gövde metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak, uygulamanın dize kaynaklarındaki gövde dizesinin anahtarı.
APNs yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine göz atın. |
body_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Gövde metnini kullanıcının geçerli yerelleştirmesine göre yerelleştirmek için kullanılacak
APNs yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine göz atın. |
title_loc_key |
İsteğe bağlı, dize |
Başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak, uygulamanın dize kaynaklarındaki başlık dizesinin anahtarı.
APNs yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine göz atın. |
title_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak olan
APNs yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine göz atın. |
Parametre | Kullanım | Açıklama |
---|---|---|
title |
İsteğe bağlı, dize |
Bildirimin başlığı. |
body |
İsteğe bağlı, dize |
Bildirimin gövde metni. |
android_channel_id |
İsteğe bağlı, dize |
Bildirimin kanal kimliği (Android O'da yenidir). Bu kanal kimliğine sahip herhangi bir bildirim alınmadan önce uygulamanın bu kanal kimliğiyle bir kanal oluşturması gerekir. İstekte bu kanal kimliğini göndermezseniz veya sağlanan kanal kimliği henüz uygulama tarafından oluşturulmamışsa FCM, uygulama manifest dosyasında belirtilen kanal kimliğini kullanır. |
icon |
İsteğe bağlı, dize |
Bildirimin simgesi.
Çekilebilir kaynak |
sound |
İsteğe bağlı, dize |
Cihaz bildirimi aldığında çalacak ses.
|
tag |
İsteğe bağlı, dize |
Bildirim çekmecesindeki mevcut bildirimleri değiştirmek için kullanılan tanımlayıcı. Belirtilmezse her istek yeni bir bildirim oluşturur. Belirtilmişse ve aynı etikete sahip bir bildirim zaten gösteriliyorsa yeni bildirim, bildirim çekmecesindeki mevcut bildirimin yerini alır. |
color |
İsteğe bağlı, dize |
Bildirimin, |
click_action |
İsteğe bağlı, dize |
Kullanıcının bildirimi tıklamasıyla ilişkilendirilen işlem. Belirtilirse kullanıcı bildirimi tıkladığında eşleşen intent filtresine sahip bir etkinlik başlatılır. |
body_loc_key |
İsteğe bağlı, dize |
Gövde metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak, uygulamanın dize kaynaklarındaki gövde dizesinin anahtarı. Daha fazla bilgi için Dize Kaynakları bölümüne bakın. |
body_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Gövde metnini kullanıcının geçerli yerelleştirmesine göre yerelleştirmek için kullanılacak Daha fazla bilgi için Biçimlendirme ve Stil bölümüne bakın. |
title_loc_key |
İsteğe bağlı, dize |
Başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak, uygulamanın dize kaynaklarındaki başlık dizesinin anahtarı. Daha fazla bilgi için Dize Kaynakları bölümüne bakın. |
title_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak olan Daha fazla bilgi için Biçimlendirme ve Stil bölümüne bakın. |
Parametre | Kullanım | Açıklama |
---|---|---|
title |
İsteğe bağlı, dize |
Bildirimin başlığı. |
body |
İsteğe bağlı, dize |
Bildirimin gövde metni. |
icon |
İsteğe bağlı, dize |
Bildirim simgesi için kullanılacak URL. |
click_action |
İsteğe bağlı, dize |
Kullanıcının bildirimi tıklamasıyla ilişkilendirilen işlem. Tüm URL değerleri için HTTPS gereklidir. |
Aşağı akış HTTP mesajları (Düz Metin)
Aşağıdaki tabloda, düz metin aşağı akış HTTP mesajlarındaki hedefler, seçenekler ve yük için söz dizimi listelenmektedir.
Parametre | Kullanım | Açıklama |
---|---|---|
Hedefler | ||
registration_id |
Zorunlu, dize | Bu parametre, mesajı alan istemci uygulamalarını (kayıt jetonları) belirtir. Yalnızca HTTP JSON biçimi kullanılarak çoklu yayın mesajlaşmasına (birden fazla kayıt jetonuna gönderme) izin verilir. |
Seçenekler | ||
collapse_key |
İsteğe bağlı, dize | Ayrıntılar için 1. tablo'ya bakın. |
time_to_live |
İsteğe bağlı, sayı | Ayrıntılar için 1. tablo'ya bakın. |
restricted_package_name |
İsteğe bağlı, dize | Ayrıntılar için 1. tablo'ya bakın. |
dry_run |
İsteğe bağlı, boole | Ayrıntılar için 1. tablo'ya bakın. |
Yük | ||
data.<key> |
İsteğe bağlı, dize | Bu parametre, mesaj yükünün anahtar/değer çiftlerini belirtir. Anahtar/değer parametrelerinin sayısıyla ilgili bir sınır yoktur ancak toplam mesaj boyutu sınırı 4.096 bayttır. Örneğin, Android'de Anahtar, ayrılmış bir kelime ("from", "message_type" veya "google" ya da "gcm" ile başlayan herhangi bir kelime) olmamalıdır. Bu tabloda tanımlanan kelimelerin hiçbirini ( |
Aşağı akış mesaj yanıtını yorumlama
Uygulama sunucusu, FCM'den gönderilen mesaj yanıtını yorumlamak için hem mesaj yanıtı üstbilgisini hem de gövdesini değerlendirmelidir. Aşağıdaki tabloda olası yanıtlar verilmiştir.
Yanıt | Açıklama |
---|---|
200 | İleti başarıyla işlendi. Yanıt gövdesi, mesaj durumu hakkında daha fazla ayrıntı içerir ancak biçimi, isteğin JSON mi yoksa düz metin mi olduğuna bağlıdır. Daha fazla ayrıntı için 5. tablo'ya bakın. |
400 | Yalnızca JSON istekleri için geçerlidir. İsteğin JSON olarak ayrıştırılamadığını veya geçersiz alanlar içerdiğini (örneğin, bir sayının beklendiği dizenin iletilmesini) belirtir. Hatanın tam nedeni yanıtta açıklanır ve istek yeniden denenmeden önce sorun giderilmelidir. |
401 | Gönderen hesabın kimliği doğrulanırken bir hata oluştu. |
5xx | 500-599 aralığındaki hatalar (500 veya 503 gibi), istek işlenmeye çalışılırken FCM arka ucunda dahili bir hata oluştuğunu veya sunucunun geçici olarak kullanılamadığını (örneğin, zaman aşımları nedeniyle) belirtir. Gönderen, daha sonra yanıta eklenen Retry-After üstbilgilerini dikkate alarak yeniden denemelidir. Uygulama sunucuları üstel geri çekme uygulamalıdır. |
Aşağıdaki tabloda, aşağı akış ileti yanıtı gövdesindeki (JSON) alanlar listelenmektedir.
Parametre | Kullanım | Açıklama |
---|---|---|
multicast_id |
Zorunlu, sayı | Çoklu yayın mesajını tanımlayan benzersiz kimlik (sayı). |
success |
Zorunlu, sayı | Hata olmadan işlenen iletilerin sayısı. |
failure |
Zorunlu, sayı | İşlenemeyen iletilerin sayısı. |
results |
Gerekli, nesne dizisi | İşlenen mesajların durumunu temsil eden nesne dizisi. Nesneler istekle aynı sırada listelenir (yani istekteki her kayıt kimliği için sonucu, yanıttaki aynı dizinde listelenir).
|
Parametre | Kullanım | Açıklama |
---|---|---|
message_id |
İsteğe bağlı, sayı | FCM, isteği başarıyla aldığında ve abone olunan tüm cihazlara teslim etmeyi denediğinde gösterilen konu mesaj kimliği. |
error |
İsteğe bağlı, dize | İleti işlenirken hata oluştu. Olası değerler tablo 9'da bulunabilir. |
Parametre | Kullanım | Açıklama |
---|---|---|
id |
Zorunlu, dize | Bu parametre, FCM'nin başarıyla işlenen benzersiz ileti kimliğini belirtir. |
registration_id |
İsteğe bağlı, dize | Bu parametre, mesajın işlenip gönderildiği istemci uygulamasının kayıt jetonunu belirtir. |
Parametre | Kullanım | Açıklama |
---|---|---|
Error |
Zorunlu, dize | Bu parametre, alıcı için ileti işlenirken hata değerini belirtir. Ayrıntılar için 9. tablo'ya bakın. |
Aşağı akış mesajı hata yanıtı kodları
Aşağıdaki tabloda, aşağı akış mesajları için hata yanıtı kodları listelenmektedir.
Hata | HTTP Kodu | Önerilen işlem |
---|---|---|
Kayıt Jetonu Eksik | 200 + hata:EksikKayıt | İsteğin kayıt jetonu içerdiğinden emin olun (düz metin mesajındaki registration_id alanında veya JSON'daki to ya da registration_ids alanında). |
Geçersiz Kayıt Jetonu | 200 + error:InvalidRegistration | Sunucuya ilettiğiniz kayıt jetonunun biçimini kontrol edin. URL'nin, istemci uygulamasının Firebase Notifications'a kaydolurken aldığı kayıt jetonuyla eşleştiğinden emin olun. Kırpmayın veya başka karakterler eklemeyin. |
Kayıtlı Olmayan Cihaz | 200 + hata:Kayıtlı Değil | Mevcut bir kayıt jetonunun geçerliliği, aşağıdakiler gibi çeşitli durumlarda sona erebilir:
|
Geçersiz Paket Adı | 200 + hata:GeçersizPackageName | Mesajın, paket adı istekte iletilen değerle eşleşen bir kayıt jetonuna gönderildiğinden emin olun. |
Kimlik Doğrulama Hatası | 401 | İleti göndermek için kullanılan gönderen hesabının kimliği doğrulanamadı. Bunun olası nedenleri şunlardır:
|
Gönderen Eşleşmiyor | 200 + error:MismatchSenderId | Kayıt jetonu belirli bir gönderen grubuna bağlıdır. Bir istemci uygulaması FCM'ye kaydolduğunda, hangi gönderenlerin ileti göndermesine izin verildiğini belirtmelidir. İstemci uygulamasına ileti gönderirken bu gönderen kimliklerinden birini kullanmanız gerekir. Farklı bir gönderene geçerseniz mevcut kayıt jetonları çalışmaz. |
Geçersiz JSON | 400 | JSON mesajının doğru şekilde biçimlendirildiğinden ve geçerli alanlar içerdiğinden (örneğin, doğru veri türünün aktarıldığından emin olun) emin olun. |
Geçersiz Parametreler | 400 + error:InvalidParameters (Geçersiz Parametreler) | Sağlanan parametrelerin doğru ad ve türe sahip olduğundan emin olun. |
Mesaj Çok Büyük | 200 + hata:MessageTooBig | Bir mesaja eklenen yük verilerinin toplam boyutunun FCM sınırlarını aşmadığından emin olun: çoğu mesaj için 4.096 bayt veya konulara gönderilen mesajlar için 2.048 bayt. Buna hem anahtarlar hem de değerler dahildir. |
Geçersiz Veri Anahtarı | 200 + hata:
InvalidDataKey |
Yük verilerinin, FCM tarafından dahili olarak kullanılan bir anahtar (ör. from veya gcm ya da google önekli herhangi bir değer) içermediğinden emin olun. Bazı kelimelerin (collapse_key gibi) FCM tarafından da kullanıldığını ancak yükte kullanılmasına izin verildiğini unutmayın. Bu durumda, yük değeri FCM değeri tarafından geçersiz kılınır. |
Geçersiz Geçerlilik Süresi | 200 + error:GeçersizTtl | time_to_live öğesinde kullanılan değerin, 0 ile 2.419.200 (4 hafta) arasında saniye cinsinden bir süreyi temsil eden bir tam sayı olduğundan emin olun. |
Zaman aşımı | 5xx veya 200 + hata:Kullanılamıyor | Sunucu isteği zamanında işleyemedi. Aynı isteği yeniden deneyin, ancak şunları yapmanız gerekir:
Soruna neden olan gönderenler kara listeye alınma riskiyle karşı karşıya kalır. |
Dahili Sunucu Hatası | 500 veya 200 + error:InternalServerError | Sunucu, isteği işlemeye çalışırken bir hatayla karşılaştı. Aynı isteği "Zaman aşımı" bölümünde listelenen gereksinimleri uygulayarak yeniden deneyebilirsiniz (yukarıdaki satıra bakın). Hata devam ederse lütfen Firebase destek ekibiyle iletişime geçin. |
Cihaz İletisi Hızı Aşıldı | 200 + hata:
DeviceMessageRate Aşıldı |
Belirli bir cihaza gönderilen mesajların oranı çok yüksek. Bir Apple uygulaması, APNs sınırlarını aşan bir hızda mesaj gönderirse bu hata mesajını alabilir. Bu cihaza gönderilen mesaj sayısını azaltın ve göndermeyi yeniden denemek için üstel geri yükleme yöntemini kullanın. |
Konular İçin İleti Hızı Aşıldı | 200 + hata:
TopicsMessageRate Aşıldı |
Belirli bir konunun abonelere gönderilen mesajların oranı çok yüksek. Bu konu için gönderilen mesaj sayısını azaltın ve göndermeyi yeniden denemek için üstel geri yükleme yöntemini kullanın. |
APNs kimlik bilgileri geçersiz | 200 + hata:
InvalidApnsCredential |
Gerekli APNs kimlik doğrulama anahtarı yüklenmediği veya süresi dolduğu için Apple cihazı hedefleyen bir mesaj gönderilemedi. Geliştirme ve üretim kimlik bilgilerinizin geçerliliğini kontrol edin. |
Cihaz grubu yönetimi
Aşağıdaki tabloda, cihaz grubu oluşturma ve üye ekleme ve kaldırma ile ilgili anahtarlar listelenmiştir. Daha fazla bilgi için platformunuz, iOS+ veya Android kılavuzuna bakın.
Parametre | Kullanım | Açıklama |
---|---|---|
operation |
Zorunlu, dize | Çalıştırılacak işlem.Geçerli değerler create , add ve remove şeklindedir. |
notification_key_name |
Zorunlu, dize | Oluşturulacak veya değiştirilecek cihaz grubunun kullanıcı tanımlı adı. |
notification_key |
Zorunlu (create işlemi hariç, dize |
Cihaz grubunun benzersiz tanımlayıcısı. Bu değer, başarılı bir create işlemi için yanıt olarak döndürülür ve cihaz grubunda yapılan sonraki tüm işlemler için gereklidir. |
registration_ids |
Zorunlu, dize dizisi | Eklenecek veya kaldırılacak cihaz jetonları. Bir cihaz grubundaki mevcut tüm kayıt jetonlarını kaldırırsanız FCM, cihaz grubunu siler. |