If your app server implements the
XMPP Connection Server
protocol,
it can receive upstream messages from a user's device to the cloud.
To initiate an upstream message, the client app sends a request containing the following:
- The address of the receiving app server in the format
SENDER_ID@fcm.googleapis.com
.
- A message ID that should be unique for each
sender ID
.
- The message data comprising the key-value pairs of the message's payload.
When it receives this data, FCM builds an XMPP stanza to send to the app server,
adding some additional information about the sending device and app.
Send an upstream message from an Android client app
Your Android app can send an upstream message using
FirebaseMessaging.send
:
Kotlin+KTX
val fm = Firebase.messaging
fm.send(
remoteMessage("$SENDER_ID@fcm.googleapis.com") {
setMessageId(messageId.toString())
addData("my_message", "Hello World")
addData("my_action", "SAY_HELLO")
},
)
Java
FirebaseMessaging fm = FirebaseMessaging.getInstance();
fm.send(new RemoteMessage.Builder(SENDER_ID + "@fcm.googleapis.com")
.setMessageId(Integer.toString(messageId))
.addData("my_message", "Hello World")
.addData("my_action","SAY_HELLO")
.build());
Handle upstream message callbacks
With
FirebaseMessaging
, you can implement the
callbacks
onMessageSent
and
onSendError
to check the status of upstream
messages. In error cases,
onSendError
returns a
SendException
with an error code. For example, if the client attempts to
send more messages after the 20-message limit is reached, it returns
SendException#ERROR_TOO_MANY_MESSAGES
.
In cases where the device is offline or the FCM
service is unavailable to
forward upstream messages to your server, Android client app instances can
accumulate a maximum of 20 pending messages.
If such messages expire before FCM can successfully send
them,
onSendError
returns
SendException#ERROR_TTL_EXCEEDED
.
To optimize network usage, FCM batches responses to
onMessageSent
and
onSendError
, so the acknowledgement may not be immediate for each message.
Receive XMPP messages on the app server
When FCM receives an upstream messaging call from a client app, it generates
the necessary XMPP stanza for sending the upstream message.
FCM adds the
category
and
from
fields, and then sends a
stanza like the following to the app server:
<message id="">
<gcm xmlns="google:mobile:data">
{
"category":"com.example.yourapp", // to know which app sent it
"data":
{
"hello":"world",
},
"message_id":"m-123",
"from":"REGID"
}
</gcm>
</message>
Sending an ACK message
In response to an upstream message like the above, the app server
must use the same connection to send an ACK message containing the unique
message ID. If FCM does not receive an ACK, it may retry sending
the message to the app server.
<message id="">
<gcm xmlns="google:mobile:data">
{
"to":"REGID",
"message_id":"m-123"
"message_type":"ack"
}
</gcm>
</message>
See the
XMPP Connection Server Reference
for more information about upstream message syntax.