Skip to content

Commit 0d175fb

Browse files
nononono
authored
chore: Document accept_from_flagship on app's manifest (#4179)
This PR documents the new manifest entries that should be used to make a cozy-app elligible for receiving files from the Flagship app as implemented in linagora/cozy-flagship-app#906 The OsReceive API is documented in linagora/cozy-flagship-app#987
2 parents 855ac47 + 82cbe33 commit 0d175fb

File tree

2 files changed

+189
-24
lines changed

2 files changed

+189
-24
lines changed

‎docs/accept-from-flagship.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
[Table of contents](README.md#table-of-contents)
2+
3+
# Accept from Flagship
4+
5+
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).
6+
7+
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.
8+
9+
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)
10+
11+
To be elligible, a cozy-app has to declare what it can receive. This is done in its `manifest.webapp` file.
12+
13+
## The manifest
14+
15+
The `manifest.webapp` file is used to declare the cozy-app's ability to receive files
16+
17+
### `accept_from_flagship` field
18+
19+
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
20+
21+
Example:
22+
```json
23+
{
24+
"name": "Drive",
25+
"name_prefix": "Cozy",
26+
"slug": "drive",
27+
//...
28+
"accept_from_flagship": true,
29+
//...
30+
}
31+
```
32+
33+
### `accept_documents_from_flagship` field
34+
35+
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.
36+
37+
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.
38+
39+
#### `accepted_mime_types` criteria
40+
41+
`accepted_mime_types` is used to declare each file type that can be handled by the cozy-app.
42+
43+
This field should contain a list of all mime types that are supported by the cozy-app.
44+
45+
Example of a cozy-app accepting PDF, and pictures:
46+
```json
47+
{
48+
//...
49+
"accept_from_flagship": true,
50+
"accept_documents_from_flagship": {
51+
"accepted_mime_types": ["application/pdf", "image/jpeg", "image/png"],
52+
}
53+
}
54+
```
55+
56+
In order to accept all files types, it is possible to use `'*/*'` mime type
57+
58+
Example of a cozy-app accepting all types of documents:
59+
```json
60+
{
61+
//...
62+
"accept_from_flagship": true,
63+
"accept_documents_from_flagship": {
64+
"accepted_mime_types": ["*/*"],
65+
}
66+
}
67+
```
68+
69+
#### `max_number_of_files` criteria
70+
71+
`max_number_of_files` is used to declare the maximum number of files that can be shared simultaneously with the cozy-app.
72+
73+
Example of a cozy-app accepting only 1 document at a time:
74+
```json
75+
{
76+
//...
77+
"accept_from_flagship": true,
78+
"accept_documents_from_flagship": {
79+
"max_number_of_files": 10,
80+
}
81+
}
82+
```
83+
84+
Example of a cozy-app accepting up to 10 documents at a time:
85+
```json
86+
{
87+
//...
88+
"accept_from_flagship": true,
89+
"accept_documents_from_flagship": {
90+
"max_number_of_files": 10,
91+
}
92+
}
93+
```
94+
95+
Setting a limit is mandatory. The Flagship app doesn't support unlimited file number.
96+
97+
#### `max_size_per_file_in_MB` criteria
98+
99+
`max_size_per_file_in_MB` is used to declare the maximum size of files that can be handled by the cozy-app.
100+
101+
The size limit is declared in MB.
102+
103+
The size limit is per file. If multiple files are shared with the cozy-app, then each file size should be under that limit.
104+
105+
Example of a cozy-app accepting documents up to 10MB:
106+
```json
107+
{
108+
//...
109+
"accept_from_flagship": true,
110+
"accept_documents_from_flagship": {
111+
"max_size_per_file_in_MB": 10,
112+
}
113+
}
114+
```
115+
116+
Setting a limit is mandatory. The Flagship app doesn't support unlimited file size.
117+
118+
#### `route_to_upload` criteria
119+
120+
`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.
121+
122+
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)
123+
124+
Example:
125+
```json
126+
{
127+
//...
128+
"accept_from_flagship": true,
129+
"accept_documents_from_flagship": {
130+
"route_to_upload": "/#/upload?fromFlagshipUpload=true",
131+
}
132+
}
133+
```
134+
135+
#### The complete manifest
136+
137+
Here is an example of a `manifest.webapp` file for an app accepting only up to 10 picture files, with a maximum of 10MB:
138+
```json
139+
{
140+
"name": "Drive",
141+
"name_prefix": "Cozy",
142+
"slug": "drive",
143+
//...
144+
"accept_from_flagship": true,
145+
"accept_documents_from_flagship": {
146+
"accepted_mime_types": ["image/jpeg", "image/png"],
147+
"max_number_of_files": 10,
148+
"max_size_per_file_in_MB": 10,
149+
"route_to_upload": "/#/upload?fromFlagshipUpload=true"
150+
}
151+
//...
152+
}
153+
```
154+
155+
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.
156+
157+
## The API
158+
159+
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.
160+
161+
Then the cozy-app can use the Flagship OsReceive API to handle shared files.
162+
163+
This API is documented [here](https://github.com/cozy/cozy-flagship-app/tree/master/src/app/domain/osReceive/os-receive-api.md)

‎docs/apps.md‎

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -21,30 +21,32 @@ didn't match our expectations. The
2121
is a better fit. We took a lot of inspirations from it, starting with the
2222
filename for this file: `manifest.webapp`.
2323

24-
| Field | Description |
25-
| ----------------- | ---------------------------------------------------------------------------------------- |
26-
| name | the name to display on the home |
27-
| name_prefix | the prefix to display with the name |
28-
| slug | the default slug (it can be changed at install time) |
29-
| editor | the editor's name to display on the cozy-bar of the app |
30-
| icon | an icon for the home |
31-
| screenshots | an array of path to the screenshots of the application |
32-
| category | the category of the application |
33-
| short_description | a short description of the application |
34-
| long_description | a long description of the application |
35-
| source | where the files of the app can be downloaded |
36-
| developer | `name` and `url` for the developer |
37-
| locales | translations of the name and description fields in other locales |
38-
| langs | list of languages tags supported by the application |
39-
| version | the current version number |
40-
| license | [the SPDX license identifier](https://spdx.org/licenses/) |
41-
| platforms | a list of `type`, `url` values for derivate of the application for other devices |
42-
| intents | a list of intents provided by this app (see [here](intents.md) for more details) |
43-
| permissions | a map of permissions needed by the app (see [here](permissions.md) for more details) |
44-
| notifications | a map of notifications needed by the app (see [here](notifications.md) for more details) |
45-
| services | a map of the services associated with the app (see below for more details) |
46-
| routes | a map of routes for the app (see below for more details) |
47-
| mobile | information about app's mobile version (see below for more details) |
24+
| Field | Description |
25+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
26+
| name | the name to display on the home |
27+
| name_prefix | the prefix to display with the name |
28+
| slug | the default slug (it can be changed at install time) |
29+
| editor | the editor's name to display on the cozy-bar of the app |
30+
| icon | an icon for the home |
31+
| screenshots | an array of path to the screenshots of the application |
32+
| category | the category of the application |
33+
| short_description | a short description of the application |
34+
| long_description | a long description of the application |
35+
| source | where the files of the app can be downloaded |
36+
| developer | `name` and `url` for the developer |
37+
| locales | translations of the name and description fields in other locales |
38+
| langs | list of languages tags supported by the application |
39+
| version | the current version number |
40+
| license | [the SPDX license identifier](https://spdx.org/licenses/) |
41+
| platforms | a list of `type`, `url` values for derivate of the application for other devices |
42+
| intents | a list of intents provided by this app (see [here](intents.md) for more details) |
43+
| permissions | a map of permissions needed by the app (see [here](permissions.md) for more details) |
44+
| notifications | a map of notifications needed by the app (see [here](notifications.md) for more details) |
45+
| services | a map of the services associated with the app (see below for more details) |
46+
| routes | a map of routes for the app (see below for more details) |
47+
| mobile | information about app's mobile version (see below for more details) |
48+
| accept_from_flagship | boolean stating if the app is compatible with the Flagship app's "OS Receive" feature |
49+
| 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) |
4850

4951
### Routes
5052

0 commit comments

Comments
 (0)