Skip to content

Commit 44f7246

Browse files
yvonnep165yvonnep165
authored
feat(fcm): Enable fid and deprecate token for Send API (#951)
* add fid arg and token deprecate warning to Message class and add unit tests * add fids to MulticastMessage and token deprecate warning and add unit tests * Fix lint formatting error * Position `tokens` first to guarantee backward compatibility for legacy positional arguments and add a unit test for it * Extract multicast-to-message-list conversion logic into a private helper function * Add docstring for the helper function * Add unit tests for the async function, change deprecate message and address other review comments * Fix error messages and MulticastMessage constructor and add mix types of fids and tokens * Add integration tests for fid as argument * Update integration tests error code for invalid fid target
1 parent f493fb0 commit 44f7246

5 files changed

Lines changed: 258 additions & 43 deletions

File tree

‎firebase_admin/_messaging_encoder.py‎

Lines changed: 45 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import math
2020
import numbers
2121
import re
22+
import warnings
2223

2324
from firebase_admin import _messaging_utils
2425

@@ -27,7 +28,7 @@ class Message:
2728
"""A message that can be sent via Firebase Cloud Messaging.
2829
2930
Contains payload information as well as recipient information. In particular, the message must
30-
contain exactly one of token, topic or condition fields.
31+
contain exactly one of fid, token, topic or condition fields.
3132
3233
Args:
3334
data: A dictionary of data fields (optional). All keys and values in the dictionary must be
@@ -37,20 +38,29 @@ class Message:
3738
webpush: An instance of ``messaging.WebpushConfig`` (optional).
3839
apns: An instance of ``messaging.ApnsConfig`` (optional).
3940
fcm_options: An instance of ``messaging.FCMOptions`` (optional).
40-
token: The registration token of the device to which the message should be sent (optional).
41+
fid: The Firebase installation ID of an FCM registered app instance to which the
42+
message should be sent (optional).
43+
token: Deprecated. Use ``fid`` instead.
4144
topic: Name of the FCM topic to which the message should be sent (optional). Topic name
4245
may contain the ``/topics/`` prefix.
4346
condition: The FCM condition to which the message should be sent (optional).
4447
"""
4548

4649
def __init__(self, data=None, notification=None, android=None, webpush=None, apns=None,
47-
fcm_options=None, token=None, topic=None, condition=None):
50+
fcm_options=None, token=None, topic=None, condition=None, fid=None):
51+
if token is not None:
52+
warnings.warn(
53+
"Message.token is deprecated. Use Message.fid instead.",
54+
DeprecationWarning,
55+
stacklevel=2
56+
)
4857
self.data = data
4958
self.notification = notification
5059
self.android = android
5160
self.webpush = webpush
5261
self.apns = apns
5362
self.fcm_options = fcm_options
63+
self.fid = fid
5464
self.token = token
5565
self.topic = topic
5666
self.condition = condition
@@ -60,24 +70,46 @@ def __str__(self):
6070

6171

6272
class MulticastMessage:
63-
"""A message that can be sent to multiple tokens via Firebase Cloud Messaging.
73+
"""A message that can be sent to multiple tokens or fids via Firebase Cloud Messaging.
6474
6575
Args:
66-
tokens: A list of registration tokens of targeted devices.
76+
tokens: Deprecated. Use ``fids`` instead (optional).
6777
data: A dictionary of data fields (optional). All keys and values in the dictionary must be
6878
strings.
6979
notification: An instance of ``messaging.Notification`` (optional).
7080
android: An instance of ``messaging.AndroidConfig`` (optional).
7181
webpush: An instance of ``messaging.WebpushConfig`` (optional).
7282
apns: An instance of ``messaging.ApnsConfig`` (optional).
7383
fcm_options: An instance of ``messaging.FCMOptions`` (optional).
84+
fids: A list of Firebase Installation IDs of targeted app instances (optional).
7485
"""
75-
def __init__(self, tokens, data=None, notification=None, android=None, webpush=None, apns=None,
76-
fcm_options=None):
77-
_Validators.check_string_list('MulticastMessage.tokens', tokens)
78-
if len(tokens) > 500:
79-
raise ValueError('MulticastMessage.tokens must not contain more than 500 tokens.')
86+
def __init__(
87+
self, tokens=None, data=None, notification=None, android=None,
88+
webpush=None, apns=None, fcm_options=None, fids=None):
89+
if tokens is not None:
90+
warnings.warn(
91+
"MulticastMessage.tokens is deprecated. Use MulticastMessage.fids instead.",
92+
DeprecationWarning,
93+
stacklevel=2
94+
)
95+
96+
if tokens is None and fids is None:
97+
raise ValueError(
98+
"Must specify at least one of MulticastMessage.tokens or MulticastMessage.fids.")
99+
100+
if tokens is not None:
101+
_Validators.check_string_list('MulticastMessage.tokens', tokens)
102+
if fids is not None:
103+
_Validators.check_string_list('MulticastMessage.fids', fids)
104+
105+
tokens_len = len(tokens) if tokens is not None else 0
106+
fids_len = len(fids) if fids is not None else 0
107+
if tokens_len + fids_len > 500:
108+
raise ValueError(
109+
'Total number of tokens and fids must not exceed 500.')
110+
80111
self.tokens = tokens
112+
self.fids = fids
81113
self.data = data
82114
self.notification = notification
83115
self.android = android
@@ -695,16 +727,17 @@ def default(self, o): # pylint: disable=method-hidden
695727
'Message.condition', o.condition, non_empty=True),
696728
'data': _Validators.check_string_dict('Message.data', o.data),
697729
'notification': MessageEncoder.encode_notification(o.notification),
730+
'fid': _Validators.check_string('Message.fid', o.fid, non_empty=True),
698731
'token': _Validators.check_string('Message.token', o.token, non_empty=True),
699732
'topic': _Validators.check_string('Message.topic', o.topic, non_empty=True),
700733
'webpush': MessageEncoder.encode_webpush(o.webpush),
701734
'fcm_options': MessageEncoder.encode_fcm_options(o.fcm_options),
702735
}
703736
result['topic'] = MessageEncoder.sanitize_topic_name(result.get('topic'))
704737
result = MessageEncoder.remove_null_values(result)
705-
target_count = sum(t in result for t in ['token', 'topic', 'condition'])
738+
target_count = sum(t in result for t in ['fid', 'token', 'topic', 'condition'])
706739
if target_count != 1:
707-
raise ValueError('Exactly one of token, topic or condition must be specified.')
740+
raise ValueError('Exactly one of fid, token, topic or condition must be specified.')
708741
return result
709742

710743
@classmethod

‎firebase_admin/_messaging_utils.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -519,7 +519,8 @@ def __init__(self, message, cause=None, http_response=None):
519519
class UnregisteredError(exceptions.NotFoundError):
520520
"""App instance was unregistered from FCM.
521521
522-
This usually means that the token used is no longer valid and a new one must be used."""
522+
This usually means that the registration token or installation ID (FID) used
523+
is no longer valid and a new one must be used."""
523524

524525
def __init__(self, message, cause=None, http_response=None):
525526
exceptions.NotFoundError.__init__(self, message, cause, http_response)

‎firebase_admin/messaging.py‎

Lines changed: 38 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import json
2121
import asyncio
2222
import logging
23+
import warnings
2324
import requests
2425
import httpx
2526

@@ -172,13 +173,45 @@ async def send_each_async(
172173
"""
173174
return await _get_messaging_service(app).send_each_async(messages, dry_run)
174175

176+
def _get_messages_from_multicast(multicast_message: MulticastMessage) -> List[Message]:
177+
"""Extracts individual Message objects from a MulticastMessage."""
178+
if not isinstance(multicast_message, MulticastMessage):
179+
raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
180+
181+
messages = []
182+
if multicast_message.tokens is not None:
183+
with warnings.catch_warnings():
184+
warnings.simplefilter("ignore", DeprecationWarning)
185+
messages.extend([Message(
186+
data=multicast_message.data,
187+
notification=multicast_message.notification,
188+
android=multicast_message.android,
189+
webpush=multicast_message.webpush,
190+
apns=multicast_message.apns,
191+
fcm_options=multicast_message.fcm_options,
192+
token=token
193+
) for token in multicast_message.tokens])
194+
195+
if multicast_message.fids is not None:
196+
messages.extend([Message(
197+
data=multicast_message.data,
198+
notification=multicast_message.notification,
199+
android=multicast_message.android,
200+
webpush=multicast_message.webpush,
201+
apns=multicast_message.apns,
202+
fcm_options=multicast_message.fcm_options,
203+
fid=fid
204+
) for fid in multicast_message.fids])
205+
206+
return messages
207+
175208
async def send_each_for_multicast_async(
176209
multicast_message: MulticastMessage,
177210
dry_run: bool = False,
178211
app: Optional[App] = None
179212
) -> BatchResponse:
180-
"""Sends the given mutlicast message to each token asynchronously via Firebase Cloud Messaging
181-
(FCM).
213+
"""Sends the given multicast message to each token or fid asynchronously via
214+
Firebase Cloud Messaging (FCM).
182215
183216
If the ``dry_run`` mode is enabled, the message will not be actually delivered to the
184217
recipients. Instead, FCM performs all the usual validations and emulates the send operation.
@@ -195,21 +228,11 @@ async def send_each_for_multicast_async(
195228
FirebaseError: If an error occurs while sending the message to the FCM service.
196229
ValueError: If the input arguments are invalid.
197230
"""
198-
if not isinstance(multicast_message, MulticastMessage):
199-
raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
200-
messages = [Message(
201-
data=multicast_message.data,
202-
notification=multicast_message.notification,
203-
android=multicast_message.android,
204-
webpush=multicast_message.webpush,
205-
apns=multicast_message.apns,
206-
fcm_options=multicast_message.fcm_options,
207-
token=token
208-
) for token in multicast_message.tokens]
231+
messages = _get_messages_from_multicast(multicast_message)
209232
return await _get_messaging_service(app).send_each_async(messages, dry_run)
210233

211234
def send_each_for_multicast(multicast_message, dry_run=False, app=None):
212-
"""Sends the given mutlicast message to each token via Firebase Cloud Messaging (FCM).
235+
"""Sends the given multicast message to each token or fid via Firebase Cloud Messaging (FCM).
213236
214237
If the ``dry_run`` mode is enabled, the message will not be actually delivered to the
215238
recipients. Instead, FCM performs all the usual validations and emulates the send operation.
@@ -226,17 +249,7 @@ def send_each_for_multicast(multicast_message, dry_run=False, app=None):
226249
FirebaseError: If an error occurs while sending the message to the FCM service.
227250
ValueError: If the input arguments are invalid.
228251
"""
229-
if not isinstance(multicast_message, MulticastMessage):
230-
raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
231-
messages = [Message(
232-
data=multicast_message.data,
233-
notification=multicast_message.notification,
234-
android=multicast_message.android,
235-
webpush=multicast_message.webpush,
236-
apns=multicast_message.apns,
237-
fcm_options=multicast_message.fcm_options,
238-
token=token
239-
) for token in multicast_message.tokens]
252+
messages = _get_messages_from_multicast(multicast_message)
240253
return _get_messaging_service(app).send_each(messages, dry_run)
241254

242255
def subscribe_to_topic(tokens, topic, app=None):

‎integration/test_messaging.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,14 @@ def test_send_malformed_token():
8787
with pytest.raises(exceptions.InvalidArgumentError):
8888
messaging.send(msg, dry_run=True)
8989

90+
def test_send_invalid_fid():
91+
msg = messaging.Message(
92+
fid='not-a-fid',
93+
notification=messaging.Notification('test-title', 'test-body')
94+
)
95+
with pytest.raises(messaging.UnregisteredError):
96+
messaging.send(msg, dry_run=True)
97+
9098
def test_send_each():
9199
messages = [
92100
messaging.Message(
@@ -149,6 +157,21 @@ def test_send_each_for_multicast():
149157
assert response.exception is not None
150158
assert response.message_id is None
151159

160+
def test_send_each_for_multicast_fids():
161+
multicast = messaging.MulticastMessage(
162+
notification=messaging.Notification('Title', 'Body'),
163+
fids=['not-a-fid', 'also-not-a-fid'])
164+
165+
batch_response = messaging.send_each_for_multicast(multicast)
166+
167+
assert batch_response.success_count == 0
168+
assert batch_response.failure_count == 2
169+
assert len(batch_response.responses) == 2
170+
for response in batch_response.responses:
171+
assert response.success is False
172+
assert isinstance(response.exception, messaging.UnregisteredError)
173+
assert response.message_id is None
174+
152175
def test_subscribe():
153176
resp = messaging.subscribe_to_topic(_REGISTRATION_TOKEN, 'mock-topic')
154177
assert resp.success_count + resp.failure_count == 1

0 commit comments

Comments
 (0)