Bu dokümanda, uygulama sunucunuz, istemci uygulamaları ve Firebase Cloud Messaging (FCM) arasında mesaj aktarmak için kullanılan XMPP söz dizimi 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 aşağıdaki 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, yayın mesajları gönderme söz dizimi verilmiştir.
Aşağı akış XMPP mesajları (JSON)
Aşağıdaki tabloda, XMPP JSON mesajlarının hedefleri, seçenekleri 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, bir cihaz grubunun bildirim anahtarı veya tek bir konu olabilir (önüne |
|
condition |
İsteğe bağlı, dize | Bu parametre, mesaj hedefini belirleyen koşulların mantıksal ifadesini belirtir. Desteklenen koşul: Konu, "konularda "konunuz"" şeklinde biçimlendirilir. 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 bir şekilde tanımlar. |
|
collapse_key |
İsteğe bağlı, dize | Bu parametre, yayın devam ettirildiğinde yalnızca son ileti gönderilecek şekilde daraltılabilen bir ileti grubunu (ör. İletilerin gönderilme sırası garanti edilmez. Not: Herhangi bir zamanda en fazla 4 farklı daraltma anahtarına izin verilir. Bu, FCM'ün istemci uygulaması başına 4 farklı mesajı aynı anda saklayabileceği anlamına gelir. Bu sayıyı aşarsanız FCM'ün hangi 4 daraltma anahtarını saklayacağı garanti edilmez. |
|
priority |
İsteğe bağlı, dize | İletinin önceliğini ayarlar. Geçerli değerler "normal" ve "yüksek"tir. Apple platformlarında bunlar, APN'lerin 5 ve 10. önceliklerine 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 anında yayınlama gerekmediği sürece kullanılmalıdır. Normal öncelikli mesajlar, uygulama tarafından belirtilmeyen bir gecikmeyle alınabilir. Yüksek öncelikli olarak gönderilen mesajlar hemen gönderilir ve uygulama bir bildirim gösterebilir. |
|
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 (saniye cinsinden) tutulacağını belirtir. Desteklenen maksimum geçerlilik süresi 4 haftadır ve varsayılan değer 4 haftadır. Daha fazla bilgi için Mesajın geçerlilik süresini ayarlama başlıklı makaleyi inceleyin. |
|
dry_run |
İsteğe bağlı, boole | Bu parametre
|
|
Yük | |||
data |
İsteğe bağlı, nesne | Bu parametre, mesajın yükü için anahtar/değer çiftlerini belirtir. Örneğin, Apple platformlarında, mesaj APN'ler tarafından yayınlanıyorsa özel veri alanlarını temsil eder. FCM tarafından yayınlanıyorsa Android'de bu işlem, 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 kelimelerden hiçbirini kullanmayın ( Dize türünde değerler önerilir. Nesnelerdeki veya dize olmayan diğer veri türlerindeki (ör. tam sayılar veya boole değerleri) değerleri dizeye dönüştürmeniz gerekir. |
|
notification |
İsteğe bağlı, nesne | Bu parametre, bildirim yayının önceden tanımlanmış, kullanıcı tarafından görülebilen anahtar/değer çiftlerini belirtir. Ayrıntılar için bildirim yükü desteğine bakın. Bildirim mesajı ve veri mesajı seçenekleri hakkında daha fazla bilgi için
İleti türleri başlıklı makaleyi inceleyin. Bir bildirim yükü sağlanırsa veya Apple cihaza gönderilen bir mesaj için 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, Apple platformları 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 çalınacak ses.
İstemci uygulamasının ana paketindeki veya uygulamanın veri kapsayıcısının |
badge |
İsteğe bağlı, dize |
Ana ekran uygulama simgesinde bulunan rozetin değeri. Belirtilmemişse rozet değiştirilmez.
|
click_action |
İsteğe bağlı, dize |
Kullanıcının bildirimi tıklamasıyla ilişkili işlem.
APN'ler yükünde |
subtitle |
İsteğe bağlı, dize |
Bildirimin alt başlığı. |
body_loc_key |
İsteğe bağlı, dize |
Ana metni kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için uygulamanın dize kaynaklarındaki ana metin dizesinin anahtarı.
APN'ler yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzak Bildirimlerinizin İçeriğini Yerelleştirme başlıklı makaleleri inceleyin. |
body_loc_args |
İsteğe bağlı, JSON dizisi olarak dize |
Ana metni kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için
APN'ler yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzak Bildirimlerinizin İçeriğini Yerelleştirme başlıklı makaleleri inceleyin. |
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 uygulamanın dize kaynaklarındaki başlık dizesinin anahtarı.
APN'ler yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzak Bildirimlerinizin İçeriğini Yerelleştirme başlıklı makaleleri inceleyin. |
title_loc_args |
İsteğe bağlı, JSON dizisi olarak dize |
Başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için
APN'ler yükünde Daha fazla bilgi için Yük Anahtarı Referansı ve Uzak Bildirimlerinizin İçeriğini Yerelleştirme başlıklı makaleleri inceleyin. |
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). Uygulama, bu kanal kimliğine sahip bir bildirim alınmadan önce bu kanal kimliğiyle bir kanal oluşturmalıdır. İ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.
|
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ı. Belirtilmezse her istek yeni bir bildirim oluşturur. Belirtilirse ve aynı etikete sahip bir bildirim zaten gösteriliyorsa yeni bildirim, bildirim çekmecesinde mevcut bildirimin yerini alır. |
color |
İsteğe bağlı, dize |
Bildirimin simge rengi. |
click_action |
İsteğe bağlı, dize |
Kullanıcının bildirimi tıklamasıyla ilişkili işlem. Belirtiliyse kullanıcı bildirimi tıkladığında eşleşen bir intent filtresine sahip bir etkinlik başlatılır. |
body_loc_key |
İsteğe bağlı, dize |
Ana metni kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için uygulamanın dize kaynaklarındaki body dizesinin anahtarı. Daha fazla bilgi için Dize Kaynakları başlıklı makaleyi inceleyin. |
body_loc_args |
İsteğe bağlı, JSON dizisi olarak dize |
Ana metni kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için Daha fazla bilgi için Biçimlendirme ve Stil başlıklı makaleyi inceleyin. |
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 uygulamanın dize kaynaklarındaki başlık dizesinin anahtarı. Daha fazla bilgi için Dize Kaynakları başlıklı makaleyi inceleyin. |
title_loc_args |
İsteğe bağlı, JSON dizisi olarak dize |
Başlık metnini kullanıcının mevcut yerelleştirmesine göre yerelleştirmek için Daha fazla bilgi için Biçimlendirme ve Stil başlıklı makaleyi inceleyin. |
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 simgesinde kullanılacak URL. |
click_action |
İsteğe bağlı, dize |
Kullanıcının bildirimi tıklamasıyla ilişkili işlem. Tüm URL değerleri için HTTPS gereklidir. |
Aşağı akış XMPP mesaj yanıtını yorumlama
Aşağıdaki tabloda, yayın XMPP mesajı yanıtında görünen alanlar listelenmiştir.
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 bir şekilde tanımlar. Değer, ilişkilendirilmiş mesajı benzersiz şekilde tanımlayan bir dizedir. |
message_type |
Zorunlu, dize | Bu parametre, FCM'den uygulama sunucusuna gönderilen bir Değer |
error |
İsteğe bağlı, dize | Bu parametre, yayın mesajıyla ilgili bir hatayı belirtir. 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 hakkında 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, yayın mesajları için hata yanıt kodları listelenmiştir.
Hata | XMPP kodu | Önerilen işlem |
---|---|---|
Kayıt jetonu eksik | INVALID_JSON |
İsteğin bir kayıt jetonu (düz metin mesajındaki registration_id alanında veya JSON'daki to ya da registration_ids alanında) içerdiğini kontrol edin. |
Geçersiz APNs Kaydı | INVALID_JSON |
iOS kayıtlarında, 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. Bu değerin, istemci uygulamasının FCM'e kaydolurken aldığı kayıt jetonuyla eşleştiğinden emin olun. Metni kısaltmayın veya ek karakter eklemeyin. |
Kayıtlı Olmayan Cihaz | DEVICE_UNREGISTERED |
Mevcut bir kayıt jetonu, aşağıdakiler de dahil olmak üzere çeşitli senaryolarda geçerliliğini yitirebilir:
|
Eşleşmeyen Gönderen | SENDER_ID_MISMATCH |
Kayıt jetonu belirli bir gönderen grubuna bağlıdır. Bir istemci uygulaması FCM için kaydolurken hangi gönderenlerin ileti göndermesine izin verildiğini belirtmelidir. İstemci uygulamasına mesaj 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 emin olun (örneğin, doğru veri türünün iletildiğinden emin olun). |
Mesaj çok büyük | INVALID_JSON |
Bir iletiye dahil edilen yük verilerinin toplam boyutunun FCM sınırlarını aşmadığından emin olun: Çoğu ileti için 4096 bayt veya konulara gönderilen iletiler için 2048 bayt. Buna hem anahtarlar hem de değerler dahildir. |
Geçersiz Veri Anahtarı | INVALID_JSON |
Yük verisinin, FCM tarafından dahili olarak kullanılan bir anahtar (from , gcm veya google ön ekiyle başlayan herhangi bir değer gibi) içermediğinden emin olun. Bazı kelimelerin (collapse_key gibi) FCM tarafından da 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 | INVALID_JSON |
time_to_live içinde 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ın doğru biçimlendirildiğinden emin olun. Ayrıntılar için tablo 6'ya bakın. |
Zaman aşımı | SERVICE_UNAVAILABLE |
Sunucu, isteği zamanında işleyemedi. Aynı isteği tekrar deneyin ancak şunu yapmanız gerekir:
Not: Sorunlara neden olan gönderenler kara listeye alınabilir. |
Dahili Sunucu Hatası | INTERNAL_SERVER_
|
Sunucu, isteği işlemeye çalışırken bir hatayla karşılaştı. "Tüme zaman aşımı" bölümünde listelenen koşulları uygulayarak aynı isteği tekrar deneyebilirsiniz (yukarıdaki satıra bakın). |
Cihaz Mesaj Sıklığı Aşıldı | DEVICE_MESSAGE_RATE |
Belirli bir cihaza gönderilen mesajların oranı çok yüksek. Bu cihaza gönderilen mesaj sayısını azaltın ve bu cihaza göndermeyi hemen tekrar denemeyin. |
Topics Mesaj Sıklığı Aşıldı | TOPICS_MESSAGE_RATE |
Belirli bir konuya abone olan kullanıcılara gönderilen mesajların oranı çok yüksek. Bu konu için gönderilen mesaj sayısını azaltın ve göndermeyi hemen tekrar denemeyin. |
Bağlantı Boşaltma | CONNECTION_DRAINING |
Bağlantı zayıf olduğu için mesaj işlenemedi. Bunun nedeni, FCM'ün yük dengeleme yapmak için düzenli olarak bir bağlantıyı kapatması gerekmesidir. Mesajı başka bir XMPP bağlantısı üzerinden tekrar deneyin. |
Geçersiz APNs Kimlik Bilgileri | INVALID_APNS_CREDENTIAL |
Gerekli APN kimlik doğrulama anahtarı yüklenmediği veya geçerlilik 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ğrulama başarısız oldu | AUTHENTICATION_FAILED |
Harici push hizmetleriyle kimlik doğrulama yapılamadı. Doğru web push sertifikalarını kullanıp kullanmadığınızı kontrol edin. |
Yukarı akış mesajı söz dizimi
Yukarı akış mesajı, istemci uygulamasının uygulama sunucusuna gönderdiği bir mesajdır. Şu anda yalnızca XMPP yayın mesajları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 dizelerindeki alanlar açıklanmaktadır.
Parametre | Kullanım | Açıklama |
---|---|---|
from |
Zorunlu, dize | Bu parametre, iletiyi 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, mesajın benzersiz kimliğini belirtir. |
data |
İsteğe bağlı, dize | Bu parametre, mesajın yükü için anahtar/değer çiftlerini belirtir. |
ACK mesajı gönderme
Aşağıdaki tabloda, uygulama sunucusunun aldığı bir yayın mesajına yanıt olarak FCM adresine göndermesi beklenen ACK yanıtı açıklanmaktadır.
Parametre | Kullanım | Açıklama |
---|---|---|
to |
Zorunlu, dize | Bu parametre, yanıt mesajının alıcısını belirtir. Değer, yayın mesajını gönderen istemci uygulamasının kayıt jetonu olmalıdır. |
message_id |
Zorunlu, dize | Bu parametre, yanıtın hangi mesaj için gönderildiğini belirtir. Değer, ilgili yayın öncesi mesajdaki message_id değeri olmalıdır. |
message_type |
Zorunlu, dize | Bu parametre, bir uygulama sunucusundan CCS'ye gönderilen bir ack mesajını belirtir.
Yayınlanan mesajlar için her zaman ack olarak ayarlanmalıdır. |
FCM sunucu mesajları (XMPP)
Bu, FCM'ten bir uygulama sunucusuna gönderilen bir iletidir. FCM tarafından uygulama sunucusuna gönderilen başlıca mesaj türleri şunlardır:
- Denetleme: CCS tarafından oluşturulan bu mesajlar, uygulama sunucusunun işlem yapması gerektiğini gösterir.
Aşağıdaki tabloda, CCS'nin bir uygulama sunucusuna gönderdiği mesajlara dahil edilen 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 adresinden gönderilen kontrol mesajının türünü belirtir. Şu anda yalnızca |