WebService::Pushwoosh - An interface to the Pushwoosh Remote API v1.3
# Create a WebService::Pushwoosh instance my $pw = WebService::Pushwoosh->new( app_code => '00000-00000', api_token => 'YOUR_APP_TOKEN' ); # Send a message to all your app's subscribers $pw->create_message(content => "Hello, world!"); # Limit to one device $pw->create_message( content => 'Pssst', devices => ['dec301908b9ba8df85e57a58e40f96f523f4c2068674f5fe2ba25cdc250a2a41'] );
See below for further examples.
Pushwoosh is a push notification service which provides a JSON API for users of its premium account. This module provides a simple Perl wrapper around that API.
For information on integrating the Pushwoosh service into your mobile apps, see http://www.pushwoosh.com/programming-push-notification/.
To obtain an API token, log in to your Pushwoosh account and visit https://cp.pushwoosh.com/api_access.
Version 0.02
my $pw = WebService::Pushwoosh->new( app_code => '00000-00000', api_token => 'YOUR_APP_TOKEN' );
Creates a WebService::Pushwoosh instance.
Parameters:
Your Pushwoosh application code (required)
Your API token from Pushwoosh (required)
The API url for Pushwoosh (optional).
It is not recommended to change this from the default.
A custom Furl object to use for the requests (optional).
It is not recommended to change this.
Set this to either 'croak' or 'manual'. 'croak' is the default and will generate an error string if an error is detected from in the Pushwoosh response. 'manual' will simply return the API status response when a method errors, if you want more control over the error handling. See the Pushwoosh documentation for the possible error codes.
'croak'
'manual'
my $message_id = $pw->create_message( # Content settings "send_date" => "now", # YYYY-MM-DD HH => mm OR 'now' "content" => { # Object( language1 => 'content1', language2 => 'content2' ) OR string "en" => "English", "de" => "Deutsch" }, "page_id" => 39, # Optional. int "link" => "http://google.com", # Optional. string "data" => { # HashRef. Will be passed as "u" parameter in the payload 'foo' => 1, 'favo_bludd' => 'axlotl_tanks', 'tleilaxu_master' => 'glossu_rabban', }, "platforms" => [1, 2, 3, 4, 5, 6, 7], # 1 - iOS; 2 - BB; 3 - Android; 4 - Nokia; 5 - Windows Phone; 7 - OS X # WP7 related "wp_type" => "Tile", # WP7 notification type. 'Tile' or 'Toast'. Raw notifications are not supported. 'Tile' is default "wp_background" => "/Resources/Red.jpg", # WP7 Tile image "wp_backbackground" => "/Resources/Green.jpg", # WP7 Back tile image "wp_backtitle" => "back title", # WP7 Back tile title "wp_count" => 3, # Optional. Integer. Badge for WP7 # Android related "android_banner" => "http://example.com/banner.png", "android_custom_icon" => "http://example.com/image.png", "android_icon" => "icon.png", "android_root_params" => { "key" => "value" }, # custom key-value object. root level parameters for the android payload "android_sound" => "soundfile", # Optional. Sound file name in the "res/raw" folder, do not include the extension #iOS related "ios_badges" => 5, # Optional. Integer. This value will be sent to ALL devices given in "devices" "ios_sound" => "soundfile", # Optional. Sound file name in the main bundle of application "ios_root_params" => { "content-available" => 1 }, # Optional - root level parameters to the aps dictionary # Mac related "mac_badges" => 3, "mac_sound" => "sound.caf", "mac_root_params" => { "content-available" => 1 }, # Recipients "devices" => [ # Optional. If set, message will only be delivered to the devices in the list. Ignored if the applications group is used "dec301908b9ba8df85e57a58e40f96f523f4c2068674f5fe2ba25cdc250a2a41" ], "filter" => "FILTER_NAME" # Optional "conditions" => [TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN] # Optional );
Sends a push notification using the createMessage API call. Croaks on errors.
createMessage
The message text to be delivered to the application
Use only to pass custom data to the application. Note that iOS push is limited to 256 bytes
HTML page id (created from Application's HTML Pages). Use this if you want to deliver additional HTML content
The time at which the message should be sent (UTC) or 'now' to send immediately (the default)
Sets the badge for the WP7 platform
Sets the badge on the icon for iOS
Limit only to the specified device IDs
Root level parameters to the aps direction, for example to use with NewsStand apps
TAG_CONDITION is an array like: [tagName, operator, operand] where
tagName String
tagName
operator "LTE"|"GTE"|"EQ"|"BETWEEN"|"IN"
operator
operand String|Integer|ArrayRef
operand
Valid operators for String tags:
EQ: tag value equals operand. Operand must be a string
Valid operators for Integer tags:
GTE: tag value greater than or equal to operand. Operand must be an integer.
LTE: tag value less than or equal to operand. Operand must be an integer.
EQ: tag value equals operand. Operand must be an integer.
BETWEEN: tag value greater than or equal to min value, and tag value is less than or equal to max value. Operand must be an array like: [min_value, max_value].
[min_value, max_value]
Valid operators for ArrayRef tags:
IN: Intersect user values and operand. Operand must be an arrayref of strings like: ["value 1", "value 2", "value N"].
You cannot use 'filter' and 'conditions' parameters together.
Returns:
$pw->delete_message(message => '78EA-F351D565-9CCA7EED');
Deletes a scheduled message
The message code obtained from create_message
$pw->register_device( application => 'APPLICATION_CODE', push_token => 'DEVICE_PUSH_TOKEN', language => 'en', # optional hwid => 'hardware id', timezone => 3600, # offset in seconds device_type => 1, );
Registers device for the application
Push token for the device
Language locale of the device (optional)
Unique string to identify the device (Please note that accessing UDID on iOS is deprecated and not allowed, one of the alternative ways now is to use MAC address)
Timezone offset in seconds for the device (optional)
1 - iphone, 2 - blackberry, 3 - android, 4 - nokia, 5 - WP7, 7 - mac
$pw->unregister_device(hwid => 'hardware device id');
Remove device from the application
Hardware device id used in "register_device" function call
$pw->set_tags( hwid => 'device id', tags => { tag1 => 'konstantinos_atreides', tag2 => 42, tag3 => 'spice_mining', tag4 => 3.14 } );
Sets tags for the device
Tags to set against the device
$pw->set_badge( hwid => 'device id', badge => 5 );
Note: Only works on iOS devices
Set current badge value for the device to let auto-incrementing badges work properly.
Current badge on the application to use with auto-incrementing badges
$pw->push_stat( hwid => 'device id', hash => 'hash' );
Register push open event.
Hash tag received in push notification
$pw->get_nearest_zone( hwid => 'device id', lat => 10.12345, lng => 28.12345, );
Records device location for geo push notifications
Latitude of the device
Longitude of the device
Since the Pushwoosh API is only available for users of its premium service, the tests will not run without a valid application code and API token. If you want to run the tests, you must set two environment variables with your credentials, eg:
PUSHWOOSH_APP_CODE=12345-12345 PUSHWOOSH_API_TOKEN=your_api_key perl t/01-simple.t
Mike Cartmell, <mike at mikec.me>
<mike at mikec.me>
Copyright 2013 Mike Cartmell.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://dev.perl.org/licenses/ for more information.
To install WebService::Pushwoosh, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Pushwoosh
CPAN shell
perl -MCPAN -e shell install WebService::Pushwoosh
For more information on module installation, please visit the detailed CPAN module installation guide.