Bu belge, Firebase Cloud Messaging aracılığıyla mesajları uygulama sunucunuzdan istemci uygulamalarına iletmek için kullanılan HTTP söz dizimine ilişkin bir referans sağlar.
Eski HTTP protokolünü kullanırken uygulama sunucunuzun tüm HTTP isteklerini bu uç noktaya yönlendirmesi gerekir:
https://fcm.googleapis.com/fcm/send
Mevcut parametreler ve seçenekler aşağıdaki geniş kategorilere ayrılır:
Aşağı akış mesajı sözdizimi
Bu bölümde, aşağı akış mesajları göndermek ve Firebase Cloud Messaging'den HTTP yanıtlarını yorumlamak için söz dizimi verilmektedir.
Aşağı akış HTTP mesajları (JSON)
Aşağıdaki tabloda HTTP JSON iletilerine ilişkin hedefler, seçenekler ve veriler listelenmektedir.
Parametre | Kullanım | Tanım | |
---|---|---|---|
Hedefler | |||
to | İsteğe bağlı, dize | Bu parametre mesajın alıcısını belirtir. Değer, bir cihazın kayıt jetonu, bir cihaz grubunun bildirim anahtarı veya tek bir konu (ön eki | |
registration_ids | İsteğe bağlı, dize dizisi | Bu parametre, birden fazla kayıt belirtecine gönderilen bir mesaj olan çok noktaya yayın mesajının alıcısını belirtir. Değer, çok noktaya yayın mesajının gönderileceği kayıt belirteçlerinin bir dizisi olmalıdır. Dizi en az 1, en fazla 1000 kayıt jetonu içermelidir. Tek bir cihaza mesaj göndermek için Çok noktaya yayın iletilerine 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: Konu, "Konularda 'Konunuz'" olarak biçimlendirilmiştir. 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ıldı. Bunun yerine, ileti alıcılarını belirtmek | |
Seçenekler | |||
collapse_key | İsteğe bağlı, dize | Bu parametre, daraltılabilecek bir mesaj grubunu (örneğin, Mesajların gönderilme sırası konusunda 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ı tutacağının garantisi yoktur. | |
priority | İsteğe bağlı, dize | Mesajın önceliğini ayarlar. Geçerli değerler "normal" ve "yüksek"tir. Apple platformlarında bunlar APN'nin 5 ve 10 önceliklerine karşılık gelir. Varsayılan olarak, bildirim mesajları yüksek öncelikle, veri mesajları ise normal öncelikle gönderilir. Normal öncelik, istemci uygulamasının pil tüketimini optimize eder ve hemen teslim gerekmediği sürece kullanılmalıdır. Normal öncelikli mesajlar için uygulama, mesajı belirtilmemiş 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, APN verisinde | |
mutable_content | İsteğe bağlı, JSON boolean'ı | Apple platformlarında, APN verisindeki | |
time_to_live | İsteğe bağlı, sayı | Bu parametre, cihazın çevrimdışı olması durumunda mesajın FCM deposunda ne kadar süreyle (saniye olarak) saklanması gerektiğini belirtir. Desteklenen maksimum süre 4 haftadır ve varsayılan değer 4 haftadır. Daha fazla bilgi için bkz. Bir mesajın ömrünü ayarlama . | |
restricted_package_ (yalnızca Android) | İsteğe bağlı, dize | Bu parametre, mesajı alabilmek için kayıt belirteçlerinin 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 aracılığıyla gönderiliyorsa özel veri alanlarını temsil eder. FCM yoluyla gönderilirse Android'de bu, Anahtar, ayrılmış bir kelime ("from", "message_type" veya "google" veya "gcm" ile başlayan herhangi bir kelime) olmamalıdır. Bu tabloda tanımlanan kelimelerin hiçbirini kullanmayın ( Dize türlerindeki değerler önerilir. Nesnelerdeki veya dize olmayan diğer veri türlerindeki (örneğin, tamsayılar veya boolean'lar) 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 verisi desteğine bakın. Bildirim mesajı ve veri mesajı seçenekleri hakkında daha fazla bilgi için bkz. Mesaj türleri . Bir bildirim verisi sağlanırsa veya bir Apple cihazına gönderilen mesaj için content_available seçeneği true olarak ayarlanırsa mesaj APN'ler aracılığıyla gönderilir , 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 için kullanılabilen önceden tanımlanmış anahtarlar listelenmektedir.
Parametre | Kullanım | Tanım |
---|---|---|
title | İsteğe bağlı, dize | Bildirimin başlığı. Bu alan telefon 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 çalınacak ses. İstemci uygulamasının ana paketindeki veya uygulamanın veri taşıyıcısının |
badge | İsteğe bağlı, dize | Ana ekrandaki uygulama simgesindeki rozetin değeri. Belirtilmediği takdirde rozet değiştirilmez. |
click_action | İsteğe bağlı, dize | Bir kullanıcının bildirime tıklamasıyla ilişkili eylem. APN yükündeki |
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 geçerli yerelleştirmesine göre yerelleştirmek için kullanılacak, uygulamanın dize kaynaklarındaki gövde dizesinin anahtarı. APN yükündeki Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine 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 APN yükündeki Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine bakın. |
title_loc_key | İsteğe bağlı, dize | Başlık metnini kullanıcının geçerli yerelleştirmesine göre yerelleştirmek için kullanılacak, uygulamanın dize kaynaklarındaki başlık dizesinin anahtarı. APN yükündeki Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine 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 kullanılacak APN yükündeki Daha fazla bilgi için Yük Anahtarı Referansı ve Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme bölümlerine bakın. |
Parametre | Kullanım | Tanım |
---|---|---|
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ğine sahip 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 kaynak |
sound | İsteğe bağlı, dize | Cihaz bildirimi aldığında çalınacak ses. |
tag | İsteğe bağlı, dize | Bildirim çekmecesindeki mevcut bildirimleri değiştirmek için kullanılan tanımlayıcı. Belirtilmediği takdirde 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 bildirime tıklamasıyla ilişkili eylem. 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 | Gövde metnini kullanıcının geçerli 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ına 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 Şekillendirme konusuna bakın. |
title_loc_key | İsteğe bağlı, dize | Başlık metnini kullanıcının geçerli 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ına 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 kullanılacak Daha fazla bilgi için Biçimlendirme ve Şekillendirme konusuna bakın. |
Parametre | Kullanım | Tanım |
---|---|---|
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 | Bir kullanıcının bildirime tıklamasıyla ilişkili eylem. 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ışlı HTTP mesajlarındaki hedefler, seçenekler ve yük için söz dizimi listelenmektedir.
Parametre | Kullanım | Tanım |
---|---|---|
Hedefler | ||
registration_id | Gerekli, dize | Bu parametre, mesajı alan istemci uygulamalarını (kayıt belirteçleri) belirtir. Çok noktaya yayın mesajlaşmasına (birden fazla kayıt belirtecine 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 tablo 1'e bakın. |
time_to_live | İsteğe bağlı, sayı | Ayrıntılar için tablo 1'e bakın. |
restricted_package_name | İsteğe bağlı, dize | Ayrıntılar için tablo 1'e bakın. |
dry_run | İsteğe bağlı, boole | Ayrıntılar için tablo 1'e bakın. |
Yük | ||
data.<key> | İsteğe bağlı, dize | Bu parametre, mesajın yükünün anahtar/değer çiftlerini belirtir. Anahtar/değer parametrelerinin sayısında herhangi bir sınırlama yoktur ancak toplam ileti boyutu sınırı 4000 bayttır. Örneğin, Android'de Anahtar, ayrılmış bir kelime ("from", "message_type" veya "google" veya "gcm" ile başlayan herhangi bir kelime) olmamalıdır. Bu tabloda tanımlanan kelimelerin hiçbirini kullanmayın ( |
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 başlığını hem de gövdeyi değerlendirmelidir. Aşağıdaki tabloda olası yanıtlar açıklanmaktadır.
Cevap | Tanım |
---|---|
200 | Mesaj başarıyla işlendi. Yanıt gövdesi mesajın durumu hakkında daha fazla ayrıntı içerecektir ancak formatı, isteğin JSON mu yoksa düz metin mi olduğuna bağlı olacaktır. Daha fazla ayrıntı için tablo 5'e bakın. |
400 | Yalnızca JSON istekleri için geçerlidir. İsteğin JSON olarak ayrıştırılamayacağını veya geçersiz alanlar içerdiğini (örneğin, sayının beklendiği yerde bir dize iletildiğini) belirtir. Kesin hata nedeni yanıtta açıklanmaktadır ve isteğin yeniden denenebilmesi için sorunun çözülmesi gerekir. |
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) gösterir. Gönderenin, yanıtta yer alan Retry-After başlığını dikkate alarak daha sonra yeniden denemesi gerekir. Uygulama sunucuları üstel gerilemeyi uygulamalıdır. |
Aşağıdaki tabloda, aşağı akış ileti yanıt gövdesindeki (JSON) alanlar listelenmektedir.
Parametre | Kullanım | Tanım |
---|---|---|
multicast_id | Gerekli, sayı | Çok noktaya yayın mesajını tanımlayan benzersiz kimlik (numara). |
success | Gerekli, sayı | Hatasız olarak işlenen iletilerin sayısı. |
failure | Gerekli, sayı | İşlenemeyen iletilerin sayısı. |
results | Gerekli, nesne dizisi | İşlenen mesajların durumunu temsil eden nesnelerin dizisi. Nesneler istekle aynı sırada listelenir (yani istekteki her kayıt kimliği için sonucu yanıtta aynı dizinde listelenir).
|
Parametre | Kullanım | Tanım |
---|---|---|
message_id | İsteğe bağlı, sayı | FCM'nin isteği başarıyla aldığı ve abone olunan tüm cihazlara teslim edilmeye çalışıldığı andaki konu mesajı kimliği. |
error | İsteğe bağlı, dize | Mesaj işlenirken oluşan hata. Olası değerler tablo 9'da bulunabilir. |
Parametre | Kullanım | Tanım |
---|---|---|
id | Gerekli, dize | Bu parametre, FCM'nin başarıyla işlendiği benzersiz mesaj kimliğini belirtir. |
registration_id | İsteğe bağlı, dize | Bu parametre, mesajın işlendiği ve gönderildiği istemci uygulamasının kayıt jetonunu belirtir. |
Parametre | Kullanım | Tanım |
---|---|---|
Error | Gerekli, dize | Bu parametre, alıcı için mesajın işlenmesi sırasında oluşan hata değerini belirtir. Ayrıntılar için tablo 9'a bakın. |
Aşağı akış mesajı hatası yanıt kodları
Aşağıdaki tablo, aşağı akış mesajları için hata yanıt kodlarını listelemektedir.
Hata | HTTP Kodu | Tavsiye edilen eylem |
---|---|---|
Eksik Kayıt Jetonu | 200 + hata:Eksik Kayıt | İsteğin bir kayıt belirteci içerip içermediğini kontrol edin (düz metin mesajındaki registration_id veya JSON'daki to veya registration_ids alanında). |
Geçersiz Kayıt Jetonu | 200 + hata:Geçersiz Kayıt | Sunucuya ilettiğiniz kayıt jetonunun formatını kontrol edin. İstemci uygulamasının Firebase Notifications'a kaydolurken aldığı kayıt jetonuyla eşleştiğinden emin olun. İlave karakterleri kesmeyin veya eklemeyin. |
Kayıtlı Olmayan Cihaz | 200 + hata: Kayıtlı Değil | Mevcut bir 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çersiz Paket Adı | İletinin, paket adı istekte iletilen değerle eşleşen bir kayıt belirtecine gönderildiğinden emin olun. |
Doğrulama hatası | 401 | Mesaj göndermek için kullanılan gönderen hesabının kimliği doğrulanamadı. Olası nedenler şunlardır:
|
Eşleşmeyen Gönderen | 200 + hata:Gönderen Kimliği Eşleşmiyor | Bir kayıt jetonu belirli bir gönderen grubuna bağlanır. Bir istemci uygulaması FCM'ye kaydolduğunda hangi gönderenlerin mesaj göndermesine izin verildiğini belirtmelidir. İstemci uygulamasına mesaj 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 doğru şekilde biçimlendirildiğini ve geçerli alanlar içerdiğini kontrol edin (ö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 olup olmadığını kontrol edin. |
Mesaj Çok Büyük | 200 + hata:MessageTooBig | Bir mesaja dahil edilen veri yükü verilerinin toplam boyutunun FCM sınırlarını aşmadığını kontrol edin: çoğu mesaj için 4096 bayt veya konulara yönelik mesajlar için 2048 bayt. Buna hem anahtarlar hem de değerler dahildir. |
Geçersiz Veri Anahtarı | 200 + hata: GeçersizVeriAnahtarı | Yük verilerinin, FCM tarafından dahili olarak kullanılan bir anahtar ( from , veya gcm veya google önüne eklenen herhangi bir değer gibi) içermediğini kontrol edin. Bazı kelimelerin ( collapse_key gibi) FCM tarafından da kullanıldığını ancak veri yükünde izin verildiğini, bu durumda veri yükü değerinin FCM değeri tarafından geçersiz kılınacağını unutmayın. |
Geçersiz Yaşam Süresi | 200 + hata:GeçersizTtl | time_to_live kullanılan değerin, 0 ile 2.419.200 (4 hafta) arasında saniye cinsinden bir süreyi temsil eden bir tam sayı olup olmadığını kontrol edin. |
Zaman aşımı | 5xx veya 200 + hatası: Mevcut değil | Sunucu isteği zamanında işleyemedi. Aynı isteği yeniden deneyin, ancak şunları yapmalısınız:
Soruna neden olan gönderenler kara listeye alınma riskiyle karşı karşıyadır. |
İç Sunucu Hatası | 500 veya 200 + hata:DahiliSunucuHatası | Sunucu, isteği işlemeye çalışırken bir hatayla karşılaştı. "Zaman Aşımı" bölümünde listelenen gereksinimleri izleyerek aynı isteği yeniden deneyebilirsiniz (yukarıdaki satıra bakın). Hata devam ederse lütfen Firebase desteğiyle iletişime geçin. |
Cihaz Mesaj Hızı Aşıldı | 200 + hata: CihazMesaj Oranı Aşıldı | Belirli bir cihaza gönderilen mesajların oranı çok yüksek. Bir Apple uygulaması APN 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 gerilemeyi kullanın. |
Konular Mesaj Hızı Aşıldı | 200 + hata: KonularMesajOran Aşıldı | Belirli bir konuya ilişkin abonelere mesaj gönderilme oranı çok yüksektir. Bu konu için gönderilen iletilerin sayısını azaltın ve göndermeyi yeniden denemek için üstel gerilemeyi kullanın. |
Geçersiz APN kimlik bilgileri | 200 + hata: GeçersizApnsKimlik Bilgileri | Gerekli APN kimlik doğrulama anahtarı yüklenmediğinden veya süresi dolduğundan, bir Apple cihazını hedef alan bir mesaj gönderilemedi. Geliştirme ve üretim kimlik bilgilerinizin geçerliliğini kontrol edin. |
Cihaz grubu yönetimi
Aşağıdaki tabloda, aygıt grupları oluşturmaya ve üye ekleme ve kaldırmaya ilişkin tuşlar listelenmektedir. Daha fazla bilgi için platformunuza ( iOS+ veya Android) yönelik kılavuza bakın.
Parametre | Kullanım | Tanım |
---|---|---|
operation | Gerekli, dize | Çalıştırma işlemi. Geçerli değerler, create , add ve remove . |
notification_key_name | Gerekli, dize | Oluşturulacak veya değiştirilecek aygıt grubunun kullanıcı tanımlı adı. |
notification_key | Gerekli ( create işlemi hariç, dize | Cihaz grubunun benzersiz tanımlayıcısı. Bu değer, başarılı bir create işlemine yanıt olarak döndürülür ve aygıt grubundaki sonraki tüm işlemler için gereklidir. |
registration_ids | Gerekli, dize dizisi | Eklenecek veya kaldırılacak cihaz belirteçleri. Bir cihaz grubundan mevcut tüm kayıt belirteçlerini kaldırırsanız FCM, cihaz grubunu siler. |