Monday, March 23, 2009

Apple Push Notification Service (APNS)

The Apple Push Notification Service will be launched in this summer and this is one of interesting features of iPhone OS 3.0.

Since the SSL certificate for the APNS for the developer's app is not yet available (update: available now on April 9) in the developer program portal, we need to simulate and test it in our environment at this moment. To prepare for this, we need a client program and a server program (for testing with the client) implementing the TLS communication protocol.

(1) Requirements
The requirement of communication with Apple Push Notification Service (APNS) is described in the "Apple Push Notification Service Programming Guide" and for the developer's view, we need to have a client program to communicate with and send the payload to the APNS

- a "raw" (binary) socket interface which is asynchronous and one-way from developer to APNS
- The binary interface is available through, port 2195
- use TLS (or SSL) to establish a secured communications channel
- The SSL certificate (will be provided from Apple per Application ID from developer portal) is required for these connections
- should present this certificate to APNS at connection time using peer-to-peer authentication.
- should also retain connections with APNS across multiple notifications.

(2) Payload
The maximum size allowed for a notification payload is 256 bytes;
Example of the notification payload

Command : 1 byte (0x00)
Device Token length : 2 bytes (0x00 0x20)
Device Token(binary) : 32 bytes
Payload length : 2 bytes
Payload Content (max 256 bytes): e.g.

"aps" : {
"alert" : {"loc-key":"%@ and %@ have invited you to Dinner","loc-args":["Jenna","Frank"]},
"badge" : 9
"sound" : "happysound.aiff"
"acme1" : "custom property",
"acme2" : 42,
"acme3" : [5,8]

The following example shows the payload message of
{"aps":{"alert":"Message from javacom","badge":9}}
in HexEdit Screen


(3) Pseudocode for this client side program (My iniitial draft for C Code)

Client code for TLS v1 protocol
Needs openssl crypto lib

At first
Initialisation of TLS Context and return SSL Context
SSL_CTX *ctx;
SSL *ssl;

SSL_CTX object is created as a framework to establish TLS/SSL enabled connections
use SSL_CTX_new to create a new context
SSL_CTX should include the tls stuff for SSL certificate handling
use SSL_CTX_set_client_cert_cb(ctx, client_cert_cb) to provide client SSL cert.

socket is created for the APNS
int sock;
struct sockaddr_in server;

connect socket
connect(sock, (struct sockaddr *)&server, sizeof(server))

Then associate the network connection with the object

create a new SSL structure for a connection

connect the SSL object with a socket file descriptor
SSL_set_app_data(ssl, conn);
SSL_set_fd(ssl, sock)

Set ssl to work in client mode (that is to connect)

Then the TLS/SSL handshake is performed
Connect SSL
If connect successful
Compose Payload
sendPayload using SSL_write (this part was given by Apple)

If connect unsuccessful, handle error

If Payload sent or reach maximum retries
Then Shut down the TLS/SSL connection.
Destroy SSL Context
SSL_CTX_free(ctx); ctx = NULL

(4) Other aspects (TO-DOs)
- Keep the definitive count of data items remaining to be downloaded.
- Regularly connect with the feedback web server and fetch the current list of those devices that have repeatedly reported failed-delivery attempts.
- iPhone client program

see update here


Anonymous said...

Ok, nice overview - thanks! But, I wonder how do you ensure that this message gets sent to the desired iphone device??

javacom said...

The delivery of payload is not guaranteed. You have to connect with the feedback web server and fetch the current list of those devices that have reported failed-delivery attempts.

Anonymous said...

How can I compose the payload for this message?

Can u please give some sample for composing payload?

javacom said...

For the source code to push payload message to the APNS, you can find it in the Developer Forum.

Anonymous said...

Did anyone get this push notification working with C code?

We get the device token from APNS service which is in hex decimal format.

<5u79cfda 4d01ga3a 11c833f9 7b52df2a 7g210252 e21b01fa a73d3463 9ge0e412>

I make the call to [[UIApplication sharedApplication] registerForRemoteNotifications], but I never recieve a callback in didRegisterForRemoteNotificationsWithDeviceToken

And the based on the document to send notification via raw message device token has to be 32 bytes binary.
char *deviceTokenBinary (32 bytes)

How can we convert the hex decimal format to 32 bytes device token binary?

Discovering Tech said...

Thanks for such a nice article.We are trying to build iphone application for this so can you suggest where can we get more help regarding this?


AniP said...

can someone give me some basic idea how can i create an app about news feed that utilizes the push notification. The idea is to notify student using push in iPhone or iPod touch. I appreciate if someone can help me. thanks. email:

Anonymous said...

How can i create a push notification? What is its steps?

Peter Campbell said...

Great overview would you be able to post your .c code?
I am trying to write my own .c client and getting a bit stuck thanks.