<img src="icon.png" alt="Pusher Icon" width="72"/>

Pusher

OS X and iOS application and framework to play with the Apple Push Notification service (APNs)

<img src="Docs/osx1.png" alt="Pusher OS X" width="612"/>

Installation

Install the Mac app using Homebrew cask:

brew cask install pusher

Or download the latest Pusher.app binary:

• Download latest binary

Alternatively, you can include NWPusher as a framework, using CocoaPods:

pod 'NWPusher', '~> 0.7.0'

or Carthage (iOS 8+ is required to use Cocoa Touch Frameworks)

github "noodlewerk/NWPusher"

Or simply include the source files you need. NWPusher has a modular architecture and does not have any external dependencies, so use what you like.

About

Testing push notifications for your iOS or Mac app can be a pain. You might consider setting up your own server or use one of the many push webservices online. Either way it's a lot of work to get all these systems connected properly. When it is all working properly, push notifications come in fast (< 1 sec) and reliably. However when nothing comes in, it can be very hard to find out why.

That's why I made Pusher. It is a Mac and iPhone app for sending push notifications directly to the Apple Push Notification Service. No need to set up a server or create an account online. You only need the SSL certificate and a device token to start pushing directly from your Mac, or even from an iPhone! Pusher has detailed error reporting and logs, which are very helpful with verifying your setup.

Pusher comes with a small framework for both OS X and iOS. It provides various tools for sending notifications programmatically. On OS X it can use the keychain to retrieve push certificates and keys. Pusher can also be used without keychain, using a PKCS #12 file. If you want to get a better understanding of how push notifications work, then this framework is a good place to start and play around.

Features

Mac OS X application for sending push notifications through the APN service:

• Takes certificates and keys directly from the keychain
• Fully customizable payload with syntax checking
• Allows setting expiration and priority
• Stores device tokens so you don't have to copy-paste them every time
• Handles PKCS #12 files (.p12)
• Automatic configuration for sandbox
• Reports detailed error messages returned by APNs
• Reads from feedback service

OS X and iOS framework for sending pushes from your own application:

• Modular, no dependencies, use what you like
• Fully documented source code
• Detailed error handling
• iOS compatible, so you can also push directly from your iPhone :o
• Demo applications for both platforms

Getting started

Before you can start sending push notification payloads, there are a few hurdles to take. First you'll need to obtain the Apple Push Services SSL Certificate of the app you want to send notifications to. This certificate is used by Pusher to set up the SSL connection through which the payloads will be sent to Apple.

Second you'll need the device token of the device you want to send your payload to. Every device has its own unique token that can only be obtained from within the app. It's a bit complicated, but in the end it all comes down to just a few clicks on Apple's Dev Center website, some gray hairs, and a bit of patience.

Certificate

Let's start with the SSL certificate. The goal is to get both the certificate and the private key into your OS X keychain. If someone else already generated this certificate, you'll need to ask for exporting these into a PKCS12 file. If there is no certificate generated yet, you can generate the certificate and the private key in the following steps:

1. Log in to Apple's Dev Center
2. Go to the Provisioning Portal or Certificates, Identifiers & Profiles
3. Go to Certificates and create a Apple Push Notification service SSL
4. From here on you will be guided through the certificate generation process.

Keep in mind that you will eventually be downloading a certificate, which you will need to install in your keychain together with the private key. This should look something like this:

<img src="Docs/keychain1.png" alt="Keychain export" width="690"/>

NB: There is Development and Production certificates, which should (generally) correspond to respectively DEBUG and RELEASE versions of your app. Make sure you get the right one, check Development (sandbox) or Production, iOS or Mac, and the bundle identifier.

The push certificate should be exported to a PKCS12 file, which allows you to share these with fellow developers:

<img src="Docs/keychain2.png" alt="PKCS12 file" width="690"/>

Device token

Now you need to obtain a device token, which is a 64 character hex string (256 bits). This should be done from within the iOS app you're going to push to. Add the following lines to the application delegate (Xcode 6 required):

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    if ([application respondsToSelector:@selector(registerUserNotificationSettings:)]) {
        NSLog(@"Requesting permission for push notifications..."); // iOS 8
        UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:
            UIUserNotificationTypeAlert | UIUserNotificationTypeBadge |
            UIUserNotificationTypeSound categories:nil];
        [UIApplication.sharedApplication registerUserNotificationSettings:settings];
    } else {
        NSLog(@"Registering device for push notifications..."); // iOS 7 and earlier
        [UIApplication.sharedApplication registerForRemoteNotificationTypes:
            UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge |
            UIRemoteNotificationTypeSound];
    }
    return YES;
}

- (void)application:(UIApplication *)application
    didRegisterUserNotificationSettings:(UIUserNotificationSettings *)settings
{
    NSLog(@"Registering device for push notifications..."); // iOS 8
    [application registerForRemoteNotifications];
}

- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)token
{
    NSLog(@"Registration successful, bundle identifier: %@, mode: %@, device token: %@",
        [NSBundle.mainBundle bundleIdentifier], [self modeString], token);
}

- (void)application:(UIApplication *)application
    didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
    NSLog(@"Failed to register: %@", error);
}

- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier
    forRemoteNotification:(NSDictionary *)notification completionHandler:(void(^)())completionHandler
{
    NSLog(@"Received push notification: %@, identifier: %@", notification, identifier); // iOS 8
    completionHandler();
}

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)notification
{
    NSLog(@"Received push notification: %@", notification); // iOS 7 and earlier
}

- (NSString *)modeString
{
#if DEBUG
    return @"Development (sandbox)";
#else
    return @"Production";
#endif
}

Now, when you run the application, the 64 character push string will be logged to the console.

Push from OS X

With the SSL certificate and private key in the keychain and the device token on the pasteboard, you're ready to send some push notifications. Let's start by sending a notification using the Pusher app for Mac OS X. Open the Pusher Xcode project and run the PusherMac target:

<img src="Docs/osx1.png" alt="Pusher OS X" width="612"/>

The combo box at the top lists the available SSL certificates in the keychain. Select the certificate you want to use and paste the device token of the device you're pushing to. The text field below shows the JSON formatted payload text that you're sending. Read more about this format in the Apple documentation under Apple Push Notification Service.

Now before you press Push, make sure the application you're sending to is in the background, e.g. by pressing the home button. This way you're sure the app is not going to interfere with the message, yet. Press push, wait a few seconds, and see the notification coming in.

If things are not working as expected, then take a look at the Troubleshooting section below.

<img src="Docs/osx2.png" alt="Pusher OS X" width="612"/>

Push from iOS

The ultimate experience is of course pushing from an iPhone to an iPhone, directly. This can be done with the Pusher iOS app. Before you run the PusherTouch target, make sure to include the certificate, private key, and device token inside the app. Take the PKCS12 file that you exported earlier and include it in the PusherTouch bundle. Then go to NWAppDelegate.m in the Touch folder and configure pkcs12FileName, pkcs12Password, and deviceToken. Now run the PusherTouch target:

<img src="Docs/ios.png" alt="Pusher iOS" width="414"/>

If everything is set up correctly, you only need to Connect and Push. Then you should receive the Testing.. push message on the device.

Again, if things are not working as expected, take a look at the Troubleshooting section below or post an issue on GitHub.

Consult Apple's documentation for more info on the APNs architecture: Apple Push Notification Service

Pushing from code

Pusher can also be used as a framework to send notifications programmatically. The included Xcode project provides examples for both OS X and iOS. Th