NAME

WebService::Pushwoosh - An interface to the Pushwoosh Remote API v1.3

SYNOPSIS

	# 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.

DESCRIPTION

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

Version 0.02

CONSTRUCTOR

new

my $pw = WebService::Pushwoosh->new(
	app_code  => '00000-00000',
	api_token => 'YOUR_APP_TOKEN'
);

Creates a WebService::Pushwoosh instance.

Parameters:

app_code

Your Pushwoosh application code (required)

api_token

Your API token from Pushwoosh (required)

api_url

The API url for Pushwoosh (optional).

It is not recommended to change this from the default.

furl

A custom Furl object to use for the requests (optional).

It is not recommended to change this.

error_mode

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.

METHODS

create_message

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.

Parameters:

content

The message text to be delivered to the application

data

Use only to pass custom data to the application. Note that iOS push is limited to 256 bytes

page_id

HTML page id (created from Application's HTML Pages). Use this if you want to deliver additional HTML content

send_date

The time at which the message should be sent (UTC) or 'now' to send immediately (the default)

wp_count

Sets the badge for the WP7 platform

ios_badges

Sets the badge on the icon for iOS

devices (ArrayRef)

Limit only to the specified device IDs

ios_root_params

Root level parameters to the aps direction, for example to use with NewsStand apps

conditions

TAG_CONDITION is an array like: [tagName, operator, operand] where

tagName String
operator "LTE"|"GTE"|"EQ"|"BETWEEN"|"IN"
operand String|Integer|ArrayRef

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].

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:

The message ID

delete_message

$pw->delete_message(message => '78EA-F351D565-9CCA7EED');

Deletes a scheduled message

Parameters:

message: The message code obtained from create_message

register_device

$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

Parameters:

push_token: Push token for the device
language: Language locale of the device (optional)
hwid: 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: Timezone offset in seconds for the device (optional)
device_type: 1 - iphone, 2 - blackberry, 3 - android, 4 - nokia, 5 - WP7, 7 - mac

unregister_device

$pw->unregister_device(hwid => 'hardware device id');

Remove device from the application

Parameters:

hwid: Hardware device id used in "register_device" function call

set_tags

$pw->set_tags(
	hwid => 'device id',
	tags => {
		tag1 => 'konstantinos_atreides',
		tag2 => 42,
		tag3 => 'spice_mining',
		tag4 => 3.14
	}
);

Sets tags for the device

Parameters:

hwid: Hardware device id used in "register_device" function call
tags: Tags to set against the device

set_badge

$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.

Parameters:

hwid: Hardware device id used in "register_device" function call
badge: Current badge on the application to use with auto-incrementing badges

push_stat

$pw->push_stat(
	hwid => 'device id',
	hash => 'hash'
);

Parameters:

hwid: Hardware device id used in "register_device" function call
hash: Hash tag received in push notification

get_nearest_zone

$pw->get_nearest_zone(
	hwid => 'device id',
	lat => 10.12345,
	lng => 28.12345,
);

Records device location for geo push notifications

Parameters:

hwid: Hardware device id used in "register_device" function call
lat: Latitude of the device
lng: Longitude of the device

TESTING

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

AUTHOR

Mike Cartmell, <mike at mikec.me>

LICENSE AND COPYRIGHT

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

VERSION

CONSTRUCTOR

new

METHODS

create_message

delete_message

register_device

unregister_device

set_tags

set_badge

push_stat

get_nearest_zone

TESTING

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions