     _                 _               _          _ _
 ___(_)_ __ ___  _ __ | | ___  _ __   | |__   ___| (_)_   _ _ __ ___
/ __| | '_ ` _ \| '_ \| |/ _ \| '_ \  | '_ \ / _ \ | | | | | '_ ` _ \
\__ \ | | | | | | |_) | | (_) | | | | | | | |  __/ | | |_| | | | | | |
|___/_|_| |_| |_| .__/|_|\___/|_| |_| |_| |_|\___|_|_|\__,_|_| |_| |_|
                |_|

Simplon/Helium

For one of my projects I had the need to talk to Urbain Airship's Push API.
So, I took today off to write an abstract project as composer package so that it is easy to implement in other projects too.

Setup

Since its a composer package all you need to to do is require it within your composer package definitions and install/update it:

{
     "require": {
        "simplon/helium": "1.1.*"
     }
}

If you dont know what composer is you should have a look at Composer's Webpage.

Anything else needed?

Since we're relying here on Urban Airship's Push API you should have registered yourself to receive:

1x Key
1x Secret Key
1x Master Secret Key

If you did not register yourself yet just head over here and register for Urbain Airship's.
The basic plan is free and offers 1,000,000 free notifications / month. That gets us started. Sweet!

A Simple Example

1. Add Device Token

The simplest creation of a device token would be as followed:

// API keys
$key = '12345';
$secret = '12345';

// device token entity
$deviceToken = \Simplon\Helium\DeviceToken::init()->setToken('111111222233344455AAABBBCCCDDDD');

// remote register device token
$response = \Simplon\Helium\Air::init()
     ->setApplicationKey($key)
     ->setApplicationSecret($secret)
     ->registerDeviceToken($deviceToken);

You're cool if your response results in "OK". If not, dont worry you're still cool but your token didn't get registered unfortunately.
Make sure that you used the correct authentication keys.

2. Send Push Notification

Based on the device token we just registered we can now send a notification to the device via:

// API keys
$key = '12345';
$secret = '12345';
$master = '12345';

// push notification entity
$pushNotifications = array();
$pushNotifications[] = \Simplon\Helium\PushNotification::init()
     ->setDeviceTokens(array('111111222233344455AAABBBCCCDDDD'))
     ->setAlert("Howdy!")
     ->getData();

// send push to UA's API
$response = \Simplon\Helium\Air::init()
     ->setApplicationKey($key)
     ->setApplicationSecret($secret)
     ->setApplicationMasterSecret($master)
     ->setNotifications($pushNotifications)
     ->sendSinglePush();

If all went through your response should result in something like:

{ "push_id": "12345-1ad5-11e2-b16d-001b21ce3d90" }

Meanwhile you also should have received your push notification on your device.

An Example with more options

Well, as always there is more. Registering/managing a device token offers the following other options:

$deviceToken = \Simplon\Helium\DeviceToken::init()
     ->setToken('111111222233344455AAABBBCCCDDDD')
     ->setAlias('USER_ID')
     ->setTags(array('tag1', 'tag2'))
     ->setBadge(5)
     ->setQuietTime('22:00', '8:00')
     ->setTimezone('Europe/Berlin');

Now, if we come back to sending a push notification to our device we can use the alias instead of the deviceToken:

// API keys
$key = '12345';
$secret = '12345';
$master = '12345';

// push notification entity
$pushNotifications = array();
$pushNotifications[] = \Simplon\Helium\PushNotification::init()
     ->setAliases(array('USER_ID'))
     ->setAlert("Howdy again!")
     ->setMetadata('type', 'fresh')
     ->setMetadata('smile', 'on')
     ->getData();

// send push to UA's API
$response = \Simplon\Helium\Air::init()
     ->setApplicationKey($key)
     ->setApplicationSecret($secret)
     ->setApplicationMasterSecret($master)
     ->setNotifications($pushNotifications)
     ->sendSinglePush();

We also could have used setTags(array('tag1')) to define our notification recipients.