Menu
Amazon Simple Notification Service
Developer Guide (API Version 2010-03-31)

Getting Started with Google Cloud Messaging for Android

Google Cloud Messaging for Android (GCM) is a service that enables you to send push notification messages to an Android app. This section describes how to obtain the GCM prerequisites and send a push notification message to a mobile endpoint.

GCM Prerequisites

To send push notification messages to an Android app, you need the following:

  • Android app registered with GCM

  • Registration ID

  • Server API key (sender auth token)

If you already have these prerequisites, then you can either use the Amazon SNS console to send a push notification message to the mobile endpoint or you can use the Amazon SNS API. For more information about using the Amazon SNS console, see Using Amazon SNS Mobile Push. For more information about using the Amazon SNS API, see Step 4: Send a Push Notification Message to a Mobile Endpoint using GCM.

Step 1: Create a Google API Project and Enable the GCM Service

To send an push notification message to an Android app, you must have a Google API project and enable the GCM service.

To create a Google API project and enable the GCM service

  1. If you do not already have a Google API project, then see the Creating a Google API project in the Android developer documentation.

    Note

    If you do not already have an Android app registered with GCM, then you can use the sample Android app provided by AWS as a template to get started. For more information, see Step 3: Obtain a Registration ID from GCM.

  2. On the Google APIs Console web site, verify that you have an Google API project.

  3. Click Services, and make sure Google Cloud Messaging for Android is turned on.

Step 2: Obtain the Server API Key

To communicate with GCM on your behalf, Amazon SNS uses your server API key. This key will be used in a later step to send a push notification to a mobile endpoint.

To obtain the server API key

  1. On the Google APIs Console web site, click API Access and make note of the server API key with the Key for server apps (with IP locking) label.

  2. If you have not yet created a server API key, then click Create new Server key. This key will be used later in this section to send a push notification to a mobile endpoint.

Step 3: Obtain a Registration ID from GCM

When you register your app with GCM to receive push notification messages, a registration ID is generated. Amazon SNS uses this value to determine which app and associated device to send mobile push notifications to.

The following steps show how to use the sample Android app provided by AWS to obtain a registration ID from GCM. You can use this sample Android app to help you get started with Amazon SNS push notifications. This sample app requires the Android SDK, the Google Play Services SDK, and the Android Support Library package. For more information about these SDKs, see Get the Android SDK and Setup Google Play Services SDK. For more information about the Android Support Library package, see Support Library Setup.

Note

The provided sample Android app is compatible with physical devices running Android version 2.3 or later and with virtual devices running Google API 17 or later.

To obtain a registration ID from GCM for your app

  1. Download and unzip the snsmobilepush.zip file.

  2. Import the AndroidMobilePushApp folder into your IDE. In Eclipse, click File, Import, expand the Android folder, click Existing Android Code Into Workspace, click Next, browse to the folder AndroidMobilePushApp, click OK, and then click Finish.

    After the sample Android app has been imported into your IDE, you need to add the Project Number for your Google API project to the strings.xml file, which is included in the sample Android app.

  3. Add the Project Number for your Google API project to the strings.xml file. In your IDE, you will find the file included in the values folder, which is a subfolder of res. The string will look similar to the following:

    
    <string name="project_number">012345678912</string>
                    

  4. Add google-play-services.jar, android-support-v4.jar, and android.jar to the Java Build Path. Select google-play-services.jar and android-support-v4.jarfor export, but do not select android.jar for export.

  5. Run the app to see the registration ID as output to the Android logging system. If you are using Eclipse with the Android ADT plug-in, you can see the registration ID in the LogCat display window. For example, the output containing the registration ID will look similar to the following:

    
    06-05 11:50:43.587: V/Registration(14146): Registered, registrationId: = Examplei7fFachkJ1xjlqT64RaBkcGHochmf1VQAr9k-IBJtKjp7fedYPzEwT_Pq3Tu0lroqro1cwWJUvgkcPPYcaXCpPWmG3Bqn-wiqIEzp5zZ7y_jsM0PKPxKhddCzx6paEsyay9Zn3D4wNUJb8m6HXrBf9dqaEw, error = null, unregistered = null
                    

    The installed app will appear on your Android device:

You should now have a registration ID, server API key, and Android app registered with GCM. You can now send a notification to the Android app on your device by either using the Amazon SNS console or the Amazon SNS API. To use the Amazon SNS console, see Using Amazon SNS Mobile Push. To use the Amazon SNS API, see Step 4: Send a Push Notification Message to a Mobile Endpoint using GCM.

Step 4: Send a Push Notification Message to a Mobile Endpoint using GCM

This section describes how to send a push notification message to your mobile endpoint. You add the gathered prerequisite information to the AWS sample file SNSMobilePush.java, which is included in the snsmobilepush.zip file.

Note

The following steps use the Eclipse Java IDE. The steps assume you have installed the AWS SDK for Java and you have the AWS security credentials for your AWS account. For more information, see AWS SDK for Java. For more information about credentials, see How Do I Get Security Credentials? in the AWS General Reference.

To add the sample to Eclipse

  1. In Eclipse, create a new Java project (File | New | Java Project).

  2. Import the SNSSamples folder to the top-level directory of the newly created Java project. In Eclipse, right-click the name of the Java project and then click Import, expand General, click File System, click Next, browse to the SNSSamples folder, click OK, and then click Finish.

  3. In the SNSSamples/src/com/amazonaws/sns/samples/mobilepush folder, open the AwsCredentials.properties file and add your AWS security credentials.

To add the AWS SDK for Java to the Build Path

  1. Right-click the Java project folder, click Build Path, and then click Configure Build Path...

  2. Click the Libraries tab, and then click Add Library....

  3. Click AWS SDK for Java, click Next, and then click Finish.

To add the prerequisite information to SNSMobilePush.java

  1. In the SNSSamples/src/com/amazonaws/sns/samples/mobilepush folder, open SNSMobilePush.java in Eclipse and uncomment sample.demoAndroidAppNotification();. It should look similar to the following:

    
    SNSMobilePush sample = new SNSMobilePush(sns);
    // TODO: Uncomment the services you wish to use.
    sample.demoAndroidAppNotification();
    // sample.demoKindleAppNotification();
    // sample.demoAppleAppNotification();
    // sample.demoAppleSandboxAppNotification();
    // sample.demoBaiduAppNotification();
    // sample.demoWNSAppNotification();
    // sample.demoMPNSAppNotification();
                        

  2. Locate the demoAndroidAppNotification method and enter the registration ID you received from GCM for the value of the registration ID string. For example, it should look similar to the following:

    String registrationId = = "EXAMPLE-kLMchcX0v3xOxWVhG6TfdBp...KT2TGkvnKyTvLuSpzK_qsHgxVB_UpmcUa7Gl6g3EXAMPLE";

  3. Enter the API key for your application. For example, it should look similar to the following:

    String serverAPIKey = "EXAMPLExV2lcV2zEKTLNYs625zfk2jh4EXAMPLE";
  4. Enter a name for your application. Application names must be made up of only uppercase and lowercase ASCII letters, numbers, underscores, hyphens, and periods, and must be between 1 and 256 characters long. For example, it should look similar to the following:

    String applicationName = "gcmpushapp";
  5. Run the application. You should see output similar to the following in the output window of your IDE:

    
    ===========================================
    Getting Started with Amazon SNS
    ===========================================
    
    {PlatformApplicationArn: arn:aws:sns:us-west-2:111122223333:app/GCM/gcmpushapp}
    {EndpointArn: arn:aws:sns:us-west-2:111122223333:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3}
    {"default":"This is the default message","GCM":"{\"delay_while_idle\":true,\"collapse_key\":\"Welcome\",\"data\":{\"message\":\"Visit Amazon!\",\"url\":\"http://www.amazon.com/\"},\"time_to_live\":125,\"dry_run\":false}"}
    Published.  MessageId=1ca8d7d1-c261-5bfc-8689-9db269c4e46c
                    

    On your Android device, you should see a push notification message appear within the Android app, similar to the following: