Release Notes: (1.1.5)
  • Parameters for "data" added - np_notif_sound, np_notif_vibrate.

Integration Guide - Google Cloud Messaging (Remote Push Notifications) Plugin

Platforms: Android
Plugin version: 1.1.5
Google Play Services version: 6.1.11

Follow a few steps below to get the plugin integrated in your App in minutes:

[1] Import the NativeGCMAndroid.unitypackage file to your unity project;

[2] Follow the instructions below to configure the plugin.

· >>> For Android platform, click on the menu item of Unity top menu bar: NeatPlug -> NativeGCM -> Patch Android Configuration. This is for generating a valid AndroidManifest.xml or patching the existing file with NativeGCM support.


· NOTE: To show a local notification in the status bar, you need to add the following parameters to "data" when sending the c2dm (Cloud to Device Message) from your server:

  • np_notif_local: "true" for creating a local notification when a cloud message is received, "false" for not.
  • np_notif_title: Your notification title.
  • np_notif_message: Your notification message.
  • np_notif_ticker: Your notification ticker text.
  • np_notif_largeicon: The URL of the custom large icon image.
  • np_notif_deeplink: A link that will be automatically opened when the notification is clicked.
  • np_notif_sound: The URL of the custom sound media file.
  • np_notif_vibrate: "true" for enable vibrate, "false" for not.

· NOTE: To get local notification working, you need to have our NativeNotification Plugin imported.

[3] Find NativeGCMAgent Prefab and NativeGCMListener Prefab in Assets/Plugins/NeatPlug/Native/NativeGCM/Prefabs/, open the first scene of your game, drag & drop those two prefabs into the scene.

[4] Okay, the integration is done here. Now set up the plugin by filling in a few properties of the NativeGCMAgent gameObject which you just dropped in the Hierarchy window. To do this, simply select that gameObject, and look at its properties in the Inspector window, you need to fill in:

   · Sender Ids - Your GCM Sender IDs (The Project Number you can get from Google APIs Console).

   · Auto Register Device - Check this if you want the device to be automatically registered on GCM when the first time the App starts.

   · Server Receive Device Reg Id URL - Supply this param if you want to post the device registration ID to your server. Learn more

Use the plugin by calling following functions:

  Use the plugin:

   · NativeGCM.Instance().UnregsiterDevice() - Unregister the device from GCM.

   · NativeGCM.Instance().SendMessageToCloud(...) - Send a "device-to-cloud" message to cloud from the device.

  There are other useful public methods that NativeGCM provides, to use them, simply call NativeGCM.methodName().
Show All   
public void Init(string[] senderIds, bool autoRegisterDevice, string serverReceiveDeviceRegIdURL)
/**
 * Initialization.
 * 
 * @param senderIds
 *              string[] - A list of GCM Sender IDs that can be obtained from Google+ dashboard.
 * 
 * @param autoRegisterDevice
 *              bool - True for automatically registering device, false for not.
 * 
 * @param serverReceiveDeviceRegIdURL
 *              string - Setting a valid URL on your own server enables posting the
 *                       user device registration ID to your server, this is required 
 *                       to send cloud notification to the device from your server.	
 * 
 */
public void Init(string[] senderIds, bool autoRegisterDevice, string serverReceiveDeviceRegIdURL)
public void RegisterDevice()
/**
 * Register the device on GCM, so that the device can receive cloud notifications.
 * 
 * Generally you don't need to call this function if you have checked the
 * "Auto Register Device" option on NativeGCMAgent.
 * 
 * The registration is happening when the first time the App starts, and once the
 * device is registered, no need to make further register device call unless you 
 * have called UnregisterDevice().
 * 
 * Your App will get notified via NativeGCMListener::OnDeviceRegistered() when the
 * registration succeeded, or via NativeGCMListener::OnFailedToRegisterDevice() when
 * it failed.
 */
public void RegisterDevice()
public void UnregisterDevice()
/**
 * Unregister the device on GCM, so that the device will not be able to 
 * receive cloud notifications.	 
 * 
 * Your App will get notified via NativeGCMListener::OnDeviceUnregistered() when the
 * registration succeeded, or via NativeGCMListener::OnFailedToUnregisterDevice() when
 * it failed.
 */
public void UnregisterDevice()
public void SendMessageToCloud(string senderId, string msgId, ... )
/**
 * Send a message to cloud.
 * 
 * This function can be used to send a testing message to cloud and see if your App can
 * receive that notification from the cloud.
 * 
 * @param senderId
 *           string - The sender ID to which you want the message to be sent. If null,
 *                    The plugin will pick up the first element of your SenderIds property
 *                    of NativeGCMAgent.
 * 
 * @param msgId
 *           string - The message ID you specify to identify the message.
 * 
 * @param timeToLive
 *           long - The life span of the message. (In milliseconds).
 * 
 * @param parameters
 *           Dictionary - The key-val pairs you want to attach to the message
 *                                        so that you can get the data in received notification.
 */
public void SendMessageToCloud(string senderId, string msgId, long timeToLive, 
                              Dictionary<string, string> parameters)
public void PostDeviceRegistrationId()
/**
 * Post the device registration ID to your server.
 * 
 * Generally you don't need to call this function, the plugin will automatically 
 * post the device registration ID to your specified server URL (specified in 
 * "Server Receive Device Reg Id URL" property of NativeGCMAgent) as long as 
 * the device is successfully registered on GCM.
 * 
 * The registration is happening when the first time the App starts, and once the
 * device is registered, no need to make further register device call unless you 
 * have called UnregisterDevice().
 * 
 * Call this function only when you really want to post the registration ID to 
 * your server again.
 */
public void PostDeviceRegistrationId()

[6] To handle events, e.g. get notified when a cloud notification is received on the device. Read this:

  Follow the instructions to handle events:

  · Select the dropped NativeGCMListener gameObject, locate the NativeGCMListener.cs script, open it and make some modifications.

  These callbacks are exposed in the script, you can supply your own implementations in them.
Show All   
void OnDeviceRegistered(string registrationId) { ... }
/**
 * Fired when the user device is successfully registered on GCM.
 * 
 * @param registrationId
 *               string - The registration ID returned by Google.
 */
void OnDeviceRegistered(string registrationId)
{
    /// Your code here...   
}
void OnFailedToRegisterDevice(string err) { ... }
/**
 * Fired when failed to register the user device on GCM.
 * 
 * @param err
 *          string - The error message.
 */ 
void OnFailedToRegisterDevice(string err)
{
    /// Your code here...   
}
void OnDeviceUnregistered() { ... }
/**
 * Fired when the user device is successfully unregistered on GCM.	 
 */
void OnDeviceUnregistered()
{
    /// Your code here...   
}
void OnFailedToUnregisterDevice(string err) { ... }
/**
 * Fired when failed to unregister the user device on GCM.
 * 
 * @param err
 *          string - The error message.
 */
void OnFailedToUnregisterDevice(string err)
{
    /// Your code here...   
}
void OnMessageSentToCloud(string msgId) { ... }
/**
 * Fired when a message is successfully sent to cloud.
 * 
 * @param msgId
 *          string - The message ID.
 */ 
void OnMessageSentToCloud(string msgId)
{
    /// Your code here...   
}
void OnFailedToSendMessageToCloud(string msgId, string err) { ... }
/**
 * Fired when failed to send a message to cloud.
 * 
 * @param msgId
 *          string - The message ID.
 * 
 * @param err
 *          string - The error message.
 */ 
void OnFailedToSendMessageToCloud(string msgId, string err)
{
    /// Your code here...   
}
void OnDeviceRegistrationIdPosted(string registrationId, string response) { ... }
/**
 * Fired when the device registration ID is successfully posted to your server.
 * 
 * @param registrationId
 *          string - The device registration ID.
 * 
 * @param response
 *          string - The server response.
 */
void OnDeviceRegistrationIdPosted(string registrationId, string response)
{
    /// Your code here...   
}
void OnFailedToPostDeviceRegistrationId(string registrationId, string err) { ... }
/**
 * Fired when failed to post the device registration ID to your server.
 * 
 * @param registrationId
 *          string - The device registration ID.
 * 
 * @param err
 *          string - The error message.
 */
void OnFailedToPostDeviceRegistrationId(string registrationId, string err)
{
    /// Your code here...   
}
void OnNotificationReceived(Dictionary<string, string> notification) { ... }
/**
 * Fired when a notification is received from GCM cloud.
 * 
 * @param notification
 *          Dictionary<string, string> - The key-value pairs of the notification.
 */ 
void OnNotificationReceived(Dictionary<string, string> notification)
{
    /// Your code here...   
}

[7] Build your App now.

[8] Test and verify if the device can be registered and clould notifications can be received properly. Also it would be helpful for you to address issues if you take a look at the logcat output (Android) to find the debug / error / warning messages.

[EOF] Should you have any questions or encounter any problems while integrating the plugin, please do not hesitate to shoot us an email at support@neatplug.com, we will be more than happy to help you. Thanks for choosing NeatPlug solutions!