firebase::messaging

Firebase Cloud Messaging API.

Summary

Firebase Cloud Messaging allows you to send data from your server to your users' devices, and receive messages from devices on the same connection if you're using a XMPP server.

The FCM service handles all aspects of queueing of messages and delivery to client applications running on target devices.

Enumerations
Error{   kErrorNone = 0,   kErrorFailedToRegisterForRemoteNotifications,   kErrorInvalidTopicName,   kErrorNoRegistrationToken,   kErrorUnknown }	enum Error code returned by Firebase Cloud Messaging C++ functions.

Functions
DeleteToken()	Future< void > Deprecated. Use Unregister() instead. Deletes the default token for this Firebase project.
DeleteTokenLastResult()	Future< void > Deprecated. Use UnregisterLastResult() instead. Gets the result of the most recent call to DeleteToken();.
DeliveryMetricsExportToBigQueryEnabled()	bool Determines whether Firebase Cloud Messaging exports message delivery metrics to BigQuery.
GetToken()	Future< std::string > Deprecated. Use Register() instead. This creates a Firebase Installations ID, if one does not exist, and sends information about the application and the device where it's running to the Firebase backend.
GetTokenLastResult()	Future< std::string > Deprecated. Use RegisterLastResult() instead. Gets the result of the most recent call to GetToken();.
Initialize(const App & app, Listener *listener)	InitResult Initialize Firebase Cloud Messaging.
Initialize(const App & app, Listener *listener, const MessagingOptions & options)	InitResult Initialize Firebase Cloud Messaging.
IsRegistrationOnInitEnabled()	bool Determines if automatic registration during initialization is enabled.
IsTokenRegistrationOnInitEnabled()	bool Deprecated. Use IsRegistrationOnInitEnabled() instead. Determines if automatic token registration during initalization is enabled.
Register()	Future< void > Registers the current Firebase app instance with the Firebase Cloud Messaging (FCM) backend to receive messages.
RegisterLastResult()	Future< void > Gets the result of the most recent call to Register().
RequestPermission()	Future< void > Displays a prompt to the user requesting permission to display notifications.
RequestPermissionLastResult()	Future< void > Gets the result of the most recent call to RequestPermission();.
SetDeliveryMetricsExportToBigQuery(bool enable)	void Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery.
SetListener(Listener *listener)	Listener * Set the listener for events from the Firebase Cloud Messaging servers.
SetRegistrationOnInitEnabled(bool enable)	void Enable or disable registration during initialization of Firebase Cloud Messaging.
SetTokenRegistrationOnInitEnabled(bool enable)	void Deprecated. Use SetRegistrationOnInitEnabled(bool) instead. Enable or disable token registration during initialization of Firebase Cloud Messaging.
Subscribe(const char *topic)	Future< void > Subscribe to receive all messages to the specified topic.
SubscribeLastResult()	Future< void > Gets the result of the most recent call to Unsubscribe();.
Terminate()	void Terminate Firebase Cloud Messaging.
Unregister()	Future< void > Unregisters the current app instance with FCM.
UnregisterLastResult()	Future< void > Gets the result of the most recent call to Unregister().
Unsubscribe(const char *topic)	Future< void > Unsubscribe from a topic.
UnsubscribeLastResult()	Future< void > Gets the result of the most recent call to Unsubscribe();.

Classes
firebase::messaging::Listener	Base class used to receive messages from Firebase Cloud Messaging.
firebase::messaging::PollableListener	A listener that can be polled to consume pending Messages and registration events.

Structs
firebase::messaging::AndroidNotificationParams	Data structure for parameters that are unique to the Android implementation.
firebase::messaging::Message	Data structure used to receive messages from cloud messaging.
firebase::messaging::MessagingOptions	A class to configure the behavior of Firebase Cloud Messaging.
firebase::messaging::Notification	Used for messages that display a notification.

Enumerations

Error

 Error

Error code returned by Firebase Cloud Messaging C++ functions.

Properties
kErrorFailedToRegisterForRemoteNotifications	Permission to receive notifications was not granted.
kErrorInvalidTopicName	Topic name is invalid for subscription/unsubscription.
kErrorNoRegistrationToken	Could not subscribe/unsubscribe because there is no registration token.
kErrorNone	The operation was a success, no error occurred.
kErrorUnknown	Unknown error.

Functions

DeleteToken

Future< void > DeleteToken()

Deletes the default token for this Firebase project.

Note that this does not delete the Firebase Installations ID that may have been created when generating the token. See Installations.Delete() for deleting that.

Deprecated. Use Unregister() instead.

Details
Returns	A future that completes when the token is deleted.

DeleteTokenLastResult

Future< void > DeleteTokenLastResult()

Gets the result of the most recent call to DeleteToken();.

Deprecated. Use UnregisterLastResult() instead.

Details
Returns	Result of the most recent call to DeleteToken().

DeliveryMetricsExportToBigQueryEnabled

bool DeliveryMetricsExportToBigQueryEnabled()

Determines whether Firebase Cloud Messaging exports message delivery metrics to BigQuery.

This function is currently only implemented on Android, and returns false with no other behavior on other platforms.

Details
Returns	true if Firebase Cloud Messaging exports message delivery metrics to BigQuery.

GetToken

Future< std::string > GetToken()

This creates a Firebase Installations ID, if one does not exist, and sends information about the application and the device where it's running to the Firebase backend.

Deprecated. Use Register() instead.

Details
Returns	A future with the token.

GetTokenLastResult

Future< std::string > GetTokenLastResult()

Gets the result of the most recent call to GetToken();.

Deprecated. Use RegisterLastResult() instead.

Details
Returns	Result of the most recent call to GetToken().

Initialize

InitResult Initialize(
  const App & app,
  Listener *listener
)

Initialize Firebase Cloud Messaging.

After Initialize is called, the implementation may call functions on the Listener provided at any time.

Details
Parameters	app The Firebase App object for this application. listener A Listener object that listens for events from the Firebase Cloud Messaging servers.
Returns	kInitResultSuccess if initialization succeeded, or kInitResultFailedMissingDependency on Android if Google Play services is not available on the current device.

Initialize

InitResult Initialize(
  const App & app,
  Listener *listener,
  const MessagingOptions & options
)

Initialize Firebase Cloud Messaging.

After Initialize is called, the implementation may call functions on the Listener provided at any time.

Details
Parameters	app The Firebase App object for this application. listener A Listener object that listens for events from the Firebase Cloud Messaging servers. options A set of options that configure the initialzation behavior of Firebase Cloud Messaging.
Returns	kInitResultSuccess if initialization succeeded, or kInitResultFailedMissingDependency on Android if Google Play services is not available on the current device.

IsRegistrationOnInitEnabled

bool IsRegistrationOnInitEnabled()

Determines if automatic registration during initialization is enabled.

Details
Returns	true if auto registration is enabled and false if disabled.

IsTokenRegistrationOnInitEnabled

bool IsTokenRegistrationOnInitEnabled()

Determines if automatic token registration during initalization is enabled.

Deprecated. Use IsRegistrationOnInitEnabled() instead.

Details
Returns	true if auto token registration is enabled and false if disabled.

Register

Future< void > Register()

Registers the current Firebase app instance with the Firebase Cloud Messaging (FCM) backend to receive messages.

This creates a Firebase Installations ID (FID), if one does not exist, and sends information about the application and the device where it's running to the Firebase backend.

Upon completion, OnRegistrationReceived will be triggered with the current FID. Calling this function when already registered will still invoke the OnRegistrationReceived callback with the existing FID.

Details
Returns	A future that completes when the registration is completed.

RegisterLastResult

Future< void > RegisterLastResult()

Gets the result of the most recent call to Register().

Details
Returns	Result of the most recent call to Register().

RequestPermission

Future< void > RequestPermission()

Displays a prompt to the user requesting permission to display notifications.

The permission prompt only appears on iOS and tvOS. If the user has already agreed to allow notifications, no prompt is displayed and the returned future is completed immediately.

Details
Returns	A future that completes when the notification prompt has been dismissed.

RequestPermissionLastResult

Future< void > RequestPermissionLastResult()

Gets the result of the most recent call to RequestPermission();.

Details
Returns	Result of the most recent call to RequestPermission().

SetDeliveryMetricsExportToBigQuery

void SetDeliveryMetricsExportToBigQuery(
  bool enable
)

Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery.

By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. In addition, you can enable the export by adding to your manifest. Note that the run-time method call will override the manifest value.

This function is currently only implemented on Android, and has no behavior on other platforms.

Details
Parameters	enable Whether Firebase Cloud Messaging should export message delivery metrics to BigQuery.

SetListener

Listener * SetListener(
  Listener *listener
)

Set the listener for events from the Firebase Cloud Messaging servers.

A listener must be set for the application to receive messages from the Firebase Cloud Messaging servers. The implementation may call functions on the Listener provided at any time.

Details
Parameters	listener A Listener object that listens for events from the Firebase Cloud Messaging servers.
Returns	Pointer to the previously set listener.

SetRegistrationOnInitEnabled

void SetRegistrationOnInitEnabled(
  bool enable
)

Enable or disable registration during initialization of Firebase Cloud Messaging.

The installation ID returned is what identifies the user to Firebase, so disabling this avoids creating any new identity and automatically sending it to Firebase, unless consent has been granted.

If this setting is enabled, it triggers the registration refresh immediately. This setting is persisted across app restarts and overrides the setting "firebase_messaging_auto_init_enabled" specified in your Android manifest (on Android) or Info.plist (on iOS and tvOS).

By default, registration during initialization is enabled.

The registration happens before you can programmatically disable it, so if you need to change the default, (for example, because you want to prompt the user before FCM generates/refreshes a registration on app startup), add to your application’s manifest:

<meta-data android:name="firebase_messaging_auto_init_enabled"
android:value="false" />

or on iOS or tvOS to your Info.plist:

<key>FirebaseMessagingAutoInitEnabled</key>
<false/>

Details
Parameters	enable sets if a registration should be requested on initialization.

SetTokenRegistrationOnInitEnabled

void SetTokenRegistrationOnInitEnabled(
  bool enable
)

Enable or disable token registration during initialization of Firebase Cloud Messaging.

This token is what identifies the user to Firebase, so disabling this avoids creating any new identity and automatically sending it to Firebase, unless consent has been granted.

If this setting is enabled, it triggers the token registration refresh immediately. This setting is persisted across app restarts and overrides the setting "firebase_messaging_auto_init_enabled" specified in your Android manifest (on Android) or Info.plist (on iOS and tvOS).

By default, token registration during initialization is enabled.

The registration happens before you can programmatically disable it, so if you need to change the default, (for example, because you want to prompt the user before FCM generates/refreshes a registration token on app startup), add to your application’s manifest:

<meta-data android:name="firebase_messaging_auto_init_enabled"
android:value="false" />

or on iOS or tvOS to your Info.plist:

<key>FirebaseMessagingAutoInitEnabled</key>
<false/>

Deprecated. Use SetRegistrationOnInitEnabled(bool) instead.

Details
Parameters	enable sets if a registration token should be requested on initialization.

Subscribe

Future< void > Subscribe(
  const char *topic
)

Subscribe to receive all messages to the specified topic.

Subscribes an app instance to a topic, enabling it to receive messages sent to that topic.

Call this function from the main thread. FCM is not thread safe.

Details
Parameters	topic The name of the topic to subscribe. Must match the following regular expression: [a-zA-Z0-9-_.~%]{1,900}.

SubscribeLastResult

Future< void > SubscribeLastResult()

Gets the result of the most recent call to Unsubscribe();.

Details
Returns	Result of the most recent call to Unsubscribe().

Terminate

void Terminate()

Terminate Firebase Cloud Messaging.

Frees resources associated with Firebase Cloud Messaging.

Note: On Android, the services will not be shut down by this method.

Unregister

Future< void > Unregister()

Unregisters the current app instance with FCM.

Note that this does not delete the Firebase Installations ID that may have been created during registration. See Installations.Delete() for deleting that.

Details
Returns	A future that completes when the unregistration is completed.

UnregisterLastResult

Future< void > UnregisterLastResult()

Gets the result of the most recent call to Unregister().

Details
Returns	Result of the most recent call to Unregister().

Unsubscribe

Future< void > Unsubscribe(
  const char *topic
)

Unsubscribe from a topic.

Unsubscribes an app instance from a topic, stopping it from receiving any further messages sent to that topic.

Call this function from the main thread. FCM is not thread safe.

Details
Parameters	topic The name of the topic to unsubscribe from. Must match the following regular expression: [a-zA-Z0-9-_.~%]{1,900}.

UnsubscribeLastResult

Future< void > UnsubscribeLastResult()

Gets the result of the most recent call to Unsubscribe();.

Details
Returns	Result of the most recent call to Unsubscribe().