NAME

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

SYNOPSIS

  # 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');

DESCRIPTION

WebService::UrbanAirship::APNS contains useful routines for using the Apple Push Notification Service for the iPhone provided by Urban Airship, as described in http://urbanairship.com/docs/push.html

to use these routines you will need to visit http://urbanairship.com/ 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...

CONSTRUCTOR

new()

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

application_key

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

application_secret

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

application_push_secret

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.

METHODS

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 http://urbanairship.com/docs/push.html, 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.

register_device()

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.

parallels http://urbanairship.com/docs/push.html#registration

ping_device()

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 http://urbanairship.com/docs/push.html#registration

push()

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]);

parallels http://urbanairship.com/docs/push.html#push

batch()

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()

parallels http://urbanairship.com/docs/push.html#batch-push

broadcast()

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.

parallels http://urbanairship.com/docs/push.html#broadcast

feedback()

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.

parallels http://urbanairship.com/docs/push.html#feedback-service

stats()

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.

parallels http://urbanairship.com/docs/push.html#statistics

DEBUGGING

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;

SEE ALSO

http://urbanairship.com/docs/push.html

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

AUTHOR

Geoffrey Young <geoff@modperlcookbook.org>

http://www.modperlcookbook.org/

COPYRIGHT

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.