Firebase Cloud Messaging (FCM) is the new version of GCM. It inherits the reliable and scalable GCM infrastructure, plus new features! See the FAQ to learn more. If you are integrating messaging in a new app, start with FCM. GCM users are strongly recommended to upgrade to FCM, in order to benefit from new FCM features today and in the future.

Try Google Cloud Messaging for iOS

Use our iOS sample app to see how Google Cloud Messaging works, or add Google Cloud Messaging to your existing app.

To use this sample, make sure you have Xcode and CocoaPods.

Get the project

Start with the sample using the following command from a terminal:

pod try Google

Select the option for GcmExample.xcodeproj from the prompt.

Get a configuration file

To use the sample, you need to provide a valid APNs certificate and some additional information to get a configuration file and finish setting up your project. If you don't already have an APNs certificate, see Provisioning APNs SSL Certificates. When prompted, provide the Bundle ID associated with your APNs certificate.

After you complete the configuration process, take note of the API server key on the download page, you will need it later. Download the GoogleServices-Info.plist file to add to your project.

Create an API project

New Cloud Messaging projects must create a Firebase project in the Firebase console. In this process, you'll generate a configuration file and credentials for your project.

  1. Create a Firebase project in the Firebase console, if you don't already have one. If you already have an existing Google project associated with your mobile app, click Import Google Project. Otherwise, click Create New Project.
  2. Click Add Firebase to your iOS app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
  3. When prompted, enter your app's bundle ID. It's important to enter the bundle ID your app is using; this can only be set when you add an app to your Firebase project.
  4. At the end, you'll download a GoogleService-Info.plist file. You can download this file again at any time.
  5. If you haven't done so already, copy this into your Xcode project root.

Add the configuration file to your project

Drag the GoogleService-Info.plist file you just downloaded into the root of your Xcode project and add it to all targets.

In Xcode, replace the bundle identifier for the GcmExample and GcmExampleSwift targets with the value associated with your APNs certificate. This must be the same value used in the Get a configuration file step.

Run the sample

Now you're ready to build the sample app and run it from Xcode.

Select the GcmExample target then start the sample application on an attached device by clicking the run button for the workspace. You must use a physical device for this application to work. The iOS simulator does not support remote notifications.

The app registers with the Google Cloud Messaging service and prints the registration token to the Xcode debug console when finished.

Next, run the GcmServerDemo target. In the dialog, insert the provided API server key, as well as the registration token that the GcmExample app has printed in the Xcode debug console.

Once you have provided credentials to the dialog, you can select Send notification to send a notification to your iOS device, or Display cURL command to print a cURL command that you can use to send the same request to the GCM connection server. You can also select Send to topic to send a message to a topic instead of a direct message to the device. You don't need to add the registration token to use this option, the server key is enough.

If the GCMExample application is running in the foreground, you can see the content of the notification printed to the Xcode debug console; if the GCMExample app is in the background, you will receive an APNS notification.

How it works

Simply get the registration token using the GMS Instance ID API, and post the notification.

  // Create a config and set a delegate that implements the GGLInstaceIDDelegate protocol.
  GGLInstanceIDConfig *instanceIDConfig = [GGLInstanceIDConfig defaultConfig];
  instanceIDConfig.delegate = self;
  // Start the GGLInstanceID shared instance with the that config and request a registration
  // token to enable reception of notifications
  [[GGLInstanceID sharedInstance] startWithConfig:instanceIDConfig];
  _registrationOptions = @{kGGLInstanceIDRegisterAPNSOption:deviceToken,
                           kGGLInstanceIDAPNSServerTypeSandboxOption:@YES};
  [[GGLInstanceID sharedInstance] tokenWithAuthorizedEntity:_gcmSenderID
                                                      scope:kGGLInstanceIDScopeGCM
                                                    options:_registrationOptions
                                                    handler:_registrationHandler];

To receive the notification, implement application:didReceiveRemoteNotification:fetchCompletionHandler: (or application:didReceiveRemoteNotification: for iOS < 8.0), and call GCMService:appDidReceiveMessage:message to acknowledge the reception of the message to GCM.

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo {
  NSLog(@"Notification received: %@", userInfo);
  // This works only if the app started the GCM service
  [[GCMService sharedInstance] appDidReceiveMessage:userInfo];
  // Handle the received message
  // ...
}

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))handler {
  NSLog(@"Notification received: %@", userInfo);
  // This works only if the app started the GCM service
  [[GCMService sharedInstance] appDidReceiveMessage:userInfo];
  // Handle the received message
  // Invoke the completion handler passing the appropriate UIBackgroundFetchResult value
  // ...
}

Next steps

If you want to dive into the details, take a look at our iOS client implementation guide.

Add Google Cloud Messaging to your app

Did you have a good experience? Run into trouble? Let us know!

Send feedback about...

Cloud Messaging
Cloud Messaging