View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Geoffrey Young > WebService-UrbanAirship > WebService::UrbanAirship::APNS



Annotate this POD


New  2
Open  0
View/Report Bugs
Module Version: 0.02   Source  


WebService::UrbanAirship::APNS - routines for Urban Airship Apple Push Notification service


  # create the object
  my $o = WebService::UrbanAirship::APNS->new(application_key         => 'C9mvZ******************8QGW',
                                              application_secret      => 'DQvNtylF***************MgVG',
                                              application_push_secret => 'HGrBg37****************ylFA');

  # now do something, like register the device
  $o->register_device(device_token => 'FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660',
                      alias        => 'de039f61e64d3300aa0ce521fd6a65f780cc814e',

  # and send a notification
  $o->push(device_token => 'FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660');


WebService::UrbanAirship::APNS contains useful routines for using the Apple Push Notification Service for the iPhone provided by Urban Airship, as described in

to use these routines you will need to visit register with as a developer. they will provide you with an application key, and two secret strings which you will need for these routines to work.

while the Urban Airship API is fairly straightforward, a simple wrapper always makes life a bit easier...



instantiate a new WebService::UrbanAirship::APSN object.

  my $o = WebService::UrbanAirship::APNS->new(application_key         => 'C9mvZ******************8QGW',
                                              application_secret      => 'DQvNtylF***************MgVG',
                                              application_push_secret => 'HGrBg37****************ylFA');

the constructor arguments are as follows


the Application Key assigned to your application. this argument is required.


the Application Secret assigned to your application. this argument is required.


the Application Push Secret assigned to your application. this argument is required.

if the required arguments are not provided the interface will die with an error.


all methods return false on failure or true on success. for some methods the true value can be further distilled to provided additional details - see each method description for when this applies.

for the most part, these methods mirror the API described at, so it makes sense to read about the interface there as well.

note that the device token is *not* the device id - you get the token from within the didRegisterForRemoteNotificationsWithDeviceToken method from your application delegate. how you get the device token from the user device to a place where you can call these methods is up to you.


registers a device with Urban Airship, which is required for broadcasts but only recommended for individual pushes.

  my $code = $o->register_device(device_token => $token,
                                 alias        => $alias);

the 'alias' and 'tags' arguments are optional. 'alias' must be a simple string, while '$tags' much be a reference to an array of simple strings.

  my $code = $o->register_device(device_token => $token,
                                 tags         => [$tag1, 'tag 2']);

the return value is false on failure, 201 for when the device is initially created, and 200 for any updates.



ping Urban Airship for information about a registered device.

  my $code = $o->register_device(device_token => $token);

the return value is false on failure, and interesting json on success.

parallels the GET behavior of


sends a single push to one or more devices and/or aliases

  my $code = $o->push(device_tokens => [$token1, $token2],
                      aliases       => [$alias1],
                      badge         => 1,
                      alert         => 'coolio!',
                      sound         => 'cool.caf');

returns false on error, true on success. if 'schedule_for' is included as an argument, a true value will be the scheduled notifications as json.

both the 'device_tokens' and 'aliases' arguments, if present, must be references to arrays. neither is required, but if the total device tokens between the two is zero the method will return false without actually trying to do anything.

all of 'badge', 'alert', and 'sound' are optional, but if none exist the method will return false without actually trying to do anything.

'schedule_for', 'exclude_tokens', and 'tags' are optional arguments. if included, each must be an array:

  my $json = $o->push(tags           => [$tag1, $tag2],
                      badge          => 1,
                      schedule_for   => [$iso8601date],
                      exclude_tokens => [$token]);



sends multiple notifications to multiple devices in a single call

  my $code = $o->batch({ device_tokens => [$token1, $token2],
                         aliases       => [$alias1],
                         badge         => 1,
                       { aliases       => [$alias2, $alias3],
                         alert         => 'gotcha!',

returns false on error, true on success.

batch() accepts one or more hash references, each of which has the same calling semantics as the arguments to push()



sends a notification to every device Urban Airship knows about.

  my $code = $o->broadcast(badge => 3,
                           alert => 'Whoa!',
                           sound => 'annoyme.caf');

returns false on error, true on success.



queries Urban Airship for devices which no longer should receive notifications from your application.

  my $response = $o->feedback(since => $date);

returns false on error, true on success. if successful, the return value is a JSON string listing device tokens and dates.

the 'since' argument should be a properly formatted ISO 8601 date, such as '2009-06-01 13:00:00'. zero checking is done of this date for any kind of validity whatsoever - you're entirely on your own crafting an appropriate date.



returns hourly statistics from Urban Airship

  my $response = $o->stats(start  => '2009-06-01 13:00:00',
                           end    => '2009-07-01',
                           format => 'csv');

the 'start' and 'end' arguments are required and must be properly formatted ISO 8601 dates. zero checking is done by this api, blah, blah...

stats() returns false on error, true on success. if successful, the return value contains statistics. by default, the results are in JSON. however, the optional 'format' argument can be used to change response formats. currently, only 'csv' is understood by the Urban Airship API.



if you are interested in verbose error messages when something doesn't go according to plan you can enable debugging as follows:

  use WebService::UrbanAirship::APNS;
  $WebService::UrbanAirship::APNS::DEBUG = 1;



Geoffrey Young <>


Copyright (c) 2009, Geoffrey Young All rights reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

syntax highlighting: