Firebase Cloud Messaging XMPP protokolü

Bu belge, geçmek için kullanılan XMPP söz dizimine ilişkin bir referans Uygulama sunucunuz, istemci uygulamalarınız ve Firebase Cloud Messaging (FCM) arasındaki mesajlar. Uygulama sunucunuz şu uç noktalara bağlanmalıdır:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

Kullanılabilen parametreler ve seçenekler şu kategorilere ayrılır:

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 hedefleri, seçenekler ve yükü listelenmektedir mesaj.

Tablo 1 Aşağı akış XMPP mesajları (JSON) için hedefler, seçenekler ve yük.

Parametre Kullanım Açıklama
Hedef
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 /topics/) bilgileri gösterilir. Birden çok konuya e-posta göndermek için condition parametresinden yararlanın.

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: &&, ||. En fazla iki operatör sayısı desteklenir.

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 bir ileti grubunu tanımlar (ör. collapse_key: "Updates Available") daraltılabilir. Böylece yalnızca teslim devam ettirildiğinde son ileti gönderilir. Bu şekilde, gönderme işleminin birden fazla cihaz tekrar çevrimiçi olduğunda veya dozdan çıktığında aynı mesajların birçoğu.

Mesajların hangi sırayla gönderileceği konusunda garanti verilmez.

Not: Herhangi bir zamanda en fazla 4 farklı daraltma anahtarına izin verilir. Bunun anlamı şudur: FCM, aynı anda 4 farklı depolama alanı mesaj sayısını artırır. Şu durumda: aşmazsanız hangi 4 daraltma anahtarının FCM'ye uyarlanacağına ilişkin bir garanti yoktur. koruyacak.

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, APN'lerde content-available konumunu göstermek için bu alanı kullanın. yük. true olarak ayarlanan bir bildirim veya mesaj gönderildiğinde, Etkin olmayan istemci uygulaması uyandırılır ve mesaj, APN'ler üzerinden sessiz bir şekilde gönderilir. bildirimi almalısınız (FCM aracılığıyla değil). Şurada sessiz bildirimlerin mevcut olduğunu unutmayın: APN'lerin teslim edileceği garanti edilmez ve APN'ler kullanıcı gibi faktörlere bağlı olabilir. Düşük Güç Modu'nu açma, uygulamadan çıkmaya zorlama gibi işlemler yapabilir. Android'de, veri mesajları varsayılan uygulamadır. Chrome'da şu anda desteklenmiyor.

mutable_content İsteğe bağlı, JSON boole

Apple platformlarında, bu alanı temsil etmek için APNs yükünde mutable-content. Bir bildirim gönderildiğinde ve bu ayarlandığında true olarak değiştirirseniz bildirimin içeriği, görüntülenmeden önce değiştirilebilir. Bildirim Hizmeti uygulama uzantısı. Bu parametre Android ve web için yoksayılır.

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.

dry_run İsteğe bağlı, boole

Bu parametre true olarak ayarlandığında, geliştiricilerin bir isteğidir.

false, varsayılan değerdir.

Yük
data İsteğe bağlı, nesne

Bu parametre, mesaj yükünün anahtar/değer çiftlerini belirtir.

Örneğin, data:{"score":"3x1"}: ile

Apple platformlarında mesaj APN'ler aracılığıyla teslim ediliyorsa özel veri alanlarını temsil eder. Eğer FCM tarafından teslim ediliyor, AppDelegate application:didReceiveRemoteNotification: hücresinde anahtar/değer sözlüğü olarak gösterilir.

Android'de bu, 3x1 dize değerine sahip score adında ekstra bir amaç ile sonuçlanır.

Anahtar, ayrılmış bir kelime ("from", "message_type" veya "google" veya "gcm" gibi). Bu tabloda tanımlanan kelimelerin hiçbirini kullanmayın (ör. collapse_key).

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, bildirim yükü. Ayrıntılı bilgi için Bildirim yükü desteğine bakın. Okuyucu Gelirleri Yöneticisi'ni 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ış Apple platformları ve Android için bildirim mesajları oluşturmak amacıyla kullanılabilen anahtarlar.

Tablo 2a. Apple — 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 Library/Sounds klasörü. Bkz. iOS Geliştirici Kitaplığı'na göz atın.

badge İsteğe bağlı, dize

Ana ekrandaki uygulama simgesindeki rozetin değeri.

Belirtilmezse rozet değiştirilmez.

0 olarak ayarlanırsa rozet kaldırılır.

click_action İsteğe bağlı, dize

Kullanıcının bildirimi tıklamasıyla ilişkilendirilen işlem.

APNs yükünde category değerine karşılık gelir.

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 loc-key değerine karşılık gelir.

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: Gövde metninibody_loc_key kullanıcının mevcut yerelleştirmesi.

APNs yükünde loc-args değerine karşılık gelir.

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 title-loc-key değerine karşılık gelir.

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: title_loc_key kullanarak başlık metnini kullanıcının mevcut yerelleştirmesi.

APNs yükünde title-loc-args değerine karşılık gelir.

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, uygulama manifestinde belirtilen kanal kimliğini kullanır.

icon İsteğe bağlı, dize

Bildirimin simgesi.

Çekilebilir kaynak için bildirim simgesini myicon olarak ayarlar myicon İstekte bu anahtarı göndermezseniz FCM, uygulama manifestinizde belirtilen başlatıcı simgesini gösterir.

sound İsteğe bağlı, dize

Cihaz bildirimi aldığında çalacak ses.

"default" veya bir ses kaynağının dosya adını destekler paketlenmiş halidir. Ses dosyaları /res/raw/ içinde bulunmalıdır.

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, #rrggbb biçiminde ifade edilen simge rengi.

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övde metninibody_loc_key kullanıcının mevcut yerelleştirmesi.

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: title_loc_key kullanarak başlık metnini kullanıcının mevcut yerelleştirmesi.

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ış XMPP mesajı yanıtını yorumlama

Aşağıdaki tabloda, aşağı akış XMPP mesaj yanıtında görünen alanlar listelenmektedir.

Tablo 3 Aşağı akış iletisi XMPP yanıt gövdesi.

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, şuradan gelen bir ack veya nack mesajını belirtir: FCM'yi uygulama sunucusuna bağlayabilirsiniz.

Değer nack olarak ayarlanırsa uygulama sunucusu Hata bilgilerini almak için error ve error_description.

error İsteğe bağlı, dize Bu parametre, aşağı akış mesajıyla ilgili bir hatayı belirtir. Bu ayar, message_type nack. 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. Ayarlandı message_type nack olduğunda.

Aşağı akış mesajı hata yanıtı kodları

Aşağıdaki tabloda, aşağı akış mesajları için hata yanıtı kodları listelenmektedir.

Tablo 4 Aşağı akış mesajı hata yanıtı kodları.

Hata XMPP kodu Önerilen işlem
Kayıt Jetonu Eksik INVALID_JSON İsteğin bir kayıt jetonu içerdiğinden emin olun ( Düz kısa mesajda veya to içinde registration_id veya JSON'de registration_ids alanına ait olmalıdır).
Geçersiz APNs Kaydı INVALID_JSON iOS kayıtları için, istemciden gelen kayıt isteğinde bir geçerli APNs jetonu ve uygulama kimliği.
Geçersiz Kayıt Jetonu BAD_REGISTRATION Sunucuya ilettiğiniz kayıt jetonunun biçimini kontrol edin. Emin olun istemci uygulamasının FCM'ye kaydolurken aldığı kayıt jetonuyla eşleşir. Şunları yapmayın: veya başka karakterler ekleyin.
Kayıtlı Olmayan Cihaz DEVICE_UNREGISTERED Mevcut bir kayıt jetonunun geçerliliği, aşağıdakiler gibi çeşitli durumlarda sona erebilir:
  • İstemci uygulamasının FCM kaydını iptal etmesi durumunda.
  • İstemci uygulamasının kaydı otomatik olarak silinirse (bu durum, Kullanıcı uygulamayı kaldırır. Örneğin iOS'te, APN'ler APNs jetonunun geçersiz olduğunu bildirdi.
  • Kayıt jetonunun süresi dolarsa (örneğin, Google, ya da cihazlar için APNs jetonunun süresi dolmuşsa).
  • İstemci uygulaması güncellenmişse ancak yeni sürüm, mesajları alacak şekilde yapılandırılmamışsa.
Tüm bu durumlarda, bu kayıt jetonunu uygulamadan kaldırın posta göndermek için kullanmayacağınız anlamına gelir.
Gönderen Eşleşmiyor SENDER_ID_MISMATCH 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 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 mesaja dahil edilen yük verilerinin toplam boyutunun FCM sınırlarını aşmamalıdır: çoğu ileti için 4096 bayt veya ileti için 2048 bayt ileti dizisine göz atın. Bu, hem anahtarlar ve değerler.
Geçersiz Veri Anahtarı INVALID_JSON Yük verilerinin bir anahtar (from, gcm veya herhangi bir değer ön ek olarak google ile başlar). Bazı kelimelerin (ör. collapse_key) bunlar FCM tarafından da kullanılır ancak yükte kullanılabilir. 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, şunu temsil eden bir tam sayı olduğundan emin olun: 0 ile 2.419.200 (4 hafta) arasında saniye cinsinden süre.
Hatalı ACK mesajı BAD_ACK Tekrar denemeden önce ack mesajın doğru şekilde biçimlendirildiğinden emin olun. Görüntüleyin tablo 6'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:

  • Yeniden deneme mekanizmanıza eksponansiyel geri yükleme uygulayın. (ör. bir saniye beklediyseniz önce tekrar denemeden önce en az iki saniye, ardından dört saniye vb. bekleyin). Birden fazla mesaj gönderiyorsanız her birini rastgele bir miktarda ilave ederek ayrı ayrı geciktirin Böylece tüm mesajlar için aynı anda yeni bir istek gönderilmesini önleyebilirsiniz.
  • İlk yeniden deneme gecikmesi bir saniye olarak ayarlanmalıdır.

Not: Soruna neden olan gönderenler kara listeye alınma riskiyle karşı karşıyadır.

Dahili Sunucu Hatası INTERNAL_SERVER_
ERROR
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).
Cihaz İletisi Hızı Aşıldı DEVICE_MESSAGE_RATE
_EXCEEDED
Belirli bir cihaza gönderilen mesajların oranı çok yüksek. Azaltın bu cihaza gönderilen iletilerin sayısı ve bu cihaza göndermeyi hemen tekrar deneme.
Konular İçin İleti Hızı Aşıldı TOPICS_MESSAGE_RATE
_EXCEEDED
Belirli bir konunun abonelere gönderilen mesajların oranı çok yüksek. Azaltın ve bu konu için gönderilen ileti sayısını hemen göndermeyin.
Bağlantı Boşaltılıyor CONNECTION_DRAINING Bağlantı boşaltıldığı için ileti işlenemedi. Bunun nedeni, düzenli aralıklarla, FCM'nin yük dengeleme gerçekleştirmek için bir bağlantıyı kapatması gerekir. Mesajı tekrar göndermeyi dene başka bir XMPP bağlantısı.
Geçersiz APNs Kimlik Bilgileri INVALID_APNS_CREDENTIAL Gerekli APN'ler nedeniyle iOS 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.
Kimlik Doğrulanamadı AUTHENTICATION_FAILED Harici push hizmetleriyle kimlik doğrulanamadı. doğru web push sertifikaları.

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. Görüntüleyin daha fazla bilgi edinmek için platformunuzun belgelerini istemci uygulamalarından ileti gönderme hakkında bilgi sağlar.

Yukarı akış XMPP mesajını yorumlama

Aşağıdaki tabloda, oluşturulan XMPP başlığındaki alanlar açıklanmaktadır istemci uygulamalarından gelen yukarı akış mesaj isteklerine yanıt olarak FCM tarafından sağlanır.

Tablo 5 Yukarı yayın XMPP mesajları.

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 göndermesi beklenen ACK yanıtı açıklanmaktadır. FCM'ye gönderilen yanıtlarla ilgili olarak uygulama sunucusunun aldığı yukarı akış mesajı.

Tablo 6 Yukarı yayın XMPP mesaj yanıtı.

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 şöyle olmalıdır: İlgili yukarı akış mesajındaki message_id değeri.
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 tarafından gönderilen başlıca mesaj türleri uygulama sunucusuna gönderir:

  • Kontrol: CCS tarafından oluşturulan bu mesajlar, uygulama sunucusundan işlem gerekiyor.

Aşağıdaki tabloda, mesajların CCS'sine dahil edilen alanlar açıklanmaktadır. bir uygulama sunucusuna gönderilir.

Tablo 7 FCM kontrol mesajları (XMPP).

Parametre Kullanım Açıklama
Ortak alan
message_type Zorunlu, dize

Bu parametre, mesajın türünü belirtir: kontrol.

control olarak ayarlandığında, mesajdacontrol_type Kontrol mesajı türünü ifade eder.

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 CONNECTION_DRAINING desteklenmektedir. Bu kontrol mesajı FCM tarafından gönderilir bu adımları uygulayarak yük dengeleme işlemi gerçekleştirebilirsiniz. Bağlantı azaldıkça artık mesaj gönderilmeyecek Ardışık düzendeki mevcut mesajların bağlantıya gönderilmesine izin verilir işlenmeye devam eder.