Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Page updated May 21, 2024

Set up Amplify Push Notifications

Amplify Flutter v1 is now in Maintenance Mode until April 30th, 2025. This means that we will continue to include updates to ensure compatibility with backend services and security. No new features will be introduced in v1.

Please use the latest version (v2) of Amplify Flutter to get started.

If you are currently using v1, follow these instructions to upgrade to v2.

The Push Notifications category allows you to integrate push notifications in your app with Amazon Pinpoint targeting, campaign, and journey management support. You can segment your users, trigger push notifications to your app, and record metrics in Pinpoint when users receive or open notifications. Amazon Pinpoint helps you to create messaging campaigns and journeys targeted to specific user segments or demographics and collect interaction metrics with push notifications.

Prerequisites

You should have completed the CLI and project setup steps.

An application targeting at least iOS 13.0, using Xcode 14.1 or later.

Push Notifications are delivered via the Apple Push Notification service (APNs). In order to use APNs, you need to setup credentials (keys or certificates) and export your credentials to a p12 file. See Setting up push notification services for more information.

Testing with APNs on the iOS simulator requires an Apple Silicon Mac running macOS 13+, Xcode 14+, and iOS simulator 16+. If your development environment does not meet all these requirements, then you must run on a real device to get an APNs token.

Set Entitlements

Using Amplify Push Notifications with APNs requires the following capabilities:

  • Push Notifications
  • Background Processing -> Remote Notifications

To add these capabilities:

  1. Open your Xcode project, go to project settings, select your main application target, select the Signing and Capabilities tab, and click + Capability in the upper left corner of the editor pane to bring up the Capabilities dialog.

Arrow pointing to the plus capability icon.

Xcode can be a little finicky with this step. If the Capabilities dialog is empty, try switching to a different tab and then switching back to Signing and Capabilities

  1. Type push in the filter box and double-click Push Notifications to add the capability.

The word push typed into the search bar capabilities and push notifications is a result.

  1. Repeat step 1 to open the Capabilities dialog and then type back in the filter box and double-click Background Modes to add the capability.

The word back typed into the search bar and background modes is a result.

  1. Select Change All when prompted.

  2. Under Background Modes, select Remote Notifications

Remote notifications box is selected in the background modes section.

  1. Select Change All again when prompted.

An application targeting at least Android SDK API level 24.

Push Notifications are delivered via Firebase Cloud Messaging (FCM). In order to use FCM, you need to register your app on the Firebase console. See Setting up push notification services for more information.

Applying the Google services plugin

The Firebase documentation directs you to add the Google services plugin to your app build.gradle using the Gradle plugins DSL. However, we recommend you continue to use the Legacy Plugin Application instead:

apply plugin: 'com.google.gms.google-services'

If you prefer using the plugins DSL, you should add the plugins block to the very top of the file or you may experience issues when building your app for Android.

Set up backend resources

To use Push Notifications with Amplify, you have the option to either have the Amplify CLI setup resources for you, or you can use an existing Amazon Pinpoint resource in your AWS account.

Prerequisite: Install and configure the Amplify CLI

Push Notifications requires version 10.8.0+ of the Amplify CLI. You can check your current version with amplify -version and upgrade to the latest version with amplify upgrade.

To start provisioning push notification resources in the backend, go to your project directory and execute the command:

amplify add notifications

Choose APNS when promoted:

? Choose the push notification channel to enable.
❯ APNS |  Apple Push Notifications
FCM | » Firebase Push Notifications
In-App Messaging
Email
SMS

Follow the setup prompts:

Authorizing the app for analytics events is crucial for unauthenticated users, particularly if you intend to configure Amplify or send push notifications to your users before their authentication. If authorization is declined, please keep in mind that updating the Cognito user pool would become necessary, and any subsequent updates could potentially result in the deletion of the current user data.

? Provide your pinpoint resource name: › [pinpoint_resource_name]
? Apps need authorization to send analytics events. Do you want to allow guests
and unauthenticated users to send analytics events? (we recommend you allow this
when getting started) (Y/n)

Choose Certificate when promoted:

? Choose authentication method used for APNs
> Certificate
Key

The CLI will prompt for your p12 certificate path, enter a path relative to the location where you ran the command.

Note: If you receive this error:

🛑 Command failed: openssl pkcs12 -in [path_to_your_cert].p12 -out [output_path].pem -nodes -passin pass:
Error outputting keys and certificates

Please try using LibreSSL 3.3.6 instead of OpenSSL. See issue #12969

Upon completion, amplifyconfiguration.dart will be updated to reference the newly provisioned backend push notifications resources. Note that this file should already be generated for you by the Amplify CLI as a part of your project if you followed the project setup walkthrough.

Choose FCM when promoted:

? Choose the push notification channel to enable.
APNS |  Apple Push Notifications
❯ FCM | » Firebase Push Notifications
In-App Messaging
Email
SMS
? Provide your pinpoint resource name:
`yourPinpointResourceName`
? Apps need authorization to send analytics events. Do you want to allow guests and unauthenticated users to send analytics events? (we recommend you allow this when getting started) (Y/n)
'Y'

The CLI will prompt for your Server Key, paste the Token you copied while setting up push notification services.

Upon completion, amplifyconfiguration.dart will be updated to reference the newly provisioned backend push notifications resources. Note that this file should already be generated for you by the Amplify CLI as a part of your project if you followed the project setup walkthrough.

Existing Amazon Pinpoint resources can be used with Amplify Push Notifications by configuring amplifyconfiguration.dart with Application ID and Region.

{
"notifications": {
"plugins": {
"awsPinpointPushNotificationsPlugin": {
"appId": "<app-id>",
"region": "<region>"
}
}
}
}
  • appId: Amazon Pinpoint application ID
  • region: AWS Region where the resources are provisioned (e.g. us-east-1)

Install Amplify Libraries

In your project directory, you should first install the necessary dependencies for using Amplify Push Notifications.

  1. Open pubspec.yaml at the root of your Flutter project with a text editor.

  2. Add the necessary libraries into the dependencies block:

dependencies:
amplify_auth_cognito: ^1.0.0
amplify_flutter: ^1.0.0
amplify_push_notifications_pinpoint: ^1.0.0
flutter:
sdk: flutter

Initialize Amplify Push Notifications

To initialize Amplify Push Notifications, you will need to configure Amplify add the Auth and Push Notifications plugins. To complete initialization, call Amplify.configure

Your resulting code should look something like the following:

// Example main.dart
import 'package:amplify_auth_cognito/amplify_auth_cognito.dart';
import 'package:amplify_flutter/amplify_flutter.dart';
import 'package:amplify_push_notifications_pinpoint/amplify_push_notifications_pinpoint.dart';
import 'amplifyconfiguration.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatefulWidget {
const MyApp({Key? key}) : super(key: key);
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
void initState() {
super.initState();
_configureAmplify();
}
Future<void> _configureAmplify() async {
try {
final authPlugin = AmplifyAuthCognito();
final pushPlugin = AmplifyPushNotificationsPinpoint();
await Amplify.addPlugins([authPlugin, pushPlugin]);
await Amplify.configure(amplifyconfig);
} on Exception catch (e) {
safePrint('An error occurred configuring Amplify: $e');
}
}
Widget build(BuildContext context) {
// Your application UI
}
}