``POST /device/(device_id)/keepalive/event``
============================================

Synopsis
--------

Send a keep-alive (KA) message to check that the link between the mobile device and the cloud service is operating, and to inform the cloud service that the client application is running properly.


Request Header Fields
---------------------

.. include:: /_include/optional_authenticated_session_header_fields.inc


Request URL Bits
----------------

* ``device_id: string``: The identification of the mobile device.


Request Query Parameters
------------------------

None.


Request Message Body
--------------------

The HTTP request must contains the following JSON structure::

    {
      "battery_level": decimal,
      "ex_bytes": string,
      "is_battery_plugged": boolean,
      "location": {
        "accuracy": decimal,
        "altitude": decimal,
        "bearing": decimal,
        "fix_time": timestamp,
        "latitude": decimal,
        "longitude": decimal,
        "provider": string,
        "speed": decimal
      },
      "network_type": string,
      "token": string
    }

where:

* ``battery_level`` (optional): The current level in percentage of the device's battery.

* ``ex_bytes`` (optional): A string representation of a tuple of the form ``received:transmitted`` where:

  * ``received``: The number of bytes received across mobile networks since the device boot.

  * ``transmitted``: The number of bytes transmitted across mobile networks since the device boot.

* ``is_battery_plugged`` (optional): Indicate if the battery of the device is plugged in a power source.

* ``location`` (optional): The last known location of the device:

  * ``accuracy`` (required): The accuracy in meters of the location.

  * ``altitude`` (required): The altitude in meters of the location.

  * ``bearing`` (optional): The bearing in degrees.  Bearing is the horizontal direction of travel of the device, and is not related to the device orientation.  It is guaranteed to be in the range ``[0.0, 360.0]``.

  * ``fix_time`` (required): The time when the device determined the information of this fix.

  * ``latitude`` (required): The latitude-angular distance, expressed in decimal degrees (WGS84 datum), measured from the center of the Earth, of a point north or south of the Equator corresponding to the location.

  * ``longitude`` (required): The longitude-angular distance, expressed in decimal degrees (WGS84 datum), measured from the center of the Earth, of a point east or west of the Prime Meridian corresponding to the location.

  * ``provider`` (required): The code name of the location provider that reported the location.

   * ``fused``: The location API in Google Play services that combines different signals to provide the location information.

   * ``gps``: This provider determines location using satellites.

   * ``network``: This provide determines the location using an hybrid positioning system, which uses different positioning technologies, such as Global Positioning System (GPS), Wi-Fi hotspots, cell tower signals.

   * ``passive``: A special location provider for receiving locations without actually initiating a location fix.  This provider can be used to passively receive location updates when other applications or services request them without actually requesting the locations yourself.  This provider will return locations generated by other providers.

  * ``speed`` (optional): The speed in meters/second over the ground.

* ``network_type`` (required): A string representation of a tuple of the form ``operator:type[:subtype]`` where:

  * ``operator: string`` (required): The identifier of the mobile phone operator, composed of the Mobile Country Code (MCC) and the Mobile Network Code (MNC) of this carrier.

  * ``type: string`` (required): A human-readable name that describes the type of the network that the device is connected to, such as ``wifi``, ``mobile``, ``unknown``.

  * ``subtype: string`` (optional): A human-readable name that describes the subtype of this network when applicable, such as the radio technology currently in use on the device for data transmission.  Network of type ``wifi`` has no subtype.  Network of type ``mobile`` can have a subtype such as ``egde``, ``gprs``, ``hsdpa``, ``hspa``, ``hspa+``, ``umts``, etc.

* ``token`` (required): A "number used once" (nonce) -- also known as pseudo-random number -- encrypted with the security key generated by the cloud service and shared with the client application.  This nonce is used to verify the authentication of the mobile device in order to prevent spoofing attack.


Response Message Body
---------------------

None.


Exceptions
----------

The platform MAY raise the following exceptions to indicate that one or several required conditions have not been respected:

* ``DeletedObjectException``: If the device has been banned by an administrator of the cloud service.

* ``DisabledObjectException``: If the device has been disabled by the individual user or the organization that owns the device.

* ``IllegalAccessException``: If the given token has not been successfully verified, meaning that someone or a program tries to masquerade as the specified device (spoofing attack).

* ``InvalidOperationException``: If the device has not been activated.

* ``UndefinedObjectException``: If the specified identification doesn't match a mobile device registered to the cloud service.
