Skip to content

chore: Document accept_from_flagship on app's manifest #4179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nono merged 1 commit into from
Nov 2, 2023
Merged

chore: Document accept_from_flagship on app's manifest #4179

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions docs/accept-from-flagship.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
[Table of contents](README.md#table-of-contents)

# Accept from Flagship

Flagship app is a mobile app that allows users to access all their Cozy from their phone (see [here](https://github.com/cozy/cozy-flagship-app) for more details).

When the Flagship app is installed on the user's phone, then they can share a document with the app to upload it in their Cozy.

When doing so, the user will have to chose which cozy-app should receive the shared document from a list of elligible cozy-apps (i.e. cozy-drive, mespapiers, etc)

To be elligible, a cozy-app has to declare what it can receive. This is done in its `manifest.webapp` file.

## The manifest

The `manifest.webapp` file is used to declare the cozy-app's ability to receive files

### `accept_from_flagship` field

First field to declare is `accept_from_flagship`. It should be set to `true` to make the cozy-app visible in the list of elligible cozy-apps

Example:
```json
{
"name": "Drive",
"name_prefix": "Cozy",
"slug": "drive",
//...
"accept_from_flagship": true,
//...
}
```

### `accept_documents_from_flagship` field

Declaring `accept_from_flagship: true` is not enough to be able to receive files from the Flagship app. The app should also declare which kind of files it can handle.

The field `accept_documents_from_flagship` is an object containing all criteria that a file or a list of files should meet to be sharable with the cozy-app.

#### `accepted_mime_types` criteria

`accepted_mime_types` is used to declare each file type that can be handled by the cozy-app.

This field should contain a list of all mime types that are supported by the cozy-app.

Example of a cozy-app accepting PDF, and pictures:
```json
{
//...
"accept_from_flagship": true,
"accept_documents_from_flagship": {
"accepted_mime_types": ["application/pdf", "image/jpeg", "image/png"],
}
}
```

In order to accept all files types, it is possible to use `'*/*'` mime type

Example of a cozy-app accepting all types of documents:
```json
{
//...
"accept_from_flagship": true,
"accept_documents_from_flagship": {
"accepted_mime_types": ["*/*"],
}
}
```

#### `max_number_of_files` criteria

`max_number_of_files` is used to declare the maximum number of files that can be shared simultaneously with the cozy-app.

Example of a cozy-app accepting only 1 document at a time:
```json
{
//...
"accept_from_flagship": true,
"accept_documents_from_flagship": {
"max_number_of_files": 10,
}
}
```

Example of a cozy-app accepting up to 10 documents at a time:
```json
{
//...
"accept_from_flagship": true,
"accept_documents_from_flagship": {
"max_number_of_files": 10,
}
}
```

Setting a limit is mandatory. The Flagship app doesn't support unlimited file number.

#### `max_size_per_file_in_MB` criteria

`max_size_per_file_in_MB` is used to declare the maximum size of files that can be handled by the cozy-app.

The size limit is declared in MB.

The size limit is per file. If multiple files are shared with the cozy-app, then each file size should be under that limit.

Example of a cozy-app accepting documents up to 10MB:
```json
{
//...
"accept_from_flagship": true,
"accept_documents_from_flagship": {
"max_size_per_file_in_MB": 10,
}
}
```

Setting a limit is mandatory. The Flagship app doesn't support unlimited file size.

#### `route_to_upload` criteria

`route_to_upload` is used to declare the cozy-app's route that should be used by the Flagship app when sharing files with the cozy-app.

The app should then implement a page on that route that will be responsible to handle those documents (i.e. ask the user where to save the document, analyse the document etc)

Example:
```json
{
//...
"accept_from_flagship": true,
"accept_documents_from_flagship": {
"route_to_upload": "/#/upload?fromFlagshipUpload=true",
}
}
```

#### The complete manifest

Here is an example of a `manifest.webapp` file for an app accepting only up to 10 picture files, with a maximum of 10MB:
```json
{
"name": "Drive",
"name_prefix": "Cozy",
"slug": "drive",
//...
"accept_from_flagship": true,
"accept_documents_from_flagship": {
"accepted_mime_types": ["image/jpeg", "image/png"],
"max_number_of_files": 10,
"max_size_per_file_in_MB": 10,
"route_to_upload": "/#/upload?fromFlagshipUpload=true"
}
//...
}
```

Note that `accept_from_flagship` may seems to be redundant if `accept_documents_from_flagship` exists. This field is an optimization to allow cozy-client queries to filter only cozy-apps that accept sharings.

## The API

When a cozy-app is selected by the user to receive a shared file, this cozy-app is opened using the `route_to_upload` route.

Then the cozy-app can use the Flagship OsReceive API to handle shared files.

This API is documented [here](https://github.com/cozy/cozy-flagship-app/tree/master/src/app/domain/osReceive/os-receive-api.md)
50 changes: 26 additions & 24 deletions docs/apps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,30 +21,32 @@ didn't match our expectations. The
is a better fit. We took a lot of inspirations from it, starting with the
filename for this file: `manifest.webapp`.

| Field | Description |
| ----------------- | ---------------------------------------------------------------------------------------- |
| name | the name to display on the home |
| name_prefix | the prefix to display with the name |
| slug | the default slug (it can be changed at install time) |
| editor | the editor's name to display on the cozy-bar of the app |
| icon | an icon for the home |
| screenshots | an array of path to the screenshots of the application |
| category | the category of the application |
| short_description | a short description of the application |
| long_description | a long description of the application |
| source | where the files of the app can be downloaded |
| developer | `name` and `url` for the developer |
| locales | translations of the name and description fields in other locales |
| langs | list of languages tags supported by the application |
| version | the current version number |
| license | [the SPDX license identifier](https://spdx.org/licenses/) |
| platforms | a list of `type`, `url` values for derivate of the application for other devices |
| intents | a list of intents provided by this app (see [here](intents.md) for more details) |
| permissions | a map of permissions needed by the app (see [here](permissions.md) for more details) |
| notifications | a map of notifications needed by the app (see [here](notifications.md) for more details) |
| services | a map of the services associated with the app (see below for more details) |
| routes | a map of routes for the app (see below for more details) |
| mobile | information about app's mobile version (see below for more details) |
| Field | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| name | the name to display on the home |
| name_prefix | the prefix to display with the name |
| slug | the default slug (it can be changed at install time) |
| editor | the editor's name to display on the cozy-bar of the app |
| icon | an icon for the home |
| screenshots | an array of path to the screenshots of the application |
| category | the category of the application |
| short_description | a short description of the application |
| long_description | a long description of the application |
| source | where the files of the app can be downloaded |
| developer | `name` and `url` for the developer |
| locales | translations of the name and description fields in other locales |
| langs | list of languages tags supported by the application |
| version | the current version number |
| license | [the SPDX license identifier](https://spdx.org/licenses/) |
| platforms | a list of `type`, `url` values for derivate of the application for other devices |
| intents | a list of intents provided by this app (see [here](intents.md) for more details) |
| permissions | a map of permissions needed by the app (see [here](permissions.md) for more details) |
| notifications | a map of notifications needed by the app (see [here](notifications.md) for more details) |
| services | a map of the services associated with the app (see below for more details) |
| routes | a map of routes for the app (see below for more details) |
| mobile | information about app's mobile version (see below for more details) |
| accept_from_flagship | boolean stating if the app is compatible with the Flagship app's "OS Receive" feature |
| accept_documents_from_flagship | when `accept_from_flagship` is `true`, defines what can be uploaded to the app (see [here](accept-from-flagship.md) for more details) |

### Routes

Expand Down