david/therinaldos.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

migrate therinaldos.com data
Build & Deploy to DigitalOcean Space / build (push) Failing after 2m38s
Details

Browse Source
This commit is contained in:
david
2024-05-05 15:50:45 -04:00
commit ef1ff240d4
23182 changed files with 3801898 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wedding-pics/apps/notifications/docs/admin-notifications.md
+73
View File
@@ -0,0 +1,73 @@
# Admin notifications
Allows admins to generate notifications for users via the console or an HTTP endpoint
## Console command
```
$ sudo -u www-data ./occ notification:generate \
admin "Short message up to 255 characters" \
-l "Optional: longer message with more details, up to 4000 characters"
```
### Help
```
$ sudo -u www-data ./occ notification:generate --help
Usage:
notification:generate [options] [--] <user-id> <short-message>
Arguments:
user-id User ID of the user to notify
short-message Short message to be sent to the user (max. 255 characters)
Options:
-l, --long-message=LONG-MESSAGE Long mesage to be sent to the user (max. 4000 characters) [default: ""]
```
## HTTP request
*The URL had to be changed when upgrading from Nextcloud 20 to 21*
```
curl -H "OCS-APIREQUEST: true" -X POST \
https://admin:admin@localhost/ocs/v2.php/apps/notifications/api/v2/admin_notifications/admin \
-d "shortMessage=Short message up to 255 characters" \
-d "longMessage=Optional: longer message with more details, up to 4000 characters"
```
### Help
```
curl -H "OCS-APIREQUEST: true" -X POST \
https://<admin-user>:<admin-app-password-token>@<server-url>/ocs/v2.php/apps/notifications/api/v2/admin_notifications/<user-id> \
-d "shortMessage=<short-message>" \
-d "longMessage=<long-message>"
```
#### Placeholders
| Placeholder | Description |
|------------------------------|------------------------------------------------------------|
| `<admin-user>` | User ID of a user with admin privileges |
| `<admin-app-password-token>` | Password or an "app password" of the "admin-user" |
| `<server-url>` | URL with Webroot of your Nextcloud installation |
| `<user-id>` | User ID of the user to notify |
| `<short-message>` | Short message to be sent to the user (max. 255 characters) |
| `<long-message>` | Long message to be sent to the user (max. 4000 characters) |
### Return codes
| Status | Description |
|--------|------------------------------------------------------------|
| 200 | Notification was created successfully |
| 400 | Too long or empty `short-message`, too long `long-message` |
| 404 | Unknown user |
| 500 | Unexpected server error |
| 503 | Instance is in maintenance mode |
## Screenshot
Both the occ command and the HTTP request generate the same notification
![Admin notification triggered from console](https://raw.githubusercontent.com/nextcloud/notifications/master/docs/screenshot.png)
wedding-pics/apps/notifications/docs/notification-workflow.md
+222
View File
@@ -0,0 +1,222 @@
# Notification Workflow for an App that sends Notifications
## Example story
Let's assume the following example scenario. Our app is the files_sharing app. We want
to notify the user when a remote share has to be accepted/declined. If the user has dealt
with it, we want to remove the notification again.
### Creating a new Notification
1. Grab a new notification object (`\OCP\Notification\INotification`) from the manager
(`\OCP\Notification\IManager`):
```php
$manager = \OC::$server->get(\OCP\Notification\IManager::class);
$notification = $manager->createNotification();
```
2. Set the necessary information for the notification:
```php
$acceptAction = $notification->createAction();
$acceptAction->setLabel('accept')
->setLink('remote_shares', 'POST');
$declineAction = $notification->createAction();
$declineAction->setLabel('decline')
->setLink('remote_shares', 'DELETE');
$notification->setApp('files_sharing')
->setUser('recipient1')
->setDateTime(new \DateTime())
->setObject('remote', '1337') // $type and $id
->setSubject('remote_share', ['name' => '/fancyFolder']) // $subject and $parameters
->addAction($acceptAction)
->addAction($declineAction)
;
```
Setting **app, user, timestamp, object and subject** are mandatory. You should not use a
translated subject, message or action label. Use something like a "language key", to avoid
length problems with translations in the storage of a notification app. Translation is done
via invocation of your notifier by the manager when the notification is prepared for display.
You should also try to avoid setting links and image paths here already, use keys again instead.
This allows you to change the image/url of your application and also the admin can move the instance
to another domain later, without breaking pending notifications. Also make sure, all your URLs are
absolute URLs, so the notification icon and link also work from the desktop and mobile clients.
3. Send the notification back to the manager:
```php
$manager->notify($notification);
```
### Preparing a notification for display
1. In `app.php` register your Notifier (`\OCP\Notification\INotifier`) interface to the manager,
using a `\Closure` returning the Notifier and a `\Closure` returning an array of the id and name:
```php
$manager = \OC::$server->get(\OCP\Notification\IManager::class);
$manager->registerNotifierService(\OCA\Files_Sharing\Notification\Notifier::class);
```
2. The manager will execute the closure and then call the `prepare()` method on your notifier.
If the notification is not known by your app, just throw an `\InvalidArgumentException`,
but if it is actually from your app, you must set the parsed subject, message and action labels:
```php
class Notifier implements \OCP\Notification\INotifier {
protected $factory;
protected $url;
public function __construct(\OCP\L10N\IFactory $factory,
\OCP\IURLGenerator $urlGenerator) {
$this->factory = $factory;
$this->url = $urlGenerator;
}
/**
* Identifier of the notifier, only use [a-z0-9_]
* @return string
*/
public function getID(): string {
return 'files_sharing';
}
/**
* Human-readable name describing the notifier
* @return string
*/
public function getName(): string {
return $this->factory->get('files_sharing')->t('File sharing');
}
/**
* @param INotification $notification
* @param string $languageCode The code of the language that should be used to prepare the notification
*/
public function prepare(INotification $notification, string $languageCode): INotification {
if ($notification->getApp() !== 'files_sharing') {
// Not my app => throw
throw new \InvalidArgumentException();
}
// Read the language from the notification
$l = $this->factory->get('files_sharing', $languageCode);
switch ($notification->getSubject()) {
// Deal with known subjects
case 'remote_share':
try {
$this->shareManager->getShareById($notification->getObjectId(), $notification->getUser());
} catch (ShareNotFound $e) {
// Throw AlreadyProcessedException exception when the notification has already been solved and can be removed.
throw new \OCP\Notification\AlreadyProcessedException();
}
$notification->setIcon($this->url->getAbsoluteURL($this->url->imagePath('core', 'actions/share.svg')))
->setLink($this->url->linkToRouteAbsolute('files_sharing.RemoteShare.overview', ['id' => $notification->getObjectId()]));
// Set rich subject, see https://github.com/nextcloud/server/issues/1706 for more information
// and https://github.com/nextcloud/server/blob/master/lib/public/RichObjectStrings/Definitions.php
// for a list of defined objects and their parameters.
$parameters = $notification->getSubjectParameters();
$notification->setRichSubject($l->t('You received the remote share "{share}"'), [
'share' => [
'type' => 'pending-federated-share',
'id' => $notification->getObjectId(),
'name' => $parameters['name'],
]
]);
// Deal with the actions for a known subject
foreach ($notification->getActions() as $action) {
switch ($action->getLabel()) {
case 'accept':
$action->setParsedLabel($l->t('Accept'))
->setLink($this->url->linkToRouteAbsolute('files_sharing.RemoteShare.accept', ['id' => $notification->getObjectId()]), 'POST');
break;
case 'decline':
$action->setParsedLabel($l->t('Decline'))
->setLink($this->url->linkToRouteAbsolute('files_sharing.RemoteShare.decline', ['id' => $notification->getObjectId()]), 'DELETE');
break;
}
$notification->addParsedAction($action);
}
// Set the plain text subject automatically
$this->setParsedSubjectFromRichSubject($notification);
return $notification;
default:
// Unknown subject => Unknown notification => throw
throw new \InvalidArgumentException();
}
}
/**
* This is a little helper function which automatically sets the simple parsed subject
* based on the rich subject you set. This is also the default behaviour of the API
* since Nextcloud 26, but in case you would like to return simpler or other strings,
* this function allows you to take over.
*
* @param INotification $notification
*/
protected function setParsedSubjectFromRichSubject(INotification $notification): void {
$placeholders = $replacements = [];
foreach ($notification->getRichSubjectParameters() as $placeholder => $parameter) {
$placeholders[] = '{' . $placeholder . '}';
if ($parameter['type'] === 'file') {
$replacements[] = $parameter['path'];
} else {
$replacements[] = $parameter['name'];
}
}
$notification->setParsedSubject(str_replace($placeholders, $replacements, $notification->getRichSubject()));
}
}
```
### Marking a notification as read/deleted/processed/obsoleted
If the user accepted the share or the share was removed/unshared, we want to remove
the notification, because no user action is needed anymore. To do this, we simply have to
call the `markProcessed()` method on the manager with the necessary information on a
notification object:
```php
$manager = \OC::$server->get(\OCP\Notification\IManager::class);
$notification->setApp('files_sharing')
->setObject('remote', 1337)
->setUser('recipient1');
$manager->markProcessed($notification);
```
Only the app name is mandatory: so if you don't set the user, the notification
will be marked as processed for all users that have it. So the following example will
remove all notifications for the app files_sharing on the object "remote #1337":
```php
$manager = \OC::$server->get(\OCP\Notification\IManager::class);
$notification->setApp('files_sharing')
->setObject('remote', 1337);
$manager->markProcessed($notification);
```
### Defer and flush
Sometimes you might send multiple notifications in one request.
In that case it makes sense to defer the sending, so in the end only one connection
is done to the push server instead of 1 per notification.
```php
$manager = \OC::$server->get(\OCP\Notification\IManager::class);
$shouldFlush = $manager->defer();
// Your application code generating notifications …
if ($shouldFlush) {
// Only flush when defer() returned true, otherwise another app is already deferring
$manager->flush();
}
```
wedding-pics/apps/notifications/docs/ocs-endpoint-v1.md
+117
View File
@@ -0,0 +1,117 @@
# Reading and deleting notifications as a Client v1
## Checking the capabilities of the server
In order to find out if notifications is installed/enabled on the server you can run a request against the capabilities endpoint: `/ocs/v2.php/cloud/capabilities`
```json
{
"ocs": {
...
"data": {
...
"capabilities": {
...
"notifications": {
"ocs-endpoints": [
"list",
"get",
"delete"
]
}
}
}
}
}
```
## Getting the notifications of a user
The user needs to be identified/logged in by the server. Then you can just run a simple GET request against `/ocs/v2.php/apps/notifications/api/v1/notifications` to grab a list of notifications:
```json
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 200,
"message": null
},
"data": [
{
"notification_id": 61,
"app": "files_sharing",
"user": "admin",
"datetime": "2004-02-12T15:19:21+00:00",
"object_type": "remote_share",
"object_id": "13",
"subject": "You received admin@localhost as a remote share from test",
"message": "",
"link": "http://localhost/index.php/apps/files_sharing/pending",
"actions": [
{
"label": "Accept",
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
"type": "POST",
"primary": true
},
{
"label": "Decline",
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
"type": "DELETE",
"primary": false
}
]
}
]
}
}
```
**Note:** If the HTTP status code is `204` (No content), you can slow down the polling to once per hour. This status code means that there is no app that can generate notifications.
### Specification
Optional elements are still set in the array, the value is just empty:
Type | Empty value
---- | -----------
string | `""`
array | `[]`
#### Notification Element
Field name | Type | Value description
---------- | ---- | -----------------
notification_id | int | Unique identifier of the notification, can be used to dismiss a notification
app | string | Name of the app that triggered the notification
user | string | User id of the user that receives the notification
datetime | string | ISO 8601 date and time when the notification was published
object_type | string | Type of the object the notification is about, that can be used in php to mark a notification as resolved
object_id | string | ID of the object the notification is about, that can be used in php to mark a notification as resolved
subject | string | Translated short subject that should be presented to the user
message | string | (Optional) Translated potentially longer message that should be presented to the user
link | string | (Optional) A link that should be followed when the subject/message is clicked
actions | array | (Optional) An array of action elements
#### Action Element
Field name | Type | Value description
---------- | ---- | -----------------
label | string | Translated short label of the action/button that should be presented to the user
link | string | A link that should be followed when the action is performed/clicked
type | string | HTTP method that should be used for the request against the link: GET, POST, DELETE
primary | bool | If the action is the primary action for the notification or not
## Get a single notification for a user
In order to get a single notification, you can send a GET request against `/ocs/v2.php/apps/notifications/api/v1/notifications/{id}`
## Deleting a notification for a user
In order to delete a notification, you can send a DELETE request against `/ocs/v2.php/apps/notifications/api/v1/notifications/{id}`
wedding-pics/apps/notifications/docs/ocs-endpoint-v2.md
+179
View File
@@ -0,0 +1,179 @@
# Reading and deleting notifications as a Client v2
## New in APIv2
* :new: Support for icons was added with capability-entry `icons`
* :new: Support for [Rich Object Strings](https://github.com/nextcloud/server/issues/1706) was added with capability-entry `rich-strings`
* :new: ETag/If-None-Match are now evaluated and respond with `304 Not Modified` and empty body when unchanged.
## Checking the capabilities of the server
In order to find out if notifications is installed/enabled on the server you can run a request against the capabilities endpoint: `/ocs/v2.php/cloud/capabilities`
```json
{
"ocs": {
...
"data": {
...
"capabilities": {
...
"notifications": {
"ocs-endpoints": [
"list",
"get",
"delete",
"delete-all",
"icons",
"rich-strings",
"action-web",
"user-status"
]
}
}
}
}
}
```
## Getting the notifications of a user
The user needs to be identified/logged in by the server. Then you can just run a simple GET request against `/ocs/v2.php/apps/notifications/api/v2/notifications` to grab a list of notifications:
```json
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 200,
"message": null
},
"data": [
{
"notification_id": 61,
"app": "files_sharing",
"user": "admin",
"datetime": "2004-02-12T15:19:21+00:00",
"object_type": "remote_share",
"object_id": "13",
"subject": "You received admin@localhost as a remote share from test",
"subjectRich": "You received {share} as a remote share from {user}",
"subjectRichParameters": {
"share": {
"type": "pending-federated-share",
"id": "1",
"name": "test"
},
"user": {
"type": "user",
"id": "test1",
"name": "User One",
"server": "http:\/\/nextcloud11.local"
}
},
"message": "",
"messageRich": "",
"messageRichParameters": [],
"link": "http://localhost/index.php/apps/files_sharing/pending",
"icon": "http://localhost/img/icon.svg",
"shouldNotify": true,
"actions": [
{
"label": "Accept",
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
"type": "POST",
"primary": true
},
{
"label": "Decline",
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
"type": "DELETE",
"primary": false
}
]
}
]
}
}
```
### Response codes
Status | Explanation
---|---
`204 No Content` | please slow down the polling to once per hour, since there are no apps that can generate notifications
`304 Not Modified` | The provided `If-None-Match` matches the ETag, response body is empty
### Headers
Status | Explanation
---|---
`ETag` | See https://tools.ietf.org/html/rfc7232#section-2.3
`X-Nextcloud-User-Status` | Only available with the `user-status` capability. The user status (`away`, `dnd`, `offline`, `online`) should be taken into account and in case of `dnd` no notifications should be directly shown.
### Specification
Optional elements are still set in the array, the value is just empty:
Type | Empty value
---- | -----------
string | `""`
array | `[]`
#### Notification Element
Field name | Type | Since | Value description
---------- | ---- | ----- | -----------------
notification_id | int | v1 | Unique identifier of the notification, can be used to dismiss a notification
app | string | v1 | Name of the app that triggered the notification
user | string | v1 | User id of the user that receives the notification
datetime | string | v1 | ISO 8601 date and time when the notification was published
object_type | string | v1 | Type of the object the notification is about, that can be used in php to mark a notification as resolved
object_id | string | v1 | ID of the object the notification is about, that can be used in php to mark a notification as resolved
subject | string | v1 | Translated short subject that should be presented to the user
subjectRich | string | v2 :new: | (Optional) Translated subject string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
subjectRichParameters | array | v2 :new: | (Optional) Subject parameters for `subjectRich` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
message | string | v1 | (Optional) Translated potentially longer message that should be presented to the user
messageRich | string | v2 :new: | (Optional) Translated message string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
messageRichParameters | array | v2 :new: | (Optional) Message parameters for `messageRich` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
link | string | v1 | (Optional) A link that should be followed when the subject/message is clicked
icon | string | v2 :new: | (Optional) A link to an icon that should be shown next to the notification.
actions | array | v1 | (Optional) An array of action elements
#### Action Element
Field name | Type | Value description
---------- | ---- | -----------------
label | string | Translated short label of the action/button that should be presented to the user
link | string | A link that should be followed when the action is performed/clicked
type | string | HTTP method that should be used for the request against the link: GET, POST, DELETE, PUT or WEB. In case of WEB a redirect should happen instead.
primary | bool | If the action is the primary action for the notification or not
## Get a single notification for a user
In order to get a single notification, you can send a GET request against `/ocs/v2.php/apps/notifications/api/v2/notifications/{id}`
## Deleting a notification for a user
In order to delete a notification, you can send a DELETE request against `/ocs/v2.php/apps/notifications/api/v2/notifications/{id}`
## Deleting all notifications for a user
In order to delete all notifications, you can send a DELETE request against `/ocs/v2.php/apps/notifications/api/v2/notifications`
**Note:** This endpoint was added for Nextcloud 14, so check for the `delete-all` capability first.
## Check existance of notifications for a user
In order to check whether a set of notification ids (max. 200 items per request) still exist for a user,
a client can send a POST request against `/ocs/v2.php/apps/notifications/api/v2/notifications/exists` with
the integer list provided as `ids` field on the POST body.
**Note:** This endpoint was added for Nextcloud 27 and 26.0.1, so check for the `exists` capability first.
wedding-pics/apps/notifications/docs/push-v2.md
+322
View File
@@ -0,0 +1,322 @@
# Push notifications as a Nextcloud client device
## Introduction
> Why is push-notifications.nextcloud.com necessary?
The Nextcloud mobile apps from the Google Playstore and Apple App Store are signed with Nextcloud developer keys or certificates.
Push notifications sent to those devices need to be signed with a generated push key or certificate from the same developer account.
The keys and certificates can not be shipped with the Nextcloud server as otherwise everyone would have our developer key and could manipulate releases or push to any random Nextcloud device.
The Firebase Cloud Messaging (Google) and Apple Push Notification Service are not made for something like a federated project like Nextcloud and still assume there is a single entity behind them like with all the other services.
So we created the push proxy push-notifications.nextcloud.com to protect our users and their data.
We took some extra efforts and reduced the available information to a bare minimum for each of the sections.
* Nextcloud server
- Knowledge:
+ user public and private key (generated by Nextcloud server)
+ device identifier (generated by Nextcloud server)
+ device public key (generated by mobile device)
+ push-token-hash (generated by mobile device)
- Actions
+ Encrypts the content of the push notifications with `device public key`.
+ Signs it with the `user private key`.
+ Sends the notifications with `push-token-hash` to the proxy.
* Push proxy (push-notifications.nextcloud.com)
- Knowledge:
+ user public key (generated by Nextcloud server, send by mobile device)
+ device identifier (generated by Nextcloud server, send by mobile device)
+ push token (generated by mobile device)
+ Google and Apple Developer certificate (generated by Nextcloud)
- Actions:
+ Verifies the signature of the push notification with `user public key` (based on `device identifier`).
+ Signs the notification with Google or Apple Developer certificate.
+ Forwards to Firebase Cloud Messaging (Google) or Apple Push Notification Service.
* Firebase Cloud Messaging (Google) and Apple Push Notification Service
- Knowledge:
+ Google and Apple Developer certificate (generated by Nextcloud)
+ push token (generated by mobile device)
- Actions:
+ Verifies the developer certificate.
+ Forwards the notification to the mobile client.
+ *Note:* Since the notification comes from the Push proxy, Google and Apple don't even know the Nextcloud server sending the notification.
* Mobile device
- Knowledge:
+ device public and private key (generated by mobile device)
+ user public key (generated by mobile device)
- Actions:
+ Verifies the signature with `user public key` to make sure the notification is from a known Nextcloud server and account.
+ Decrypts the notification with `device private key`.
## Checking the capabilities of the Nextcloud server
In order to find out if notifications support push on the server you can run a request against the capabilities endpoint: `/ocs/v2.php/cloud/capabilities`
```
{
"ocs": {
...
"data": {
...
"capabilities": {
...
"notifications": {
"push": [
...
"devices",
"object-data",
"delete"
]
}
}
}
}
}
```
## Subscribing at the Nextcloud server
1. **Only on first registration on the server** The device generates a `rsa2048` key pair (`devicePrivateKey` and `devicePublicKey`).
2. The device generates the `PushToken` for *Apple Push Notification Service* (iOS) or *Firebase Cloud Messaging* (Android)
3. The device generates a `sha512` hash of the `PushToken` (`PushTokenHash`)
4. The device then sends the `devicePublicKey`, `PushTokenHash` and `proxyServerUrl` to the Nextcloud server:
```
POST /ocs/v2.php/apps/notifications/api/v2/push
{
"pushTokenHash": "{{PushTokenHash}}",
"devicePublicKey": "{{devicePublicKey}}",
"proxyServer": "{{proxyServerUrl}}"
}
```
​
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | No further action by the device required |
| 201 | Push token was created/updated and **needs to be sent to the `Proxy`** |
| 400 | Invalid device public key; device does not use a token to authenticate; the push token hash is invalid formatted; the proxy server URL is invalid; |
| 401 | Device is not logged in |
#### Body in case of success
In case of `200` and `201` the reply has more information in the body:
| Key | Type | |
| ---------------- | ------------ | ---------------------------------------- |
| publicKey | string (512) | rsa2048 public key of the user account on the instance |
| deviceIdentifier | string (128) | unique identifier encrypted with the users private key |
| signature | string (512) | base64 encoded signature of the deviceIdentifier |
#### Body in case of an error
In case of `400` the following `message` can appear in the body:
| Error | Description |
| ------------------------ | ---------------------------------------- |
| `INVALID_PUSHTOKEN_HASH` | The hash of the push token was not a valid `sha512` hash. |
| `INVALID_SESSION_TOKEN` | The authentication token of the request could not be identified. Check whether a password was used to login. |
| `INVALID_DEVICE_KEY` | The device key does not match the one registered to the provided session token. |
| `INVALID_PROXY_SERVER` | The proxy server was not a valid https URL. |
## Unsubcribing at the Nextcloud server
When an account is removed from a device, the device should unregister on the server. Otherwise the server sends unnecessary push notifications and might be blocked because of spam.
The device should then send a `DELETE` request to the Nextcloud server:
```
DELETE /ocs/v2.php/apps/notifications/api/v2/push
```
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was not registered on the server |
| 202 | Push token was deleted and **needs to be deleted from the `Proxy`** |
| 400 | Device does not use a token to authenticate |
| 401 | Device is not logged in |
#### Body in case of an error
In case of `400` the following `message` can appear in the body:
| Error | Description |
| ----------------------- | ---------------------------------------- |
| `INVALID_SESSION_TOKEN` | The authentication token of the request could not be identified. |
## Subscribing at the Push Proxy
The device sends the`PushToken` as well as the `deviceIdentifier`, `signature` and the user´s `publicKey` (from the server´s response) to the Push Proxy:
```
POST /devices
{
"pushToken": "{{PushToken}}",
"deviceIdentifier": "{{deviceIdentifier}}",
"deviceIdentifierSignature": "{{signature}}",
"userPublicKey": "{{userPublicKey}}"
}
```
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was written to the database |
| 400 | Push token, public key or device identifier is malformed, the signature does not match |
| 403 | Device is not allowed to write the push token of the device identifier |
| 409 | In case of a conflict the device can retry with the additional field `cloudId` with the value `{{userid}}@{{serverurl}}` which allows the proxy to verify the public key and device identifier belongs to the given user on the instance |
## Unsubscribing at the Push Proxy
The device sends the `deviceIdentifier`, `deviceIdentifierSignature` and the user´s `publicKey` (from the server´s response) to the Push Proxy:
```
DELETE /devices
{
"deviceIdentifier": "{{deviceIdentifier}}",
"deviceIdentifierSignature": "{{signature}}",
"userPublicKey": "{{userPublicKey}}"
}
```
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was deleted from the database |
| 400 | Public key or device identifier is malformed |
| 403 | Device identifier and device public key didn't match or could not be found |
## Pushed notifications
The pushed notifications is defined by the [Firebase Cloud Messaging HTTP Protocol](https://firebase.google.com/docs/cloud-messaging/http-server-ref#send-downstream). The sample content of a Nextcloud push notification looks like the following:
```json
{
"to" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
"notification" : {
"body" : "NEW_NOTIFICATION",
"body_loc_key" : "NEW_NOTIFICATION",
"title" : "NEW_NOTIFICATION",
"title_loc_key" : "NEW_NOTIFICATION"
},
"data" : {
"subject" : "*Encrypted subject*",
"signature" : "*Signature*"
}
}
```
| Attribute | Meaning |
| ----------- | ---------------------------------------- |
| `subject` | The subject is encrypted with the device´s *public key*. |
| `signature` | The signature is a sha512 signature over the encrypted subject using the user´s private key. |
### Encrypted subject data
#### Normal content notification
If you are missing any information necessary to parse the notification in a more usable way, use the `nid` to get the full notification information via [OCS API](ocs-endpoint-v2.md)
```json
{
"app" : "spreed",
"subject" : "Test mentioned you in a private conversation",
"type" : "chat",
"id" : "t0k3n",
"nid" : 1337
}
```
| Attribute | Meaning | Capability |
| ----------- | ---------------------------------------- |------------|
| `app` | The nextcloud app sending the notification | -|
| `subject` | The subject of the actual notification | -|
| `type` | Type of the object this notification is about | `object-data` |
| `id` | Identifier of the object this notification is about | `object-data` |
| `nid` | Numeric identifier of the notification in order to get more information via the [OCS API](ocs-endpoint-v2.md) | `object-data` |
#### Silent delete notification (single)
These notifications should not be shown to the user. Instead you should delete pending system notifications for the respective id
```json
{
"delete" : true,
"nid" : 1337
}
```
| Attribute | Meaning | Capability |
| ----------- | ---------------------------------------- |------------|
| `nid` | Numeric identifier of the notification in order to get more information via the [OCS API](ocs-endpoint-v2.md) | `object-data` |
| `delete` | Delete all notifications related to `nid` | `delete` |
#### Silent delete notification (all)
These notifications should not be shown to the user. Instead you should delete all pending system notifications for this account
```json
{
"delete-all" : true
}
```
| Attribute | Meaning | Capability |
| ----------- | ---------------------------------------- |------------|
| `delete-all` | Delete all notifications related to this account | `delete` |
### Verification
So a device should verify the signature using the user´s public key.
If the signature is okay, the subject can be decrypted using the device´s private key.
wedding-pics/apps/notifications/docs/screenshot.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB