Bu belge, uygulama sunucunuzdan istemci uygulamalarına Firebase Cloud Messaging aracılığıyla gelen mesajlarla gönderir.
Eski HTTP protokolünü kullanırken uygulama sunucusu, tüm HTTP isteklerini bu uç noktaya yönlendirmelidir:
https://fcm.googleapis.com/fcm/send
Kullanılabilir parametreler ve seçenekler aşağıdaki geniş kategorileri kapsar:
Aşağı akış mesajı söz dizimi
Bu bölümde, aşağı akış mesajlarını göndermek ve yorumları Firebase Cloud Messaging tarafından gönderilen HTTP yanıtları.
Aşağı akış HTTP mesajları (JSON)
Aşağıdaki tabloda HTTP JSON mesajlarının hedefleri, seçenekleri ve yükü listelenmiştir.
Tablo 1. Aşağı akış HTTP mesajları (JSON) için hedefler, seçenekler ve yük.
Parametre | Kullanım | Açıklama | |
---|---|---|---|
Hedefler | |||
to |
İsteğe bağlı, dize |
Bu parametre, iletinin alıcısını belirtir.
Bu değer; cihazın kayıt jetonu, cihaz grubunun
tek bir konu (öneki
|
|
registration_ids | İsteğe bağlı, dize dizisi |
Bu parametre, bir çoklu yayın mesajının alıcısını belirtir. birden fazla kayıt jetonuna gönderilir.
Değer,
çoklu yayın mesajı. Dizide en az 1, en fazla 1.000 olmalıdır
kayıt jetonlarıdır. Tek bir cihaza mesaj göndermek için şunu kullanın:
Ç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 belirler. Desteklenen koşul: "Konunuz" olarak biçimlendirilmiş konu inceleyebilirsiniz. Bu değeri 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, belirtmek için |
|
Seçenekler | |||
collapse_key |
İsteğe bağlı, dize | Bu parametre bir ileti grubunu tanımlar (ö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. Bunun anlamı, FCM, istemci uygulaması başına aynı anda 4 farklı mesaj depolayabilir. Şu durumda: aşılırsa FCM tarafından hangi 4 daraltma anahtarının tutulacağı garanti edilmez. |
|
priority |
İsteğe bağlı, dize | İletinin önceliğini ayarlar. Geçerli değerler "normal"dir ve "yüksek" olarak derecelendirilir. Apple platformlarında bunlar, APN 5 ve 10 önceliklerine karşılık gelir. Varsayılan olarak, bildirim mesajları yüksek öncelikli ve veri mesajlarıyla gönderilir normal öncelikte gönderilir. Normal öncelik, istemci uygulamasının pil tüketimi ve hemen teslimat gerekmiyorsa kullanılmalıdır. Uygulama, normal öncelikli mesajları şu şekilde alabilir: belirtilmemiş. 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 |
|
mutable_content |
İsteğe bağlı, JSON boole | Apple platformlarında, bu alanı temsil etmek için
APNs yükünde |
|
time_to_live |
İsteğe bağlı, sayı | Bu parametre, mesajın FCM depolama alanında ne kadar süreyle (saniye cinsinden) saklanması gerektiğini belirtir emin olun. 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 gerekir. | |
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" veya "gcm" gibi). Bu tabloda tanımlanan kelimelerin hiçbirini kullanmayın
(ör. Dize türlerindeki değerlerin kullanılması önerilir. Değerleri nesnelerdeki veya diğer dize olmayan veri türlerindeki değerleri dönüştürmeniz gerekir (ör. tam sayılar veya boole'ler) dize. |
|
notification |
İsteğe bağlı, nesne | Bu parametre, parametrenin ön tanımlı, kullanıcı tarafından görülebilen anahtar/değer çiftlerini
bildirim yükünü azaltır. 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
bkz.
Mesaj türleri. Bildirim yükü sağlanırsa veya
Apple'a gönderilen mesaj için content_available seçeneği true olarak ayarlandı
mesaj APN'ler üzerinden, aksi takdirde
FCM.
|
Bildirim yükü desteği
Aşağıdaki tablolarda, önceden tanımlanmış tuşlar, iOS ve Android için bildirim mesajları oluşturmak amacıyla kullanılabilir.
Tablo 2a. iOS — Bildirim mesajları için tuşlar
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 paketindeki 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 |
Uygulamanın dize kaynaklarında bulunan ve Gövde metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirin.
APNs yükünde Görüntüleyin Yük Anahtarı Referansı ve Daha fazlası için Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme ekleyebilirsiniz. |
body_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Şurada biçim belirteçleri yerine kullanılacak değişken dize değerleri:
APNs yükünde Görüntüleyin Yük Anahtarı Referansı ve Daha fazlası için Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme ekleyebilirsiniz. |
title_loc_key |
İsteğe bağlı, dize |
Uygulama dizesi kaynaklarında kullanılan başlık dizesinin anahtarı başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirin.
APNs yükünde Görüntüleyin Yük Anahtarı Referansı ve Daha fazlası için Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme ekleyebilirsiniz. |
title_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Şurada biçim belirteçleri yerine kullanılacak değişken dize değerleri:
APNs yükünde Görüntüleyin Yük Anahtarı Referansı ve Daha fazlası için Uzaktan Bildirimlerinizin İçeriğini Yerelleştirme ekleyebilirsiniz. |
Tablo 2b. Android — Bildirim mesajları için tuşlar
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 bir özellik). Bu kanal kimliğine sahip herhangi bir bildirimin etkinleştirilmesi için uygulamanın bu kanal kimliğiyle bir kanal oluşturması gerekir. alındı. İstekte bu kanal kimliğini göndermezseniz veya sağlanan kanal kimliği henüz gönderilmezse FCM uygulaması tarafından oluşturulan kanal kimliği, uygulama manifestinde belirtilen kanal kimliğini kullanır. |
icon |
İsteğe bağlı, dize |
Bildirimin simgesi.
Çekilebilir kaynak için bildirim simgesini |
sound |
İsteğe bağlı, dize |
Cihaz bildirimi aldığında çalacak ses.
|
tag |
İsteğe bağlı, dize |
Bildirimdeki mevcut bildirimlerin yerine kullanılan tanımlayıcı çekmecesi. Belirtilmezse her istek yeni bir bildirim oluşturur. Belirtilmişse ve aynı etikete sahip bir bildirim zaten bulunuyorsa gösterilirse, yeni bildirim, bildirim çekmecesi. |
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. Belirtilmişse eşleşen intent filtresine sahip bir etkinlik Kullanıcı bildirimi tıkladığında |
body_loc_key |
İsteğe bağlı, dize |
Uygulamanın dize kaynaklarında bulunan ve Gövde metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirin. Görüntüleyin Dize Kaynakları bölümünde bulabilirsiniz. |
body_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Şurada biçim belirteçleri yerine kullanılacak değişken dize değerleri:
Görüntüleyin Biçimlendirme ve Stil başlıklı makaleyi inceleyin. |
title_loc_key |
İsteğe bağlı, dize |
Uygulama dizesi kaynaklarında kullanılan başlık dizesinin anahtarı başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirin. Görüntüleyin Dize Kaynakları bölümünde bulabilirsiniz. |
title_loc_args |
İsteğe bağlı, dize olarak JSON dizisi |
Şurada biçim belirteçleri yerine kullanılacak değişken dize değerleri:
Görüntüleyin Biçimlendirme ve Stil başlıklı makaleyi inceleyin. |
Tablo 2c. Web (JavaScript) - Bildirim mesajları için anahtarlar
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 hedefler, seçenekler ve yük için söz dizimi yalın biçimde listelenmiştir aşağı akış HTTP mesajları için de geçerlidir.
Tablo 3. Aşağı akış düz metin HTTP mesajları için hedefler, seçenekler ve yük.
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ına ilişkin bir sınırlama yoktur. ancak 4.096 baytlık toplam ileti boyutu sınırı vardır. Örneğin, Android'de Anahtar, ayrılmış bir kelime ("from", "message_type" veya
"google" veya "gcm" gibi). Bu tabloda tanımlanan kelimelerin hiçbirini kullanmayın
(ör. |
Aşağı akış mesaj yanıtını yorumlama
Uygulama sunucusu hem ileti yanıtı üstbilgisini hem de gövdesini değerlendirmelidir. FCM tarafından gönderilen yanıtın yorumlanması için kullanılır. Aşağıdaki tablo olası yanıtları tanımlamaktadır.
Tablo 4. Aşağı akış HTTP mesajı yanıtı üstbilgisi.
Yanıt | Açıklama |
---|---|
200 | İleti başarıyla işlendi. Yanıt gövdesinde daha fazla içerik yer alacak hakkında ayrıntılı bilgi verir ancak mesajın biçimi, isteğin JSON veya düz metindi. 5. tabloya bakın. inceleyebilirsiniz. |
400 | Yalnızca JSON istekleri için geçerlidir. İsteğin JSON olarak ayrıştırılamadığını veya geçersiz içerdiğini gösterir alanları (örneğin, bir sayının beklendiği dizenin iletilmesi). Tam yanıtta hatanın nedeni açıklanır ve sorunun çözülmesi gerekir ve istek yeniden denenebilir. |
401 | Gönderen hesabın kimliği doğrulanırken bir hata oluştu. |
5xx | 500-599 aralığındaki hatalar (örneğin, 500 veya 503),
isteği işlemeye çalışırken FCM arka ucunda dahili bir hata olması veya
sunucu geçici olarak kullanılamıyorsa (örneğin, zaman aşımları nedeniyle). Gönderen
Retry-After
tıklayın. Uygulama sunucuları üstel geri çekme uygulamalıdır. |
Aşağıdaki tabloda, aşağı akış ileti yanıtı gövdesindeki alanlar listelenmiştir (JSON).
Tablo 5. Aşağı akış HTTP ileti yanıtı gövdesi (JSON).
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. İlgili içeriği oluşturmak için kullanılan
nesneler istekle aynı sırada listelenir (ör. her bir kayıt için
kimliğini içeriyorsa, sonucu yanıtta aynı dizinde listelenir.
|
Tablo 6. Konu mesajı HTTP yanıt gövdesi (JSON).
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 teslimat yapmayı dener. |
error |
İsteğe bağlı, dize | İleti işlenirken hata oluştu. Olası değerler tablo 9'da bulunabilir. |
Tablo 7. Aşağı akış HTTP ileti yanıtı gövdesi için başarılı yanıt (Düz Metin).
Parametre | Kullanım | Açıklama |
---|---|---|
id |
Zorunlu, dize | Bu parametre, başarıyla işlenen benzersiz ileti kimliğini (FCM) belirtir. |
registration_id |
İsteğe bağlı, dize | Bu parametre, mesajın gönderildiği istemci uygulamasının kayıt jetonunu belirtir işlenip gönderilir. |
Tablo 8. Aşağı akış HTTP iletisi yanıt gövdesi için hata yanıtı (Düz Metin).
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.
Tablo 9. Aşağı akış mesajı hata yanıtı kodları.
Hata | HTTP Kodu | Önerilen işlem |
---|---|---|
Kayıt Jetonu Eksik | 200 + hata:EksikKayıt | İsteğin bir kayıt jetonu içerdiğinden emin olun (
Düz kısa mesajda veya to içinde registration_id
veya registration_ids alanını kullanın). |
Geçersiz Kayıt Jetonu | 200 + error:InvalidRegistration | Sunucuya ilettiğiniz kayıt jetonunun biçimini kontrol edin. Emin olun istemci uygulamasının Firebase'e kaydolurken aldığı kayıt jetonuyla eşleşir Bildirimler. 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 | İletinin, paket adı istekte iletilen değerle eşleşir. |
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 + error:MismatchSenderId | Kayıt jetonu belirli bir gönderen grubuna bağlıdır. Bir istemci uygulaması kaydolduğunda FCM için hangi gönderenlerin ileti göndermesine izin verildiğini belirtmelidir. Bunlardan birini kullanmalısınız kimlik doğrulaması ekleyebilirsiniz. Farklı bir gönderen için 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 emin olun. (örneğin, doğru veri türünün iletildiğinden 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 dahil edilen yük verilerinin toplam boyutunun FCM sınırlarını aşmaz: çoğu ileti için 4.096 bayt veya iletilerde 2.048 bayt. ileti dizisine göz atın. Bu, hem anahtarlar ve değerler. |
Geçersiz Veri Anahtarı | 200 + hata:
. GeçersizVeri Anahtarı |
Yük verilerinin bir anahtar (from ,
veya gcm ya da herhangi bir değer
ön eki google olan), FCM tarafından dahili olarak kullanılır. Bazı kelimelerin (ör. collapse_key )
aynı zamanda FCM tarafından da kullanılır, ancak
yük değerinin FCM değeri tarafından geçersiz kılınması durumunda. |
Geçersiz Geçerlilik Süresi | 200 + error:GeçersizTtl | time_to_live öğesinde kullanılan değerin, şunu temsil eden bir tam sayı olduğundan emin olun:
0 ile 2.419.200 (4 hafta) arasında saniye cinsinden süre. |
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ı. Yeniden deneyebilirsiniz "Zaman aşımı" bölümünde listelenen gereksinimlerin ardından aynı istek (yukarıdaki satıra bakın). Hata devam ediyorsa lütfen Firebase destek ekibiyle iletişime geçin. |
Cihaz İletisi Hızı Aşıldı | 200 + hata:
CihazMesaj Oranı . Aşıldı |
Belirli bir cihaza gönderilen mesajların oranı çok yüksek. Apple uygulaması Mesajları APNs sınırlarını aşan bir hızda gönderir. Bu hata mesajını alabilir Azaltın bu cihaza gönderilen mesajların sayısı ve eksponansiyel geri yükleme kullanma tekrar deneyin. |
Konular İçin İleti Hızı Aşıldı | 200 + hata:
Konu Mesaj Hızı . Aşıldı |
Belirli bir konunun abonelere gönderilen mesajların oranı çok yüksek. Azaltın Bu konu için gönderilen ileti sayısı ve eksponansiyel geri yükleme kullanma tekrar deneyin. |
APNs kimlik bilgileri geçersiz | 200 + hata:
GeçersizApnsCredential |
Gerekli APN'ler nedeniyle Apple cihazı hedefleyen bir mesaj gönderilemedi Kimlik doğrulama anahtarı yüklenmedi veya anahtarın süresi dolmuş. Geliştirmenizin geçerliliğini kontrol etme ve üretim kimlik bilgileri. |
Cihaz grubu yönetimi
Aşağıdaki tabloda, cihaz grupları oluşturma anahtarları listelenmektedir ve üye ekleyip çıkarmayı deneyin. Daha fazla bilgi için hakkında bilgi edindiniz iOS+ veya Android.
Tablo 10. Cihaz grubu yönetimi anahtarları.
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 hariç, dize |
Cihaz grubunun benzersiz tanımlayıcısı. Bu değer
başarılı bir create için yanıtta döndürülür
ve
cihaz grubundaki sonraki tüm işlemler için gereklidir. |
registration_ids |
Zorunlu, dize dizisi | Eklenecek veya kaldırılacak cihaz jetonları. Mevcut tüm reklam birimlerini bir cihaz grubundaki kayıt jetonları ise FCM, cihaz grubunu siler. |