Bu belgede, mesajları uygulama sunucunuzdan istemci uygulamalarına Firebase Cloud Messaging aracılığıyla iletmek için kullanılan HTTP söz dizimi için referans sağlanmaktadır.
Eski HTTP protokolünü kullanırken, uygulama sunucunuz tüm HTTP isteklerini şu uç noktaya yönlendirmelidir:
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, aşağı akış mesajları göndermek ve Firebase Cloud Messaging'den HTTP yanıtlarını yorumlamak için kullanılan söz dizimi verilmektedir.
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 bir mesajın 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 bir çoklu yayın mesajının alıcısını belirtir. Mesaj, birden fazla kayıt jetonuna gönderilir.
Değer, çoklu yayın mesajının gönderileceği kayıt jetonları dizisi olmalıdır. Dizi en az 1, en fazla 1.000 kayıt jetonu içermelidir. Tek bir cihaza mesaj göndermek için Çoklu yayın mesajlarına yalnızca HTTP JSON biçimi kullanılarak izin verilir. |
|
condition |
İsteğe bağlı, dize | Bu parametre, mesaj hedefini belirleyen koşulların mantıksal ifadesini belirtir. Desteklenen koşul: "konularda "konunuz" 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 parametre kullanımdan kaldırılmıştır. Bunun yerine, ileti alıcılarını belirtmek için |
|
Seçenekler | |||
collapse_key |
İsteğe bağlı, dize | Bu parametre, daraltılabilen bir mesaj grubunu (ör. İletilerin hangi sırayla gönderileceği konusunda bir garanti olmadığını unutmayın. Not: Aynı anda 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ğına dair bir garanti yoktur. |
|
priority |
İsteğe bağlı, dize | İletinin önceliğini ayarlar. Geçerli değerler "normal" ve "high" olarak belirlenmiştir. Apple platformlarında bunlar, APN'lerin öncelikleri 5 ve 10'a karşılık gelir. Varsayılan olarak, bildirim mesajları yüksek öncelikli, veri mesajları ise normal öncelikli olarak gönderilir. Normal öncelik, istemci uygulamasının pil tüketimini optimize eder ve hemen teslim gerekmiyorsa kullanılmalıdır. Normal önceliğe sahip mesajlarda, uygulama mesajı belirtilmemiş bir gecikmeyle alabilir. Bir mesaj yüksek öncelikli olarak 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üreyle (saniye cinsinden) saklanması gerektiğini belirtir. Maksimum geçerlilik süresi 4 haftadır. Varsayılan değer 4 haftadır. Daha fazla bilgi için Bir iletinin kullanım süresini ayarlama başlıklı makaleye 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 Varsayılan değer: |
|
Yük | |||
data |
İsteğe bağlı, nesne | Bu parametre, mesajın yükünün özel anahtar/değer çiftlerini belirtir. Örneğin, Apple platformlarında mesaj APN'ler üzerinden gönderiliyorsa özel veri alanlarını temsil eder. FCM aracılığıyla gönderilirse Android'de bu, Anahtar ayrılmış bir kelime olmamalıdır ("from", "message_type" veya "google" ya da "gcm" ile başlayan herhangi bir kelime). Bu tabloda tanımlanan kelimelerin hiçbirini ( Dize türlerindeki değerler önerilir. Nesnelerdeki veya dize olmayan diğer veri türlerindeki değerleri (ör. tamsayılar veya boole'ler) 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ği bölümüne bakın.
Bildirim mesajı ve veri mesajı seçenekleri hakkında daha fazla bilgi için
Mesaj türleri başlıklı makaleye göz atın. Apple cihaza gönderilen bir mesaj için bildirim yükü sağlanırsa veya content_available seçeneği true olarak ayarlanırsa mesaj APN'ler üzerinden gönderilir. Aksi takdirde FCM üzerinden gönderilir.
|
Bildirim yükü desteği
Aşağıdaki tablolarda, iOS ve Android için bildirim mesajları oluşturmak üzere 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 ekran uygulama simgesindeki rozetin değeri. Belirtilmezse rozet değişmez.
|
click_action |
İsteğe bağlı, dize |
Bir kullanıcının bildirimi tıklamasıyla ilişkilendirilen işlem.
APNs yükündeki |
subtitle |
İsteğe bağlı, dize |
Bildirimin alt başlığı. |
body_loc_key |
İsteğe bağlı, dize |
Uygulamanın dize kaynaklarında, gövde metninin kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak gövde dizesi anahtarı.
APNs yükündeki 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
APNs yükündeki 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 |
Uygulamanın dize kaynaklarında, başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak başlık dizesinin anahtarı.
APNs yükündeki 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 geçerli yerelleştirmesine göre yerelleştirmek için
APNs yükündeki 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 yeni). 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 manifestinde belirtilen kanal kimliğini kullanır. |
icon |
İsteğe bağlı, dize |
Bildirimin simgesi.
Çekilebilir |
sound |
İsteğe bağlı, dize |
Cihaz bildirimi aldığında çalacak ses.
|
tag |
İsteğe bağlı, dize |
Bildirim çekmecesindeki mevcut bildirimlerin yerini alan 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 |
Bir kullanıcının bildirimi tıklamasıyla ilişkilendirilen işlem. Belirtilirse kullanıcı bildirimi tıkladığında, eşleşen amaç filtresine sahip bir etkinlik başlatılır. |
body_loc_key |
İsteğe bağlı, dize |
Uygulamanın dize kaynaklarında, gövde metninin kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak gövde dizesi 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 Daha fazla bilgi için Biçimlendirme ve Stil bölümüne bakın. |
title_loc_key |
İsteğe bağlı, dize |
Uygulamanın dize kaynaklarında, başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için kullanılacak 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 geçerli yerelleştirmesine göre yerelleştirmek için 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 |
Bildirimin simgesi için kullanılacak URL. |
click_action |
İsteğe bağlı, dize |
Bir 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ında 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. Çoklu yayın mesajlarına (birden fazla kayıt jetonuna gönderme) yalnızca HTTP JSON biçimi kullanılarak izin verilir. |
Seçenekler | ||
collapse_key |
İsteğe bağlı, dize | Ayrıntılar için 1. tabloya bakın. |
time_to_live |
İsteğe bağlı, sayı | Ayrıntılar için 1. tabloya bakın. |
restricted_package_name |
İsteğe bağlı, dize | Ayrıntılar için 1. tabloya bakın. |
dry_run |
İsteğe bağlı, boole | Ayrıntılar için 1. tabloya 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ına ilişkin bir sınır yoktur ancak toplam 4.096 baytlık mesaj boyutu sınırı vardır. Örneğin, Android'de Anahtar ayrılmış bir kelime olmamalıdır ("from", "message_type" veya "google" ya da "gcm" ile başlayan herhangi bir kelime). 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övdeyi değerlendirmelidir. Aşağıdaki tabloda olası yanıtlar açıklanmaktadır.
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 isteğin biçimi, isteğin JSON veya düz metin olmasına göre değişir. Daha fazla bilgi için 5. tabloya 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ı olması beklenen bir dizeyi iletme) belirtir. Hatanın tam nedeni yanıtta açıklanır ve istek yeniden denenmeden önce sorun giderilmelidir. |
401 | Gönderen hesabının kimliği doğrulanırken bir hata oluştu. |
5xx | 500-599 aralığındaki hatalar (500 veya 503 gibi), isteği işlemeye çalışı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önderenin daha sonra yanıtta yer alan Retry-After üst bilgisi dikkate alınarak yeniden denemesi gerekir. Uygulama sunucuları eksponansiyel geri yükleme uygulamalıdır. |
Aşağıdaki tabloda, aşağı akış mesaj 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ı | Hatasız işlenen ileti sayısı. |
failure |
Zorunlu, sayı | İşlenemeyen iletilerin sayısı. |
results |
Zorunlu, 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 sonuç, yanıtta 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 olan tüm cihazlara teslim etmeye çalıştığında kullanılan 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 mesaj kimliğini belirtir. |
registration_id |
İsteğe bağlı, dize | Bu parametre, mesajın işlenip gönderildiği istemci uygulaması için kayıt jetonunu belirtir. |
Parametre | Kullanım | Açıklama |
---|---|---|
Error |
Zorunlu, dize | Bu parametre, alıcı için mesajı işlerken hata değerini belirtir. Ayrıntılar için tablo 9'a 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 bir kayıt jetonu içerip içermediğini kontrol edin (düz kısa mesajdaki registration_id alanında veya JSON'daki to ya da registration_ids alanında). |
Geçersiz Kayıt Jetonu | 200 + hata:Geçersiz Kayıt | Sunucuya ilettiğiniz kayıt jetonunun biçimini kontrol edin. Bu kodun, istemci uygulamasının Firebase Notifications'a kaydolurken aldığı kayıt jetonuyla eşleştiğinden emin olun. Kısaltmayın veya fazladan karakter eklemeyin. |
Kayıtlı Olmayan Cihaz | 200 + hata:Kayıtlı Değil | Mevcut kayıt jetonunun geçerliliği, aşağıdakiler de dahil olmak üzere çeşitli senaryolarda sona erebilir:
|
Geçersiz Paket Adı | 200 + hata:GeçersizPaketAdı | İletinin, paket adı istekte iletilen değerle eşleşen bir kayıt jetonuna yönlendirildiğinden emin olun. |
Kimlik Doğrulama Hatası | 401 | İleti göndermek için kullanılan gönderen hesabının kimliği doğrulanamadı. Olası nedenler şunlardır:
|
Gönderen Eşleşmiyor | 200 + hata: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 belirtmesi gerekir. İstemci uygulamasına ileti gönderirken bu gönderen kimliklerinden birini kullanmalısınız. Farklı bir gönderene geçerseniz mevcut kayıt jetonları çalışmaz. |
Geçersiz JSON | 400 | JSON mesajının düzgün şekilde biçimlendirildiğinden ve geçerli alanlar içerdiğinden emin olun (örneğin, doğru veri türünün iletildiğinden emin olun). |
Geçersiz Parametreler | 400 + hata:GeçersizParametreler | Sağlanan parametrelerin doğru ada ve türe sahip olduğundan emin olun. |
Mesaj Çok Büyük | 200 + hata:İleti çokBig | Bir mesaja dahil edilen yük verilerinin toplam boyutunun FCM sınırlarını aşmadığından emin olun: çoğu mesaj için 4.096 bayt, konulara gönderilen mesajlarda ise 2.448 bayt. Buna hem anahtarlar hem de değerler dahildir. |
Geçersiz Veri Anahtarı | 200 + hata:
GeçersizVeri Anahtarı |
Yük verilerinde, FCM tarafından dahili olarak kullanılan bir anahtar (from veya gcm gibi ya da google ön ekine sahip herhangi bir değer) bulunmadığından emin olun. FCM tarafından da bazı kelimelerin (collapse_key gibi) kullanıldığını ancak yükte 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 + hata:GeçersizTl | time_to_live için kullanılan değerin, 0 ile 2.419.200 (4 hafta) arasında saniye cinsinden bir süreyi temsil eden tam sayı olduğundan emin olun. |
Engelleme | 5xx veya 200 + hata:Kullanılamıyor | Sunucu isteği zamanında işleyemedi. Aynı isteği tekrar göndermeyi deneyin. Bu durumda, şunları yapmanız gerekir:
Sorunlara neden olan gönderenler kara listeye alınma riskiyle karşı karşıyadır. |
Dahili Sunucu Hatası | 500 veya 200 + hata:InternalServerError | Sunucu, isteği işlemeye çalışırken bir hatayla karşılaştı. "Zaman Aşımı" bölümünde listelenen (yukarıdaki satıra bakın) gereksinimleri izleyerek aynı isteği yeniden deneyebilirsiniz. Hata devam ederse lütfen Firebase destek ekibiyle iletişime geçin. |
Cihaz Mesaj Hızı Aşıldı | 200 + hata:
DeviceMessageRate Aşıldı |
Belirli bir cihaza gönderilen iletilerin 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 mesajların sayısını azaltın ve göndermeyi yeniden denemek için üstel geri yükleme özelliğini kullanın. |
Konular Mesaj Hızı Aşıldı | 200 + hata:
TopicsMessageRate Aşıldı |
Belirli bir konuda abonelere gönderilen mesajların oranı çok yüksek. Bu konu için gönderilen mesajların sayısını azaltın ve göndermeyi yeniden denemek için üstel geri yükleme özelliğini kullanın. |
Geçersiz APNs kimlik bilgileri | 200 + hata:
InvalidApnsCredential |
Gerekli APNs kimlik doğrulama anahtarı yüklenmediği veya süresi dolduğundan Apple cihazına hedeflenen mesaj gönderilemedi. Geliştirme ve üretim kimlik bilgilerinizin geçerliliğini kontrol edin. |
Cihaz grubu yönetimi
Aşağıdaki tabloda, cihaz grupları oluşturma ve üye ekleme ve kaldırmayla ilgili anahtarlar listelenmiştir. Daha fazla bilgi için platformunuza ( iOS+ veya Android) yönelik kılavuza bakın.
Parametre | Kullanım | Açıklama |
---|---|---|
operation |
Zorunlu, dize | Çalıştırılacak işlem.Geçerli değerler: create , add ve remove . |
notification_key_name |
Zorunlu, dize | Oluşturulacak veya değiştirilecek cihaz grubunun kullanıcı tanımlı adı. |
notification_key |
Zorunlu (create işlemi, dize hariç) |
Cihaz grubunun benzersiz tanımlayıcısı. Bu değer, başarılı bir create işleminin yanıtında döndürülür ve cihaz grubunda 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. |