了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

Sunucu ortamınız ve FCM

Firebase Cloud Messaging'in sunucu tarafı iki bileşenden oluşur:

  • Google tarafından sağlanan FCM arka ucu .
  • Cloud Functions for Firebase veya Google tarafından yönetilen diğer bulut ortamları gibi, uygulama sunucunuz veya sunucu mantığınızın çalıştığı diğer güvenilir sunucu ortamınız .

Uygulama sunucunuz veya güvenilir sunucu ortamınız, mesajları kullanıcıların cihazlarında çalışan istemci uygulamalarına yönlendiren FCM arka ucuna mesaj istekleri gönderir.

Güvenilir sunucu ortamı için gereksinimler

Uygulama sunucusu ortamınız aşağıdaki ölçütleri karşılamalıdır:

  • FCM arka ucuna uygun şekilde biçimlendirilmiş mesaj istekleri gönderebilir.
  • Üstel geri alma kullanarak istekleri işleyebilir ve yeniden gönderebilir.
  • Sunucu yetkilendirme kimlik bilgilerini ve müşteri kayıt belirteçlerini güvenli bir şekilde saklayabilir.
  • XMPP protokolü için (kullanılıyorsa), sunucunun gönderdiği her mesajı benzersiz bir şekilde tanımlamak için mesaj kimlikleri oluşturabilmesi gerekir (FCM HTTP arka ucu, mesaj kimlikleri oluşturur ve bunları yanıtta döndürür). XMPP mesaj kimlikleri, gönderen kimliği başına benzersiz olmalıdır.

Bir sunucu seçeneği belirleme

FCM sunucularıyla nasıl etkileşim kuracağınıza karar vermeniz gerekecek: Firebase Admin SDK'yı veya ham protokolleri kullanarak. Popüler programlama dillerindeki desteği ve kimlik doğrulama ve yetkilendirme işlemlerine yönelik kullanışlı yöntemleri nedeniyle, Firebase Admin SDK önerilen yöntemdir.

FCM sunucularıyla etkileşim seçenekleri aşağıdakileri içerir:

  • Node , Java , Python , C# ve Go desteğine sahip Firebase Admin SDK.
  • Protokol seçeneklerinin en günceli olan FCM HTTP v1 API'si , daha güvenli yetkilendirme ve esnek çapraz platform mesajlaşma yetenekleriyle (Firebase Admin SDK, bu protokolü temel alır ve kendisine özgü tüm avantajları sağlar). Yeni özellikler genellikle yalnızca HTTP v1 API'sine eklendiğinden, çoğu kullanım durumu için bu API'yi kullanmanızı öneririz.
  • Eski HTTP protokolü. Yeni projelerin eski protokol yerine FCM v1 HTTP API'sini benimsemesi şiddetle tavsiye edilir.
  • Eski XMPP sunucu protokolü. Yeni projelerin eski protokol yerine FCM v1 HTTP API'sini benimsemesi şiddetle tavsiye edilir.

FCM için Firebase Yönetici SDK'sı

Admin FCM API, arka uçla kimlik doğrulamayı gerçekleştirir ve mesaj göndermeyi ve konu aboneliklerini yönetmeyi kolaylaştırır. Firebase Admin SDK ile şunları yapabilirsiniz:

  • Tek tek cihazlara mesaj gönder
  • Bir veya daha fazla konuyla eşleşen konulara ve koşul ifadelerine mesaj gönderin.
  • Konulara ve konulara abone olun ve abonelikten çıkın
  • Farklı hedef platformlara uyarlanmış mesaj yükleri oluşturun

Admin Node.js SDK, cihaz gruplarına mesaj göndermek için yöntemler sağlar.

Firebase Admin SDK'yı ayarlamak için Firebase Admin SDK'yı Sunucunuza Ekleme bölümüne bakın. Halihazırda bir Firebase projeniz varsa SDK'yı Ekle ile başlayın. Ayrıca, projeniz için Cloud Messaging ayarlar sayfasında Cloud Messagin API'yi etkinleştirdiğinizden emin olun. Ardından, Firebase Admin SDK yüklendikten sonra gönderme istekleri oluşturmak için mantık yazmaya başlayabilirsiniz.

FCM Sunucu Protokolleri

Şu anda FCM şu ham sunucu protokollerini sağlamaktadır:

Uygulama sunucunuz bu protokolleri ayrı ayrı veya art arda kullanabilir. Birden çok platforma mesaj göndermek için en güncel ve en esnek olduğundan, mümkün olan her yerde FCM HTTP v1 API'si önerilir. Gereksinimleriniz cihazlardan sunucuya yukarı akış mesajlaşmayı içeriyorsa, XMPP protokolünü uygulamanız gerekir.

XMPP mesajlaşması, HTTP mesajlaşmasından aşağıdaki şekillerde farklılık gösterir:

  • Yukarı/Dosya mesajları
    • HTTP: Yalnızca aşağı akış, buluttan cihaza.
    • XMPP: Yukarı akış ve aşağı akış (cihazdan buluta, buluttan cihaza).
  • Mesajlaşma (eşzamanlı veya eşzamansız)
    • HTTP: Eşzamanlı. Uygulama sunucuları, iletileri HTTP POST istekleri olarak gönderir ve bir yanıt bekler. Bu mekanizma senkronizedir ve yanıt alınana kadar gönderenin başka bir mesaj göndermesini engeller.
    • XMPP: Eşzamansız. Uygulama sunucuları, kalıcı XMPP bağlantıları üzerinden tüm cihazlarına tam hat hızında mesaj gönderir/alır. XMPP bağlantı sunucusu, onay veya hata bildirimlerini (özel ACK ve NACK JSON kodlu XMPP mesajları biçiminde) eşzamansız olarak gönderir.
  • JSON
    • HTTP: HTTP POST olarak gönderilen JSON mesajları.
    • XMPP: XMPP mesajlarında kapsüllenmiş JSON mesajları.
  • Düz Metin
    • HTTP: HTTP POST olarak gönderilen Düz Metin mesajları.
    • XMPP: Desteklenmiyor.
  • Çoklu kayıt jetonlarına çok noktaya yayın aşağı akış gönderme.
    • HTTP: JSON mesaj biçiminde desteklenir.
    • XMPP: Desteklenmiyor.

HTTP sunucusu protokolünü uygulama

Bir mesaj göndermek için uygulama sunucusu, bir HTTP başlığı ve JSON anahtar/değer çiftlerinden oluşan bir HTTP gövdesi ile bir POST isteği gönderir. Başlık ve gövde seçenekleriyle ilgili ayrıntılar için bkz. Uygulama Sunucusu Oluştur İstek Gönder

XMPP sunucu protokolünü uygulama

FCM mesajları için JSON yükü, aşağıdaki istisnalar dışında HTTP protokolüne benzer:

  • Birden fazla alıcı için destek yoktur.
  • FCM, gerekli olan message_id alanını ekler. Bu kimlik, bir XMPP bağlantısındaki mesajı benzersiz bir şekilde tanımlar. FCM'den gelen ACK veya NACK, uygulama sunucularından FCM'ye gönderilen bir mesajı tanımlamak için message_id kullanır. Bu nedenle, bu message_id yalnızca benzersiz ( gönderen kimliği başına) olması değil, aynı zamanda her zaman mevcut olması önemlidir.
  • XMPP, FCM ile kalıcı bir bağlantıya yetki vermek için sunucu anahtarını kullanır. Daha fazla bilgi için İstek Gönderme Yetkilendirme bölümüne bakın.

Normal FCM mesajlarına ek olarak, JSON nesnesindeki message_type alanı tarafından belirtilen kontrol mesajları gönderilir. Değer, "ack" veya "nack" veya "kontrol" olabilir (aşağıdaki biçimlere bakın). Bilinmeyen bir message_type olan herhangi bir FCM mesajı, sunucunuz tarafından göz ardı edilebilir.

Uygulama sunucunuzun FCM'den aldığı her cihaz mesajı için bir ACK mesajı göndermesi gerekir. Asla bir NACK mesajı göndermesi gerekmez. Bir mesaj için bir ACK göndermezseniz, mesajın süresi önce dolmadığı sürece FCM, bir sonraki yeni XMPP bağlantısı kurulduğunda mesajı yeniden gönderir.

FCM ayrıca her sunucudan cihaza mesaj için bir ACK veya NACK gönderir. İkisini de almazsanız, işlemin ortasında TCP bağlantısının kapatıldığı ve sunucunuzun mesajları yeniden göndermesi gerektiği anlamına gelir. Ayrıntılar için Akış Kontrolüne bakın.

Tüm mesaj parametrelerinin listesi için Protokol Referansına bakın.

İstek biçimi

Faydalı mesaj — bildirim mesajı

İşte bir bildirim mesajı için bir XMPP kıtası:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
     "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
  }
  </gcm>
</message>

Faydalı mesaj — veri mesajı

İşte bir uygulama sunucusundan FCM'ye giden JSON mesajını içeren bir XMPP kıtası:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
  }
  </gcm>
</message>

Yanıt formatı

Bir FCM yanıtının üç olası biçimi olabilir. İlki normal bir 'acck' mesajıdır. Ancak yanıt bir hata içerdiğinde, mesajın alabileceği aşağıda açıklanan 2 farklı biçim vardır.

ACK mesajı

İşte FCM'den uygulama sunucusuna gönderilen ACK/NACK mesajını içeren bir XMPP kıtası:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

NA mesajı

Bir NACK hatası, message_type durum mesajının "nack" olduğu normal bir XMPP mesajıdır. Bir NACK mesajı şunları içerir:

  • Bir NACK hata kodu.
  • Bir NACK hata açıklaması.

Aşağıda bazı örnekler verilmiştir.

Kötü kayıt:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationToken",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

Geçersiz JSON:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

Cihaz Mesaj Hızı Aşıldı:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

NACK hata kodlarının tam listesi için Sunucu Referansına bakın. Aksi belirtilmedikçe, bir NACKed mesajı yeniden denenmemelidir. Beklenmeyen NACK hata kodları, INTERNAL_SERVER_ERROR ile aynı şekilde ele alınmalıdır.

Stanza hatası

Ayrıca belirli durumlarda dörtlük hatası da alabilirsiniz. Bir stanza hatası şunları içerir:

  • Stanza hata kodu.
  • Stanza hata açıklaması (serbest metin).

Örneğin:

<message id="3" type="error" to="123456789@fcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

Kontrol mesajları

Periyodik olarak, FCM'nin yük dengelemeyi gerçekleştirmek için bir bağlantıyı kapatması gerekir. Bağlantıyı kapatmadan önce FCM, bağlantının boşaltılmakta olduğunu ve yakında kapatılacağını belirtmek için bir CONNECTION_DRAINING mesajı gönderir. "Boşaltma", bir bağlantıya gelen mesajların akışını kapatmak, ancak boru hattında zaten olan her şeyin devam etmesine izin vermek anlamına gelir. Bir CONNECTION_DRAINING mesajı aldığınızda, gerekirse yeni bir bağlantı açarak hemen başka bir FCM bağlantısına mesaj göndermeye başlamalısınız. Bununla birlikte, orijinal bağlantıyı açık tutmalı ve bağlantı üzerinden gelebilecek mesajları almaya devam etmelisiniz (ve bunları KABUL ETME)—FCM, hazır olduğunda bir bağlantının kapatılmasını başlatır.

CONNECTION_DRAINING mesajı şöyle görünür:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING şu anda desteklenen tek control_type .

Akış kontrolü

FCM'ye gönderilen her mesaj, bir ACK veya NACK yanıtı alır. Bu yanıtlardan birini almayan iletiler beklemede kabul edilir. Bekleyen mesaj sayısı 100'e ulaşırsa, uygulama sunucusu yeni mesaj göndermeyi durdurmalı ve şekil 1'de gösterildiği gibi FCM'nin mevcut bekleyen mesajlardan bazılarını onaylamasını beklemelidir:

FCM ile uygulama sunucusu arasındaki kontrol akışının ayrıntılı diyagramı

Şekil 1. Mesaj/onay akışı.

Tersine, uygulama sunucusunun aşırı yüklenmesini önlemek için, çok fazla onaylanmamış mesaj varsa FCM göndermeyi durdurur. Bu nedenle, uygulama sunucusu, gelen mesajların sürekli akışını sürdürmek için mümkün olan en kısa sürede, istemci uygulamasından FCM yoluyla alınan yukarı akış mesajlarını "ACK" etmelidir. Yukarıda bahsedilen bekleyen mesaj limiti, bu ACK'ler için geçerli değildir. Bekleyen mesaj sayısı 100'e ulaşsa bile uygulama sunucusu, yeni yukarı akış mesajlarının teslimini engellememek için FCM'den alınan mesajlar için ACK'ler göndermeye devam etmelidir.

ACK'ler yalnızca bir bağlantı bağlamında geçerlidir. Bir mesajın ACK'lanmasından önce bağlantı kapatılırsa, uygulama sunucusu FCM'nin tekrar ACK'lamadan önce yukarı akış mesajını yeniden göndermesini beklemelidir. Benzer şekilde, bağlantı kapatılmadan önce FCM'den ACK/NACK alınmayan bekleyen tüm mesajlar yeniden gönderilmelidir.