Push It Real Good

Push notification is one of those things that seems simpler going in...

Please notice that this code and implementation is highly experimental and we are still working out the kinks. It is also only enabled for paid accounts in Codename One due to some of the server side infrastructure we need to maintain to support this feature.

Push notification allows you to send a message to a device, usually a simple text message which is sent to the application or prompted to the user appropriately. When supported by the device it can be received even when the application isn't running and doesn't require polling which can drain device battery life.
The keyword here is "when supported" unfortunately not all devices support push notification e.g. Android device that don't have the Google Play application (formerly Android Market) don't support push and must fall back to polling the server... Not ideal.

Currently we support pushing to Google authorized Android devices: C2DM (Cloud To Device Messaging) and to iOS devices: Push Notification.
For other devices we will fallback to polling the server in a given frequency, not an ideal solution by any means so we give you the option to not fallback.

This is how Apple describes push notification (image source Apple):

The "provider" is the server code that wishes to notify the device. It needs to ask Apple to push to a specific device and a specific client application. There are many complexities not mentioned here such as the need to have a push certificate or how the notification to APNS actually happens but the basic idea is identical in iOS and Android's C2DM.

Codename One hides some but not all of the complexities involved in the push notification process. Instead of working between the differences of APNS/C2DM & falling back to polling, we effectively do everything that's involved.

Push consists of the following stages on the client:

1. Local Registration - an application needs to register to ask for push. This is done by invoking:
   Display.getInstance().registerPush("gmail email account for C2DM", fallback);
   
   The fallback flag indicates whether the system should fallback to polling if push isn't supported.
   On iOS this stage prompts the user indicating to him that the application is interested in receiving push notification messages.
2. Remote registration - once registration in the client works, the device needs to register to the cloud. This is an important step since push requires a specific device registration key (think of it as a "phone number" for the device).  Normally Codename One registers all devices that reach this stage so you can push a notification for everyone, however if you wish to push to a specific device you will need to catch this information! To get push events your main class (important, this must be your main class!) should implement the PushCallback interface. The registeredForPush(String) callback is called with the unique device ID that can be used later on when pushing to this particular device.
3. In case of an error during push registration you will receive the dreaded: pushRegistrationError.
   This is a very problematic area on iOS, where you must have a package name that matches EXACTLY the options in your provisioning profile which is setup to support push. It is also critical that you do not use a provisioning profile containing a * character in it.
   
4. You will receive a push callback if all goes well.

Sending the push requires two different things for Google and  iOS. In C2DM (Google) you send a push via a gmail address (you need to apply to get a larger quota) and once you have that quota you can just start sending push notifications.

To prove that you indeed have the account you need a Google auth key which you can retrieve by calling:

https://codename-one.appspot.com/googleAuth?email=youremail@gmail.com&password=yourpassword

The key occasionally expires so be sure to refresh it. You can optionally send us your Google credentials when pushing a message via the server API and we will retrieve the key automatically.
For privacy concerns we recommend setting up a separate account that will be used for push alone and not using your standard Google account to perform push operations.

For iOS developers must download a push certificate from the iOS provisioning portal for the given application. Notice that by enabling push you will probably need to regenerate the provisioning profile as well and download/replace your existing provisioning profile.
The certificate must be converted to a p12 certificate as I explained in the provisioning profile tutorial.  

Currently we don't have the option to send the iOS certificate as part of the push request so you will have to host it somewhere and provide us with the link.

To send a push message use the following web API:
https://codename-one.appspot.com/sendPushMessage?auth=googleAuthKey&
packageName=packageNameOfApplication&
email=gmailAccount&
device=theDeviceKey&
type=1&
production=true/false&
certPassword=pass&
cert=CertificateURL

Notice the following arguments in particular:

• device - this is an optional argument, to send to all devices just omit this argument. To send to a particular device you need to provide its key which was given in the registeredForPush() callback.
• type - this must currently be set to 1, there will be additional types in the future
• production - iOS has production and development push services each of which requires a different certificate. Its important to pick the right one. Pass true for production and false for development.
• cert - the URL for the iOS push certificate which you are hosting.
• certPassword - the password of the certificate

Again take into consideration that this is an early stage release with multiple bugs.