Bu dokümanda, mesajları uygulama sunucunuz, istemci uygulamalarınız ve Firebase Cloud Messaging (FCM) arasında iletmek için kullanılan XMPP söz dizimine yönelik bir referans sağlanmaktadır. Uygulama sunucunuz şu uç noktalara bağlanmalıdır:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
Kullanılabilir parametreler ve seçenekler şu kategorilere ayrılır:
- Aşağı akış mesajı söz dizimi
- Aşağı akış mesajı hata yanıtı kodları
- Yukarı akış mesajı söz dizimi
- FCM kontrol mesajları
Aşağı akış mesajı söz dizimi
Bu bölümde, aşağı akış mesajlarını göndermek için kullanılan söz dizimi verilmiştir.
Aşağı akış XMPP mesajları (JSON)
Aşağıdaki tabloda XMPP JSON mesajları için hedefler, seçenekler ve yük listelenmiştir.
Parametre | Kullanım | Açıklama | |
---|---|---|---|
Hedef | |||
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 ( |
|
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: |
|
Seçenekler | |||
message_id |
Zorunlu, dize | Bu parametre, XMPP bağlantısındaki bir mesajı benzersiz şekilde tanımlar. |
|
collapse_key |
İsteğe bağlı, dize | Bu parametre, teslim devam ettirildiğinde yalnızca son mesajın gönderilmesi için daraltılabilen bir mesaj grubunu (ör. Mesajların hangi sırayla gönderileceği konusunda garanti verilmez. 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, APN 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. |
|
dry_run |
İsteğe bağlı, boole | Bu parametre,
|
|
Yük | |||
data |
İsteğe bağlı, nesne | Bu parametre, mesaj yükünün anahtar/değer çiftlerini belirtir. Örneğin, Apple platformlarında mesaj APN'ler aracılığıyla teslim ediliyorsa özel veri alanlarını temsil eder. FCM tarafından yayınlanıyorsa 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, Apple platformları 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ış XMPP mesajı yanıtını yorumlama
Aşağıdaki tabloda, aşağı akış XMPP mesaj yanıtında görünen alanlar listelenmektedir.
Parametre | Kullanım | Açıklama |
---|---|---|
from |
Zorunlu, dize | Bu parametre, bu yanıtı kimin gönderdiğini belirtir. Değer, istemci uygulamasının kayıt jetonudur. |
message_id |
Zorunlu, dize | Bu parametre, XMPP bağlantısındaki bir mesajı benzersiz şekilde tanımlar. Değer, ilgili mesajı benzersiz şekilde tanımlayan bir dizedir. |
message_type |
Zorunlu, dize | Bu parametre, FCM'den uygulama sunucusuna bir Değer |
error |
İsteğe bağlı, dize | Bu parametre, aşağı akış mesajıyla ilgili bir hatayı belirtir. Politika, message_type nack olduğunda ayarlanır. Ayrıntılar için tablo 4'e bakın. |
error_description |
İsteğe bağlı, dize | Bu parametre, hata için açıklayıcı bilgiler sağlar. message_type , nack olduğunda ayarlanır. |
Aşağı akış mesajı hata yanıtı kodları
Aşağıdaki tabloda, aşağı akış mesajları için hata yanıtı kodları listelenmektedir.
Hata | XMPP kodu | Önerilen işlem |
---|---|---|
Kayıt Jetonu Eksik | INVALID_JSON |
İ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 APNs Kaydı | INVALID_JSON |
iOS kayıtları için istemciden gelen kayıt isteğinin geçerli bir APNs jetonu ve uygulama kimliği içerdiğinden emin olun. |
Geçersiz Kayıt Jetonu | BAD_REGISTRATION |
Sunucuya ilettiğiniz kayıt jetonunun biçimini kontrol edin. İstemci uygulamasının FCM'ye kaydolurken aldığı kayıt jetonuyla eşleştiğinden emin olun. Kırpmayın veya fazladan karakter eklemeyin. |
Kayıtlı Olmayan Cihaz | DEVICE_UNREGISTERED |
Mevcut bir kayıt jetonunun geçerliliği, aşağıdakiler gibi çeşitli durumlarda sona erebilir:
|
Gönderen Eşleşmiyor | SENDER_ID_MISMATCH |
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 | INVALID_JSON |
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. |
Mesaj Çok Büyük | INVALID_JSON |
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, konulara mesaj gönderilmesi için bu boyut 2.048 bayttır. Buna hem anahtarlar hem de değerler dahildir. |
Geçersiz Veri Anahtarı | INVALID_JSON |
Yük verilerinin, FCM tarafından dahili olarak kullanılan bir anahtar (ör. from , gcm veya 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 | INVALID_JSON |
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. |
Hatalı ACK mesajı | BAD_ACK |
Tekrar denemeden önce ack mesajın doğru şekilde biçimlendirildiğinden emin olun. Ayrıntılar için 6. tablo'ya bakın. |
Zaman aşımı | SERVICE_UNAVAILABLE |
Sunucu isteği zamanında işleyemedi. Aynı isteği yeniden deneyin, ancak şunları yapmanız gerekir:
Not: Soruna neden olan gönderenler kara listeye alınma riskiyle karşı karşıyadır. |
Dahili Sunucu Hatası | INTERNAL_SERVER_
|
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). |
Cihaz İletisi Hızı Aşıldı | DEVICE_MESSAGE_RATE |
Belirli bir cihaza gönderilen mesajların oranı çok yüksek. Bu cihaza gönderilen iletilerin sayısını azaltın ve bu cihaza göndermeyi hemen tekrarlamayın. |
Konular İçin İleti Hızı Aşıldı | TOPICS_MESSAGE_RATE |
Belirli bir konunun abonelere gönderilen mesajların oranı çok yüksek. Bu konu için gönderilen ileti sayısını azaltın ve göndermeyi hemen tekrar denemeyin. |
Bağlantı Boşaltılıyor | CONNECTION_DRAINING |
Bağlantı boşaltıldığı için ileti işlenemedi. Bunun nedeni, yük dengeleme gerçekleştirmek için FCM'nin düzenli olarak bir bağlantıyı kapatması gerekmesidir. Mesajı başka bir XMPP bağlantısı üzerinden tekrar göndermeyi deneyin. |
Geçersiz APNs Kimlik Bilgileri | INVALID_APNS_CREDENTIAL |
Gerekli APNs kimlik doğrulama anahtarı yüklenmediği veya süresi dolduğu için iOS cihazı hedefleyen bir mesaj gönderilemedi. Geliştirme ve üretim kimlik bilgilerinizin geçerliliğini kontrol edin. |
Kimlik Doğrulanamadı | AUTHENTICATION_FAILED |
Harici push hizmetleriyle kimlik doğrulanamadı. Doğru web push sertifikalarını kullanıp kullanmadığınızı kontrol edin. |
Yukarı akış mesajı söz dizimi
Yukarı akış mesajı, istemci uygulamanın uygulama sunucusuna gönderdiği bir mesajdır. Şu anda yalnızca XMPP yukarı akış mesajlaşmasını desteklemektedir. İstemci uygulamalarından mesaj gönderme hakkında daha fazla bilgi için platformunuzun belgelerine bakın.
Yukarı akış XMPP mesajını yorumlama
Aşağıdaki tabloda, istemci uygulamalarından gelen yukarı akış mesaj isteklerine yanıt olarak FCM tarafından oluşturulan XMPP ifadesindeki alanlar açıklanmaktadır.
Parametre | Kullanım | Açıklama |
---|---|---|
from |
Zorunlu, dize | Bu parametre, mesajı kimin gönderdiğini belirtir. Değer, istemci uygulamasının kayıt jetonudur. |
category |
Zorunlu, dize | Bu parametre, mesajı gönderen istemci uygulamasının uygulama paketi adını belirtir. |
message_id |
Zorunlu, dize | Bu parametre iletinin benzersiz kimliğini belirtir. |
data |
İsteğe bağlı, dize | Bu parametre, mesaj yükünün anahtar/değer çiftlerini belirtir. |
ACK mesajı gönderme
Aşağıdaki tabloda, uygulama sunucusunun aldığı bir yukarı akış mesajına yanıt olarak uygulama sunucusunun FCM'ye göndermesi beklenen ACK yanıtı açıklanmaktadır.
Parametre | Kullanım | Açıklama |
---|---|---|
to |
Zorunlu, dize | Bu parametre, yanıt iletisinin alıcısını belirtir. Değer, yukarı akış mesajını gönderen istemci uygulamasının kayıt jetonu olmalıdır. |
message_id |
Zorunlu, dize | Bu parametre, yanıtın hangi mesaja yönelik olduğunu belirtir. Değer, ilgili yukarı akış mesajındaki message_id değeri olmalıdır. |
message_type |
Zorunlu, dize | Bu parametre, bir uygulama sunucusundan CCS'ye bir ack mesajı belirtir.
Yukarı akış mesajları için her zaman ack olarak ayarlanmalıdır. |
FCM sunucu mesajları (XMPP)
Bu, FCM'den uygulama sunucusuna gönderilen bir mesajdır. FCM'nin uygulama sunucusuna gönderdiği birincil mesaj türleri şunlardır:
- Kontrol: CCS tarafından oluşturulan bu mesajlar, uygulama sunucusundan işlem yapılması gerektiğini belirtir.
Aşağıdaki tabloda, CCS'nin uygulama sunucusuna gönderdiği mesajlarda yer alan alanlar açıklanmaktadır.
Parametre | Kullanım | Açıklama |
---|---|---|
Ortak alan | ||
message_type |
Zorunlu, dize | Bu parametre, mesajın türünü belirtir: kontrol.
|
control_type |
İsteğe bağlı, dize | Bu parametre, FCM'den gönderilen kontrol mesajının türünü belirtir. Şu anda yalnızca |