Google is committed to advancing racial equity for Black communities. See how.
Bu sayfa, Cloud Translation API ile çevrilmiştir.
Switch to English

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ı .

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

Güvenilir sunucu ortamı için gereksinimler

Uygulama sunucusu ortamınız aşağıdaki kriterleri karşılamalıdır:

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

Bir sunucu seçeneği seçme

FCM sunucularıyla etkileşim kurmanın bir yolunu belirlemeniz gerekir: Firebase Admin SDK'yı veya ham protokolleri kullanarak. Popüler programlama dillerinde sağladığı destek ve kimlik doğrulama ve yetkilendirme işlemlerine yönelik kolaylık yöntemleri nedeniyle Firebase Admin SDK önerilen yöntemdir.

FCM sunucularıyla etkileşim için seçenekler şunları içerir:
  • Node , Java , Python , C # ve Go desteğine sahip Firebase Admin SDK.
  • Protokol seçeneklerinin en güncel olanı olan FCM HTTP v1 API , daha güvenli yetkilendirme ve esnek platformlar arası mesajlaşma yetenekleriyle (Firebase Admin SDK bu protokole dayanır ve tüm doğal avantajlarını sağlar).
  • Eski HTTP protokolü.
  • XMPP sunucu protokolü. İstemci uygulamalarınızdan yukarı akış mesajlaşmasını kullanmak istiyorsanız, XMPP kullanmanız gerektiğini unutmayın.

FCM için Firebase Admin SDK

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:

  • Bireysel cihazlara mesaj gönderin
  • Bir veya daha fazla konuyla eşleşen konulara ve koşul ifadelerine mesaj gönderin.
  • Konulara abone olun ve cihazların aboneliğini iptal edin
  • Farklı hedef platformlara göre 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ı kurmak için Firebase Admin SDK'yı Sunucunuza Ekleme konusuna bakın. Zaten bir Firebase projeniz varsa SDK Ekle ile başlayın. 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 birlikte kullanabilir. Birden çok platforma mesaj göndermek için en güncel ve en esnek olduğu için, FCM HTTP v1 API'sı mümkün olan her yerde önerilir. Gereksinimleriniz cihazlardan sunucuya yukarı akış mesajlarını içeriyorsa, XMPP protokolünü uygulamanız gerekir.

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

  • Yukarı / Aşağı mesajlar
    • HTTP: Yalnızca aşağı akış, buluttan cihaza.
    • XMPP: Yukarı akış ve aşağı akış (aygıttan buluta, buluttan aygıta).
  • Mesajlaşma (senkron veya asenkron)
    • HTTP: Eşzamanlı. Uygulama sunucuları mesajları HTTP POST istekleri olarak gönderir ve bir yanıt bekler. Bu mekanizma eşzamanlıdır ve gönderenin yanıt alınana kadar 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, eşzamansız olarak (özel ACK ve NACK JSON kodlu XMPP mesajları biçiminde) onay veya hata bildirimleri 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.
  • Çok noktaya yayın aşağı akış, birden çok kayıt jetonuna gönderilir.
    • HTTP: JSON mesaj biçiminde desteklenir.
    • XMPP: Desteklenmiyor.

HTTP sunucusu prosedürü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 yayınlar. Başlık ve gövde seçenekleriyle ilgili ayrıntılar için bkz. Uygulama Sunucusu Oluşturma İstekleri Gönderme

XMPP sunucusu prosedürü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, mesajı bir XMPP bağlantısında benzersiz şekilde tanımlar. FCM'den 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) değil, her zaman mevcut olması da önemlidir.
  • XMPP, FCM'ye kalıcı bağlantı yetkisi vermek için sunucu anahtarını kullanır. Daha fazla bilgi için Gönderme İsteklerini Yetkilendirme konusuna bakın.

Normal FCM mesajlarına ek olarak, JSON nesnesindeki message_type alanıyla gösterilen kontrol mesajları gönderilir. Değer, "ack" veya "nack" veya "kontrol" olabilir (aşağıdaki biçimlere bakın). message_type bilinmeyen 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 ACK göndermezseniz, FCM, mesajın süresi önce sona ermediği sürece, bir sonraki yeni XMPP bağlantısı kurulduğunda bunu yeniden gönderir.

FCM ayrıca her sunucudan cihaza mesaj için bir ACK veya NACK gönderir. İkisini de almazsanız, bu 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 bir listesi için Protokol Referansına bakın.

İstek biçimi

Yüklü mesaj - bildirim mesajı

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

<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>

Yüklü mesaj - veri mesajı

Bir uygulama sunucusundan FCM'ye giden JSON mesajını içeren bir XMPP standardı:

<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 biçimi

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

ACK mesajı

FCM'den uygulama sunucusuna ACK / NACK mesajını içeren bir XMPP standardı:

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

NACK mesajı

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.

Hatalı kayıt:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationId",
    "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 Oranı 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 aynı şekilde ele alınmalıdır.

Stanza hatası

Ayrıca belirli durumlarda bir stanza 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ı

Yük dengeleme gerçekleştirmek için FCM'nin düzenli aralıklarla 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ın kesilmesi, ancak boru hattında halihazırda olanın devam etmesine izin verilmesi anlamına gelir. Bir CONNECTION_DRAINING mesajı aldığınızda, hemen başka bir FCM bağlantısına mesaj göndermeye başlamalı ve gerekirse yeni bir bağlantı açmalısınız. Bununla birlikte, orijinal bağlantıyı açık tutmalı ve bağlantı üzerinden gelebilecek mesajları almaya devam etmelisiniz (ve bunları ACK) —FCM, hazır olduğunda bir bağlantı başlatmayı kapatır.

CONNECTION_DRAINING mesajı şuna benzer:

<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 bir NACK yanıtı alır. Bu yanıtlardan birini almayan mesajlar beklemede kabul edilir. Bekleyen mesaj sayısı 100'e ulaşırsa, uygulama sunucusu yeni mesajlar göndermeyi bırakmalı ve FCM'nin şekil 1'de gösterildiği gibi mevcut bekleyen mesajların bazılarını onaylamasını beklemelidir:

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

Tersine, uygulama sunucusunun aşırı yüklenmesini önlemek için FCM, çok fazla onaylanmamış mesaj varsa göndermeyi durdurur. Bu nedenle, uygulama sunucusu, gelen mesajların sabit akışını sağlamak için istemci uygulamasından FCM aracılığıyla alınan yukarı akış mesajlarını mümkün olan en kısa sürede "ACK" yapmalıdır. Yukarıda belirtilen bekleyen mesaj sınırı bu ACK'lar için geçerli değildir. Bekleyen mesaj sayısı 100'e ulaşsa bile, uygulama sunucusu yeni yukarı akış mesajlarının teslimini engellemekten kaçınmak için FCM'den alınan mesajlar için ACK göndermeye devam etmelidir.

ACK'lar yalnızca tek 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 bir ACK / NACK alınmamış tüm bekleyen mesajlar tekrar gönderilmelidir.