Items Pushsafer

Pushsafer

See original

SYNOPSIS

This module allows MisterHouse to send notification messages to Pushsafer.com clients. See https://www.pushsafer.com/ for details of the service and API.

CONFIGURATION

INI PARAMETERS

Configure the required pushsafer settings in your mh.ini file:

  Pushsafer_k           = <Private or Alias key from Pushsafer.com account> 
  Pushsafer_t           = "MisterHouse" Default title for messages if none provided 
  Pushsafer_d           = <Default device or device group id to send notifications to>
  Pushsafer_i           = <Default icon>
  Pushsafer_s           = <Default sound>
  Pushsafer_v           = <Default vibration>
  Pushsafer_disable = 1  Disable notifications.  Messages will still be logged

Items.mht

Create a pushsafer instance in the .mht file, or in user code:

  CODE, require Pushsafer; #noloop 
  CODE, my $push = new Pushsafer(); #noloop

A user code file overriding parameters normally specified in mh.private.ini. All of the parameters are optional if properly configured in the ini file.

    use Pushsafer;
    my $push = new Pushsafer({
                                        k => '1234qwer1234qewr1234qwer',
                                        t => 'Home Notification',
                                        d => '111',
                                        i => '11',
                                        s => '5',
                                        v => '1',
                      });

In user code send a message. The only required parameter is the first, the message text. Any of the parameters provided when initializing the Pushsafer instance may also be provided on the message send. They will be merged with and override the default values provided on initialization. See the method documentation for below more details.

  $push->notify( "Some important message", { t => 'Security Alert', i => 11 });

DESCRIPTION

The Pushsafer instance establishes the defaults for messages and acts as a rudimentary rate limiter for notifications.

The rate limiting kicks in if an identical message is sent within a 10 second threshold. (Identical meaning the same message, title and device.) Identical messages will be logged but not sent to the pushsafer service. This will minimize excessive use of message credits if a configuration error causes looping notifications.

It's important to exclude the Pushsafer initialization from the loop, so that rate limiting thresholds can be detected and pending acknowledgments are not lost.

INHERITS

DEPENDENCIES

Data::Dumper: Used for error reporting and debugging
LWP::UserAgent: Implements HTTPS for interaction with Pushsafer.net
Digest::MD5: Calculates hash for rate limiting duplicate messages
JSON: Decodes responses from Pushsafer.net

METHODS

new(p_self, p_parameter_hash)

Creates a new Pushsafer object. The parameter hash is optional. Defaults will be taken from the mh.private.ini file or are hardcoded.

This must be excluded from the primary misterhouse loop, or the acknowledgment checking and duplicate message rate limiting will be lost

  my $push = Pushsafer->new( {
                        k       => "xxxx...",           # Set the Private or Alias Key
                        t       => "Some title",        # Set default title for messages
                        d       => "111",                       # Set the target device or device group (leaving this unset goes to all devices)
                        i       => "5",                         # Set the icon to be displayed
                        s       => "3",                         # Set the sound to be played
                        v       => "1",                         # Set the vibration to be played
                        speak   => 1,                           # Enable or disable speak of notifications and acknowledgment
        });

Any of these parameters may be specified in mh.ini by prefixing them with "Pushsafer_"

notify(p_self, p_message, p_paramater_hash)

This is the primary method of the Pushsafer object. The message text is the only mandatory parameter.

The optional parameter hash can be used to override defaults, or specify additional information for the notification. The list is not exclusive. Additional parameters will be passed in the POST to Pushsafer.com. This allows support of any API parameter as defined at https://pushsafer.net/api

        $push->notify("Some urgent message", {
                        k   => "xxxx...",      # Override the Private or Alias Key
            t   => "Some title",   # Override title of message
            d   => "1111"                       # Device or device-group id 
        });

Notify will record the last message sent along with a timestamp. If the duplicate message is sent within a 10 second window, the message will be logged and dropped. A duplicate message is one with identical message text, title and device. Although this permits a message to be sent to multiple users using repeated notify commands, it is preferable to define a group ID on the Pushsafer.com site to minimize traffic.

AUTHOR

George Clark

MODIFICATIONS 2016/09/30 Kevin Siml Pushsafer.com

SEE ALSO

http://www.pushsafer.com