APNS

a gem for the Apple Push Notification Service. This project was forked from https://github.com/jpoz/APNS by jpoz
and schandra. This fork adds support for the Apple’s Enhanced Notification Format and aims to have better test coverage.

The API and the code have been refactored and tweaked with the aim of making them more modular and testable.

Install

sudo gem install apns

Setup:

Convert your certificate

In Keychain access export your certificate as a p12. Then run the following command to convert it to a .pem

  
    openssl pkcs12 -in cert.p12 -out cert.pem -nodes -clcerts

After you have your .pem file. Set what host, port, certificate file location on the APNS class:

  
    APNS.host = 'gateway.push.apple.com' 
    # gateway.sandbox.push.apple.com is default

    APNS.pem  = '/path/to/pem/file'
    # this is the file you just created
    
    APNS.port = 2195 
    # this is also the default. Shouldn't ever have to set this, but just in case Apple goes crazy, you can.

Example (Single notification):

Then to send a push notification you can either just send a string as the alert or give it a hash for the alert, badge and sound.

  
    device_token = '123abc456def'

    APNS::NotificationSender.send_notification(device_token, 'Hello iPhone!' )

    APNS::NotificationSender.send_notification(device_token, :alert => 'Hello iPhone!', :badge => 1, :sound => 'default')

Example (Multiple notifications):

You can also send multiple notifications using the same connection to Apple:

  
    device_token = '123abc456def'

    n1 = APNS::Notification.new(device_token, 'Hello iPhone!' )

    n2 = APNS::Notification.new(device_token, :alert => 'Hello iPhone!', :badge => 1, :sound => 'default')
    
    APNS::NotificationSender.send_notifications([n1, n2])

Send other info along with aps

You can send other application specific information as well.

  
    APNS::NotificationSender.send_notification(device_token, :alert => 'Hello iPhone!', :badge => 1, :sound => 'default',
                                         :other => {:sent => 'with apns gem'})

This will add the other hash to the same level as the aps hash:

  
    {"aps":{"alert":"Hello iPhone!","badge":1,"sound":"default"},"sent":"with apns gem"}

Enhanced Notification Format and Detecting Errors

Sending notifications can fail due to a number of reasons. The way the Apple notifications servers work is that,
they will let you know only if something goes wrong and only if you are using the enhanced notification format.

Single Notifications

When sending single notifications. The gem will send the notification and will wait for 1 second for the APNS to send
a error message. This is usually enough time for the APNS to send a error message if it decides that your notification
has some error in it.

When you send a notification you will get a return value. Depending on whether there was any error you would get a
error or nil.

  
    device_token = '123abc456def'

    result = APNS::NotificationSender.send_notification(device_token, 'Hello iPhone!' )

The error object is a map containing the error.

    
        {
              :notification_id => 2,
              :error           => {
                  :type        => 8,
                  :code        => 7,
                  :description => "Invalid payload size"
              }
          }

Description of the fields in the error map

notification_id – The id of the notification that failed. When sending single notifications the notification_id
is always 0. When sending multiple notifications this indicate the position (0 based index) of the notification
(which resulted in the error) in the array of notifications sent to the send_notifications method.
type – this is always 8. Its the type of the message sent by the APNS.
code – error code
description – description of the error

Multiple Notifications

When sending multiple notifications you will get a array as the return value from the send_notifications method. This
contains a collection of map objects which details the errors occurred while sending notifications.

    
        [
            {
                :token => "device_token_to_which_the_failed_notification_was_sent",
                :error =>
                         {
                              :notification_id => 2,
                              :error           => {
                                  :type        => 8,
                                  :code        => 7,
                                  :description => "Invalid payload size"
                              }
                          }
            }
        ]

Getting your iPhone’s device token

After you setup push notification for your application with Apple. You need to ask Apple for you application specific device token.

ApplicationAppDelegate.m



  
    - (void)applicationDidFinishLaunching:(UIApplication *)application {    
        // Register with apple that this app will use push notification
        [[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | 
          UIRemoteNotificationTypeSound | UIRemoteNotificationTypeBadge)];	
    }
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
// Show the device token obtained from apple to the log
NSLog("deviceToken: %", deviceToken);
}

troex/APNS