Bu belge, uygulama sunucunuz, istemci uygulamalarınız ve Firebase Cloud Messaging (FCM) arasında mesaj iletmek için kullanılan XMPP söz dizimine ilişkin bir referans sağlar. Uygulama sunucunuzun şu uç noktalara bağlanması gerekir:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
Mevcut parametreler ve seçenekler şu kategorilere girer:
- Aşağı akış mesajı sözdizimi
- Aşağı akış mesajı hatası yanıt kodları
- Yukarı akış mesajı sözdizimi
- FCM kontrol mesajları
Aşağı akış mesajı sözdizimi
Bu bölümde aşağı yönlü mesajların gönderilmesine ilişkin sözdizimi verilmektedir.
Aşağı akış XMPP mesajları (JSON)
Aşağıdaki tabloda XMPP JSON iletilerine ilişkin hedefler, seçenekler ve veriler listelenmektedir.
Parametre | Kullanım | Tanım | |
---|---|---|---|
Hedef | |||
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 | |
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: | |
Seçenekler | |||
message_id | Gerekli, dize | Bu parametre bir XMPP bağlantısındaki bir mesajı benzersiz şekilde tanımlar. | |
collapse_key | İsteğe bağlı, dize | Bu parametre, dağıtım devam ettirildiğinde yalnızca son mesajın gönderilmesini sağlayacak şekilde daraltılabilen bir mesaj grubunu (örneğin, Mesajların gönderilme sırasının garantisi yoktur. 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 . | |
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 anahtar/değer çiftlerini belirtir. Örneğin, Apple platformlarında mesaj APN'ler tarafından teslim ediliyorsa özel veri alanlarını temsil eder. FCM tarafından teslim edilirse 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, Apple platformları 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ğinin Yerelleştirilmesi 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ğinin Yerelleştirilmesi 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ış XMPP mesaj yanıtını yorumlama
Aşağıdaki tabloda, aşağı akış XMPP ileti yanıtında görünen alanlar listelenmektedir.
Parametre | Kullanım | Tanım |
---|---|---|
from | Gerekli, dize | Bu parametre bu yanıtı kimin gönderdiğini belirtir. Değer, istemci uygulamasının kayıt belirtecidir. |
message_id | Gerekli, dize | Bu parametre bir XMPP bağlantısındaki bir mesajı benzersiz şekilde tanımlar. Değer, ilişkili mesajı benzersiz şekilde tanımlayan bir dizedir. |
message_type | Gerekli, dize | Bu parametre, FCM'den uygulama sunucusuna gönderilen bir Değer |
error | İsteğe bağlı, dize | Bu parametre, aşağı akış 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 hataya ilişkin açıklayıcı bilgiler sağlar. message_type nack olduğunda ayarlanır. |
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 | XMPP kodu | Tavsiye edilen eylem |
---|---|---|
Eksik Kayıt Jetonu | INVALID_JSON | İ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 APN Kaydı | INVALID_JSON | iOS kayıtları için istemciden gelen kayıt isteğinin geçerli bir APN belirteci ve uygulama kimliği içerdiğini kontrol edin. |
Geçersiz Kayıt Jetonu | BAD_REGISTRATION | Sunucuya ilettiğiniz kayıt jetonunun formatını kontrol edin. İstemci uygulamasının FCM'ye kaydolurken aldığı kayıt jetonuyla eşleştiğinden emin olun. İlave karakterleri kesmeyin veya eklemeyin. |
Kayıtlı Olmayan Cihaz | DEVICE_UNREGISTERED | Mevcut bir kayıt jetonunun geçerliliği, aşağıdakiler de dahil olmak üzere çeşitli senaryolarda sona erebilir:
|
Eşleşmeyen Gönderen | SENDER_ID_MISMATCH | 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 | INVALID_JSON | 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). |
Mesaj Çok Büyük | INVALID_JSON | 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ı | INVALID_JSON | Yük verilerinin, FCM tarafından dahili olarak kullanılan bir anahtar ( from , 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ındığını unutmayın. |
Geçersiz Yaşam Süresi | INVALID_JSON | 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. |
Hatalı ACK mesajı | BAD_ACK | Yeniden denemeden önce ack mesajının doğru şekilde biçimlendirildiğini kontrol edin. 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 yeniden deneyin, ancak şunları yapmalısınız:
Not: Soruna neden olan gönderenlerin kara listeye alınma riski vardır. |
İç Sunucu Hatası | INTERNAL_SERVER_ | 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). |
Cihaz Mesaj Hızı Aşıldı | DEVICE_MESSAGE_RATE | Belirli bir cihaza gönderilen mesajların oranı çok yüksek. Bu cihaza gönderilen mesajların sayısını azaltın ve bu cihaza göndermeyi hemen yeniden denemeyin. |
Konular Mesaj Hızı Aşıldı | TOPICS_MESSAGE_RATE | 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 hemen yeniden göndermeyi denemeyin. |
Bağlantı Boşaltma | CONNECTION_DRAINING | Bağlantı tükendiği için mesaj işlenemedi. Bunun nedeni, FCM'nin yük dengelemeyi gerçekleştirmek için periyodik olarak bir bağlantıyı kapatması gerekmesidir. Mesajı başka bir XMPP bağlantısı üzerinden yeniden deneyin. |
Geçersiz APN Kimlik Bilgileri | INVALID_APNS_CREDENTIAL | Gerekli APN kimlik doğrulama anahtarı yüklenmediğinden veya süresi dolduğundan, iOS cihazını hedef alan 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ğrulaması yapılamadı. Doğru web push sertifikalarını kullanıp kullanmadığınızı kontrol edin. |
Yukarı akış mesajı sözdizimi
Yukarı akış mesajı, istemci uygulamasını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 dörtlüğündeki alanlar açıklanmaktadır.
Parametre | Kullanım | Tanım |
---|---|---|
from | Gerekli, dize | Bu parametre mesajı kimin gönderdiğini belirtir. Değer, istemci uygulamasının kayıt belirtecidir. |
category | Gerekli, dize | Bu parametre, mesajı gönderen istemci uygulamasının uygulama paketi adını belirtir. |
message_id | Gerekli, dize | Bu parametre mesajın benzersiz kimliğini belirtir. |
data | İsteğe bağlı, dize | Bu parametre, mesajın yükünün anahtar/değer çiftlerini belirtir. |
ACK mesajı gönderme
Aşağıdaki tablo, uygulama sunucusunun aldığı bir yukarı akış mesajına yanıt olarak uygulama sunucusunun FCM'ye göndermesinin beklendiği ACK yanıtını açıklamaktadır.
Parametre | Kullanım | Tanım |
---|---|---|
to | Gerekli, dize | Bu parametre bir yanıt mesajının alıcısını belirtir. Değer, yukarı akış mesajını gönderen istemci uygulamasının kayıt belirteci olmalıdır. |
message_id | Gerekli, dize | Bu parametre, yanıtın hangi mesaja yönelik olduğunu belirtir. Değer, karşılık gelen yukarı akış mesajındaki message_id değeri olmalıdır. |
message_type | Gerekli, dize | Bu parametre, bir uygulama sunucusundan CCS'ye gönderilen bir ack mesajını belirtir. Yukarı akış mesajları için her zaman ack olarak ayarlanmalıdır. |
FCM sunucu mesajları (XMPP)
Bu, FCM'den bir uygulama sunucusuna gönderilen bir mesajdır. FCM'nin uygulama sunucusuna gönderdiği başlıca mesaj türleri şunlardır:
- Kontrol: CCS tarafından oluşturulan bu mesajlar, uygulama sunucusundan eylem yapılması gerektiğini gösterir.
Aşağıdaki tabloda CCS'nin bir uygulama sunucusuna gönderdiği mesajlarda bulunan alanlar açıklanmaktadır.
Parametre | Kullanım | Tanım |
---|---|---|
Ortak alan | ||
message_type | Gerekli, 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 |