src/main/resources/Documentation/api.md

Firebase Cloud Notifications Plugin
===================================

App implementations should register the device token identifier received from FCM, using the *Register Cloud Notification* method to send the device token identifier and configure how it wants to be notified. When registering the device, it also should provide a token, which is returned on every notification, that allows to identify
the Gerrit instance how send the notification. In addition, an app can configure which events wants to listen to and how the message from FCM is received (as notification, as custom data or received both). Read the FCM documentation to know which is more appropriated for your device operation system. See *Custom Data* in the FCM Notification section to see the information returned as custom data.

A client application can unregistered a device (and stop receiving notifications) from the Gerrit instance using the *Unregister Cloud Notification* method.

Client applications must use a combination of fcm device identifier + a unique local account token, so they can register to listen notification for different accounts on this Gerrit instance. Token must


REST API
--------

This plugin adds new methods to the /accounts Gerrit REST Api entry point to allow a device to register/unregister to receive event notification in this Gerrit instance.

***

**Get Cloud Notifications Config**

`'GET /config/server/cloud-notifications'`

Retrieve the cloud notifications server configuration of the Gerrit server instance.

*Request*
This method returns a *CloudNotificationsConfigInfo* entity (see below).

    GET /config/server/cloud-notifications

*Response*

    HTTP1.1 200 OK
    Content-Disposition: attachment
    Content-Type: application/json; charset=UTF-8

    )]}'
    {
        "senderId": "322112333"
    }

***

**Get Cloud Notifications**

`'GET /accounts/{account-id}/devices/{device-id}/tokens'`

Retrieve a list of registered tokens by a device hold by the Gerrit server instance.

*Request*
This request requires an authenticated call and only returns information if account-id is the authenticated account. This method returns a list of *CloudNotificationInfo* entities (see below).

    GET /accounts/self/devices/bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1/tokens

*Response*

    HTTP1.1 200 OK
    Content-Disposition: attachment
    Content-Type: application/json; charset=UTF-8

    )]}'
    [
     {
       "device": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1",
       "token": "f986567456f107d0eb2d84c85ac5aed2",
       "registeredOn": "2016-11-25 14:45:03.123",
       "events": 1023,
       "responseMode": "DATA"
     }
    ]

***

**Get Cloud Notification**

`'GET /accounts/{account-id}/devices/{device-id}/tokens/{token}'`

Retrieve a registered device information hold by the Gerrit server instance.

*Request*
This request requires an authenticated call and only returns information if account-id is the authenticated account. This method returns a *CloudNotificationInfo* entity (see below).

    GET /accounts/self/devices/bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1/tokens/f986567456f107d0eb2d84c85ac5aed2

*Response*

    HTTP1.1 200 OK
    Content-Disposition: attachment
    Content-Type: application/json; charset=UTF-8

    )]}'
    {
      "device": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1",
      "token": "f986567456f107d0eb2d84c85ac5aed2",
      "registeredOn": "2016-11-25 14:45:03.123",
      "events": 1023,
      "responseMode": "DATA"
    }

***

**Register Cloud Notification**

`'POST /accounts/{account-id}/devices/{device-id}/tokens'`

Register or update a registered device information to be hold by the Gerrit server instance.

*Request*
This request requires an authenticated call and is only valid if account-id is the authenticated account. This method accepts a *CloudNotificationInput* entity (see below).

    POST /accounts/self/devices/bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1/tokens
    Content-Type: application/json

    {
      "token": "f986567456f107d0eb2d84c85ac5aed2",
      "events": 8,
      "responseMode": "NOTIFICATION"
    }

As a response, this method returns the registered *CloudNotificationInfo* entity (see below).

*Response*

    HTTP1.1 200 OK
    Content-Disposition: attachment
    Content-Type: application/json; charset=UTF-8

    )]}'
    {
      "deviceId": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1",
      "token": "f986567456f107d0eb2d84c85ac5aed2",
      "registeredOn": "2016-11-25 14:45:03.123",
      "events": 8,
      "responseMode": "NOTIFICATION"
    }

***

**Unregister Cloud Notification**

`'DELETE /accounts/{account-id}/devices/{device-id}/tokens/{token}'`

Unregister a registered device information hold by the Gerrit server instance.

*Request*
This request requires an authenticated call and is only valid if account-id is the authenticated account.

    DELETE /accounts/self/devices/bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1/tokens/f986567456f107d0eb2d84c85ac5aed2

*Response*

    HTTP/1.1 204 No Content

***

**CloudNotificationsConfigInfo**

Entity with information about the cloud notifications server configuration.

`senderId: The Firebase Cloud Messaging server identifier.`

***

**CloudNotificationInfo**

Entity with information about a registered device.

`device: A Firebase Cloud Messaging registered device identification.`

`token: A device token that unique identifies the server/account in the device.`

`registeredOn: When the device was registered.`

`events : A bitwise flag to indicate which events to notify. See CloudNotificationEvents below.`

`responseMode: Firebase response mode. See CloudNotificationResponseMode below.`

***

**CloudNotificationInput**

Entity with information about a device to be register.

`token: A device token that unique identifies the server/account in the device.`

`events : A bitwise flag to indicate which events to notify. See CloudNotificationEvents below.`

`responseMode: Firebase response mode. See CloudNotificationResponseMode below.`

***

**CloudNotificationEvents**

Enumeration of available events to notify to the client device.

`CHANGE_ABANDONED_EVENT = 0x01`

`CHANGE_MERGED_EVENT = 0x02`

`CHANGE_RESTORED_EVENT = 0x04`

`COMMENT_ADDED_EVENT = 0x08`

`DRAFT_PUBLISHED_EVENT = 0x10  (deprecated in 2.15)`

`HASHTAG_CHANGED_EVENT = 0x20`

`REVIEWER_ADDED_EVENT = 0x40`

`REVIEWER_DELETED_EVENT = 0x80`

`PATCHSET_CREATED_EVENT = 0x100`

`TOPIC_CHANGED_EVENT = 0x200`

`VOTE_DELETED_EVENT = 0x1000`

`PRIVATE_STATE_CHANGED_EVENT = 0x2000`

`WIP_STATE_CHANGED_EVENT = 0x4000`

***

**CloudNotificationResponseMode**

Enumeration of available Firebase notification modes.

`NOTIFICATION: Notification in the device is handled by Firebase`

`DATA: Notification in the device is handled by the app which receives a custom object data`

`BOTH: Notification includes both: notification data and custom object data`



FCM NOTIFICATION
----------------

**Custom Data**

This is the information sent as a custom data inside the FCM notification. Depends on the event, some of this fields could be empty.

`when: An unix timestamp on when notification was created`

`who: A json AccountInfo object of the account that originated the notification`

`token: The token used to registered the device`

`event: The event type (see CloudNotificationEvents above)`

`change: The change identifier`

`legacyChangeId: The legacy change identifier`

`revision: The revision/patchset identifier`

`project: The project identifier`

`branch: The branch identifier`

`topic: The topic identifier`

`subject: The subject of the change`

`extra: Extra notification information, if present. The structure depends on event type.`