.. _push_notification_reporter_webservice:

Push Notification Reporter
==========================

.. contents::
   :local:
   :depth: 3

Overview
--------

This web service may be used to collect reports about received push notifications. When configured, the web service is
called each time a push notification is received and it reports the push notification to the server.

It can be used to create some automated test which sends push notification to a device and wait for the device to
report that the push has been successfully received or to collect statistics about push delivery success rate.

Push notifications are sent via Acrobits Push Notification Mediator (pnmediator) server. For instructions on how to
send pushes, see :ref:`http-push`.

Parameters
----------

Parameter templates for Push Notification Reporter can use any variables from :ref:`global-params` and :ref:`account-params`
scopes. Other parameters are taken from the received push notification, which is a key-value dictionary. The keys may
be used as placeholders which will be replaced by the appropriate values.

Unfortunately, the structure of the push notifications do not follow any well-defined, strict format for historical
reasons. The following keys may be useful for detecting the type of push notification.

``pushId``
~~~~~~~~~~

    if not empty, the received push was sent as a response to PUSH-TEST.

``s``
~~~~~

    if not empty, the received push is a notification about incoming call. ``c`` contains the callee.


``sm``
~~~~~~

    if not empty, the received push is a notifition about incoming text message

``s_missed``
~~~~~~~~~~~~

    indicates missed call notification

``type``
~~~~~~~~

    if not empty, it specifies other push types


Configuration
-------------

The following :ref:`account-xml` keys are relevant for Push Notification Reporter configuration:

``pushNotificationReporterUrl``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Contains the URL, including URL scheme, of the web service, possibly also with query string.

    Example (with query-string):

    .. code-block:: none

        https://example.com/pushReceived/?username=%account[username]%&pushTestId=%pushId%


``pushNotificationReporterPostData``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    If filled in, the app will use POST request to report the token

    Example ( for  application/x-www-form-urlencoded):

    .. code-block:: none

        username=%account[username]%&pushTestId=%pushId%

    Example ( for  application/json ):

    .. code-block:: json

        { "username" : "%account[username]%", "pushTestId" : "%pushId%" }

``pushNotificationReporterContentType``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default to
    ``application/x-www-form-urlencoded``

Response
--------

    The response will be considered successful if the HTTP response code is 2xx. Any responses which have other
    response code are silently ignored and the app will not retry the request.

    There are no response values expected, so the body of the response is not parsed or processed in any way.

Examples
--------

GET method
~~~~~~~~~~

request:

 .. code-block:: http

    GET /pushReceived/?username=johndow&pushTestId=aELTLURy HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6


response:

 .. code-block:: http

    HTTP/1.1 200 OK
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Encoding: gzip
    Content-Length: 0
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive

POST method, JSON
~~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    POST /pushReceived/johndow/ HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6
    Content-Type: application/json
    Content-Length: 183

    {
        "pushTestId"    : "aELTLURy"
    }

response:

 .. code-block:: http

    HTTP/1.1 200 OK
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Encoding: gzip
    Content-Length: 0
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive