Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(291)

Side by Side Diff: docs/interface_share_target.md

Issue 1963823003: Rewrite Share interface docs and split into two APIs. (Closed) Base URL: git@github.com:chromium/ballista.git@master
Patch Set: Rebrand as Web Share (not Ballista). Created 4 years, 6 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« docs/interface_share.md ('K') | « docs/interface_share.md ('k') | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 # Web Share Target Interface
2
3 **Date**: 2016-05-30
4
5 This document is a rough spec (i.e., *not* a formal web standard draft) of the
6 Web Share Target API. This API allows websites to register to receive shared
7 content from either the [Web Share API](interface_share.md), or system events
8 (e.g., shares from native apps).
9
10 This API requires the user agent to support both [service
11 workers](https://www.w3.org/TR/service-workers/) and [web app
12 manifests](https://www.w3.org/TR/appmanifest/). The [Web Share
13 API](interface_share.md) is not required, but recommended.
14
15 Examples of using the Share Target API for sharing can be seen in the
16 [explainer document](explainer.md).
17
18 **Note**: The Web Share Target API is a proposal of the [Ballista
19 project](../README.md), which aims to explore website-to-website and
20 website-to-native interoperability.
21
22 ## App manifest
23
24 The first thing a handler needs to do is declare its share handling capabilities
25 in its [web app manifest](https://www.w3.org/TR/appmanifest/):
26
27 ```WebIDL
28 partial dictionary Manifest {
29 boolean supports_share;
30 };
31 ```
32
33 The `"supports_share"` member of the manifest, if `true`, indicates that the app
34 can receive share events from requesters, or the system. The declarative nature
35 of the manifest allows search services to index and present web applications
36 that handle shares.
37
38 Handlers declaring `supports_share` in their manifest will **not** be
39 automatically registered; the user must explicitly authorize the registration.
40 How this takes place is still under consideration (see [User
41 Flow](user_flow.md#registering-a-website-as-a-handler-on-mobile), but will
42 ultimately be at the discretion of the user agent (the user may be automatically
43 prompted, or may have to explicitly request registration).
44
45 **For consideration**: We may wish to provide a method for websites to
46 explicitly request to prompt the user for handler registration. There would
47 still be a requirement to declare `supports_share` in the manifest. For now, we
48 have omitted such a method from the design to keep control in the hands of user
49 agents. It is easier to add such a method later than remove it.
50
51 ## Event handlers
52
53 Handlers **must** have a registered [service
54 worker](https://www.w3.org/TR/service-workers/).
55
56 When the user picks a registered web app as the target of a share, the
57 handler's service worker starts up (if it is not already running), and a
58 `"share"` event is fired at the global object.
59
60 ```WebIDL
61 partial interface WorkerGlobalScope {
62 attribute EventHandler onshare;
63 };
64
65 interface ShareEvent : ExtendableEvent {
66 readonly attribute ShareData data;
67
68 void reject(DOMException error);
69 };
70
71 dictionary ShareData {
72 DOMString? title;
73 DOMString? text;
74 DOMString? url;
75 };
76 ```
77
78 The `onshare` handler (with corresponding event type `"share"`) takes a
79 `ShareEvent`. The `data` field provides data from the sending application.
80
81 How the handler deals with the data object is at the handler's discretion, and
82 will generally depend on the type of app. Here are some suggestions:
83
84 * An email client might draft a new email, using `title` as the subject of an
85 email, with `text` and `url` concatenated together as the body.
86 * A social networking app might draft a new post, ignoring `title`, using `text`
87 as the body of the message and adding `url` as a link. If `text` is missing,
88 it might use `url` in the body as well. If `url` is missing, it might scan
89 `text` looking for a URL and add that as a link.
90 * A text messaging app might draft a new message, ignoring `title` and using
91 `text` and `url` concatenated together. It might truncate the text or replace
92 `url` with a short link to fit into the message size.
93
94 A share fails if:
95
96 * The handler had no registered service worker.
97 * There was an error during service worker initialization.
98 * There is no event handler for `share` events.
99 * The event handler explicitly calls the event's `reject` method (either in the
100 event handler, or in the promise passed to the event's
101 [`waitUntil`](https://www.w3.org/TR/service-workers/#wait-until-method)
102 method).
103 * The promise passed to `waitUntil` is rejected.
104
105 Once the event completes without failing, the share automatically succeeds, and
106 the requester's promise is resolved. The end of the event's lifetime marks the
107 end of the share, and there is no further communication in either direction.
108
109 The Share Target API is defined entirely within the service worker. If the
110 handler needs to provide UI (which should be the common case), the service
111 worker must create a foreground page and send the appropriate data between the
112 worker and foreground page, out of band. The `share` event handler is [allowed
113 to show a
114 popup](https://html.spec.whatwg.org/multipage/browsers.html#allowed-to-show-a-po pup),
115 which means it can call the
116 [`clients.openWindow`](https://www.w3.org/TR/service-workers/#clients-openwindow -method)
117 method.
118
119 ## Where do shares come from?
120
121 Share events can be sent from a variety of places:
122
123 * Built-in trigger (e.g., user picks "Share" from a browser's menu, to share the
124 URL in the address bar).
125 * A native application.
126 * A web application using the [Web Share API](interface_share.md).
127
128 There will usually be a picker that lets the user select a target app. This
129 could be the native system app picker, or a user-agent-supplied picker. The apps
130 could include other system apps and actions alongside the web app handlers.
131
132 If an event comes from a web app, the `data` field of the event should be a
133 clone of the `data` parameter to `navigator.share`. If the event comes from some
134 other source, the user agent may construct the `data` object as appropriate.
OLDNEW
« docs/interface_share.md ('K') | « docs/interface_share.md ('k') | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698