NAME

Net::APNS::Persistent - Send Apple APNS notifications over a persistent connection

SYNOPSIS

  use Net::APNS::Persistent;

  my $devicetoken_hex = '04ef...a878416';
  
  my $apns = Net::APNS::Persistent->new({
    sandbox => 1,
    cert    => 'cert.pem',
    key     => 'key.pem',
    passwd  => 'key password',
  });

  $apns->queue_notification(
    $devicetoken_hex,
    {
      aps => {
          alert => 'sweet!',
          sound => 'default',
          badge => 1,
      },
    });
  
  $apns->send_queue;

  $apns->disconnect;

You can queue more than one notification in one transmission by calling queue_notification multiple times. If you want to pass in utf8 text in the alert (either as a string or alert->body), you need to be careful with the encoding. See the test files for an example of reading utf8 from a text file. You should also be able to pass utf8 through from eg. a database in a similar way.

You can also use the connection many times (ie. queue then send, queue then send, ad nauseum). The call to disconnect is not strictly necessary since the object will disconnect as soon as it falls out of scope.

You can place your own custom data outside the aps hash. See the Apple Push Notification Service Programming Guide for more info.

All methods are fatal on error. Eg. if the ssl connection returns an error, the code will die. You can either then just restart your script or you can use eval to catch the exception.

DESCRIPTION

Class to create a persistent connection to Apple's APNS servers

METHODS

new

Args:

sandbox

set to true if you want to use the sandbox host. defaults to 0. ignored if you set the host manually

cert

path to your certificate

cert_type

defaults to PEM - see Net::SSLeay.

key

path you your private key

key_type

defaults to PEM - see Net::SSLeay.

passwd

password for your private key, if required.

host

defaults to gateway.push.apple.com or gateway.sandbox.push.apple.com depending on the setting of sandbox. can be set manually.

port

defaults to 2195

command

defaults to 0

NB: all these args are available as accessors, but you need to set them before the connection is first used.

queue_notification

takes two arguments - a device token (as a string representation of hex), and a hashref with the payload. eg:

  my $devicetoken_hex = '04ef...a878416';

  $apns->queue_notification(
    $devicetoken_hex,
    {
      aps => {
          alert => 'sweet!',
          sound => 'default',
          badge => 1,
      },
    });

  $apns->queue_notification(
    $devicetoken_hex,
    {
      aps => {
          alert => {
              body => 'foo',
              'action-loc-key' => undef,
          },
          sound => 'default',
          badge => 1,
      },
      foo => 'bar',
    });

The second example shows the complex alert format and also custom application data outside the aps hash.

This method will ensure that the payload is at most 256 bytes by trimming the alert body. The trimming function is utf8-safe, but not very efficient (so don't ask it to trim War and Peace).

send_queue

This will actually send the data to the ssl connection.

disconnect

Disconnect the ssl connection and socket, and free the ssl structures. This usually isn't necessary as this will happen implicitly when the object is destroyed.

SEE ALSO

Presentation on this module by Author

http://mark.aufflick.com/talks/apns

Apple Push Notification Service Programming Guide

http://developer.apple.com/IPhone/library/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Introduction/Introduction.html

Net::APNS::Feedback

GIT Source Repository for this module

http://github.com/aufflick/p5-net-apns-persistent

AUTHOR

Mark Aufflick, <mark@aufflick.com>, http://mark.aufflick.com/

CREDITS

Some inspiration came from haoyayoi's Net::APNS.

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Mark Aufflick

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.

cpanm Net::APNS::Persistent

perl -MCPAN -e shell
install Net::APNS::Persistent