Skip to content

docs: Update client.md for FCM doc revamp #17689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Update client.md for FCM doc revamp #17689

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 63 additions & 53 deletions docs/cloud-messaging/client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,12 @@
Project: /docs/cloud-messaging/_project.yaml
Book: /docs/_book.yaml
page_type: guide

{% include "_shared/apis/console/_local_variables.html" %}
{% include "_local_variables.html" %}
{% include "docs/cloud-messaging/_local_variables.html" %}
{% include "docs/android/_local_variables.html" %}

<link rel="stylesheet" type="text/css" href="/styles/docs.css" />

# Set up a Firebase Cloud Messaging client app on Flutter

Follow these steps to set up an FCM client on Flutter.

## Platform-specific setup and requirements
Depending on the platform you're targeting, there are some additional required setup steps that you'll need to take.

Some of the required steps depend on the platform you're targeting.
## iOS+

### iOS+

#### Enable app capabilities in Xcode
### Enable app capabilities in Xcode

Before your application can start to receive messages, you must enable push
notifications and background modes in your Xcode project.
Expand All @@ -31,27 +18,25 @@ notifications and background modes in your Xcode project.

#### Upload your APNs authentication key

Before you use FCM, upload your APNs certificate to Firebase. If you don't
already have an APNs certificate, create one in the
Before you use FCM, upload your APNs authentication key to Firebase. If you don't
already have an APNs authentication key, create one in the
[Apple Developer Member Center](https://developer.apple.com/membercenter/index.action).

1. Inside your project in the Firebase console, select the gear icon, select
**Project Settings**, and then select the **Cloud Messaging** tab.
1. Select the **Upload Certificate** button for your development certificate,
your production certificate, or both. At least one is required.
1. For each certificate, select the .p12 file, and provide the password, if
any. Make sure the bundle ID for this certificate matches the bundle ID of
your app. Select **Save**.
1. Select the **Upload** button for your development authentication key,
your production authentication key, or both. At least one is required.
1. For each authentication key, select the .p8 file, and provide the key ID and your Apple team ID. Select **Save**.

#### Method swizzling

To use the FCM Flutter plugin on Apple devices, you must not disable method
swizzling. Swizzling is required, and without it, key Firebase features such as
FCM token handling do not function properly.
To use the FCM Flutter plugin on Apple devices, method
swizzling is required. Without it, key Firebase features such as
FCM token handling won't function properly.

### Android
## Android

#### Google Play services
### Google Play services

FCM clients require devices running Android 4.4 or higher that also have Google
Play services installed, or an emulator running Android 4.4 with Google APIs.
Expand All @@ -69,12 +54,12 @@ other means, such as through the back button, the check is still performed.
If the device doesn't have a compatible version of Google Play services, your
app can call [`GoogleApiAvailability.makeGooglePlayServicesAvailable()`](//developers.google.com/android/reference/com/google/android/gms/common/GoogleApiAvailability.html#public-methods) to allow users to download Google Play services from the Play Store.

### Web
## Web

#### Configure Web Credentials with FCM
### Configure Web Credentials with FCM

The FCM Web interface uses Web credentials called "Voluntary Application Server
Identification," or "VAPID" keys, to authorize send requests to supported web
The FCM Web interface uses Web credentials called Voluntary Application Server
Identification, or "VAPID" keys, to authorize send requests to supported web
push services. To subscribe your app to push notifications, you need to
associate a pair of keys with your Firebase project. You can either generate a
new key pair or import your existing key pair through the Firebase console.
Expand Down Expand Up @@ -131,20 +116,15 @@ see [Application server keys](https://developers.google.com/web/fundamentals/pus
flutter run
```


## Access the registration token

To send a message to a specific device, you need to know that device's
registration token. Because you'll need to enter the token in a field in the
Notifications console to complete this tutorial, make sure to copy the token
or securely store it after you retrieve it.

To retrieve the current registration token for an app instance, call
To send a message to a specific device, you need to know the device
registration token. To retrieve the current registration token for an app instance, call
`getToken()`. If notification permission has not been granted, this method will
ask the user for notification permissions. Otherwise, it returns a token or
rejects the future due to an error.

Warning: In iOS SDK 10.4.0 and higher, it is a requirement that the APNs token
Warning: In iOS SDK 10.4.0 and higher, it is required that the APNs token
is available before making API requests. The APNs token is not guaranteed to
have been received before making FCM plugin API requests.

Expand Down Expand Up @@ -182,23 +162,21 @@ FirebaseMessaging.instance.onTokenRefresh
});
```


## Prevent auto initialization {:#prevent-auto-init}

When an FCM registration token is generated, the library uploads
the identifier and configuration data to Firebase. If you prefer to prevent
token autogeneration, disable auto-initialization at build time.

#### iOS
### iOS

On iOS, add a metadata value to your `Info.plist`:

```
FirebaseMessagingAutoInitEnabled = NO
```


#### Android
### Android

On Android, disable Analytics collection and FCM auto initialization (you must
disable both) by adding these metadata values to your `AndroidManifest.xml`:
Expand All @@ -222,17 +200,49 @@ await FirebaseMessaging.instance.setAutoInitEnabled(true);

This value persists across app restarts once set.

## Next steps
## Send a test notification message

1. Install and run the app on the target device. On Apple devices, you'll need to accept the request for permission to receive remote notifications.
2. Make sure the app is in the background on the device.
3. In the Firebase console, open the Messaging page.
4. If this is your first message, select **Create your first campaign**. Select **Firebase Notification messages** and select **Create**.
5. Otherwise, on the **Campaign** tab, select **New campaign** and then **Notifications**.
6. Enter the message text.
7. Select **Send test message** from the right pane.
8. In the field labeled **Add an FCM registration token**, enter your registration token.
9. Select **Test**.

After you select **Test**, the targeted client device, with the app in the background, should receive the notification.

For insight into message delivery to your app, see the FCM reporting dashboard, which records the number of messages sent and opened on Apple and Android devices, along with impression data for Android apps.

## Handling interaction

After the client app is set up, you are ready to start sending downstream
messages with the
[Notifications composer](//console.firebase.google.com/project/_/notification).
See [Send a test message to a backgrounded app](first-message).
When users tap a notification, the default behavior on both Android and iOS is
to open the application. If the application is terminated, it will be started,
and if it is in the background, it will be brought to the foreground.

To add other, more advanced behavior to your app, you'll need a
[server implementation](/docs/cloud-messaging/server).
Depending on the content of a notification, you may want to handle the user's
interaction when the application opens. For example, if a new chat message is
sent using a notification and the user selects it, you may want to open the
specific conversation when the application opens.

Then, in your app client:
The `firebase-messaging` package provides two ways to handle this interaction:
1. `getInitialMessage():` If the application is opened from a terminated
state, this method returns a `Future` containing a `RemoteMessage`. Once
consumed, the `RemoteMessage` will be removed.
1. `onMessageOpenedApp`: A`Stream` which posts a `RemoteMessage` when the
application is opened from a background state.

To make sure your users have a smooth experience, you should handle both
scenarios. The following code example outlines how this can be achieved:

How you handle interactions depends on your application setup. The previously
shown example is a basic example of using a `StatefulWidget`.

## Next steps

After the client app is set up, you can start receiving messages or sending them to your users:
- [Send a test message to a backgrounded app](first-message)
- [Receive messages](/docs/cloud-messaging/flutter/receive)
- [Subscribe to message topics](/docs/cloud-messaging/flutter/topic-messaging)
- [Notification composer](///console.firebase.google.com/project/_/notification)
Loading