Mike Cartmell > WebService-Pushwoosh-0.01 > WebService::Pushwoosh

Download:
WebService-Pushwoosh-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source   Latest Release: WebService-Pushwoosh-0.02

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

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",
                        "ru" => "Русский",
                        "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_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 },
                "android_root_params" => { "key" => "value" }, # custom key-value object. root level parameters for the android payload

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

Register push open event.

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 ^

Copyright 2013 Mike Cartmell.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

syntax highlighting: