Web Activities v1

[Mounir Lamouri]

Hi,

During the recent B2G work week in San Digeo, Jonas and I seat together
to finalize the Web Activities API using the System Message Handler API.

We believe that the API is in a good-enough shape so unless someone
speaks up, we will implement this as is.

Note that we are still not handling the declarative way to register an
activity handler for non-installed web applications. This is contained
enough to be handled later.

The API should be, for most of it, self-explanatory. However, some
additional details are given after.

interface ActivityOptions {
attribute DOMString name;
attribute Object? data; // a dictionary
};

[Constructor(DOMString name)]
interface ActivityHandlerDescription {
attribute DOMString name; // default has to be passed to ctor
attribute DOMString href; // default is current location
attribute DOMString disposition; // going to be an enum with a default
attribute boolean returnValue;
attribute Object? filters; // a dictionary
};

interface ActivityRequestHandler {
void postResult(any result);
void postError(DOMString error);
readonly attribute ActivityOptions source;
};

[Constructor(ActivityOptions options)]
interface Activity : DOMRequest {
};

partial interface Navigator {
DOMRequest registerActivityHandler(ActivityDescription d);
void unregisterActivityHandler(ActivityDescription d);
bool isActivityHandlerRegistered(ActivityHandler handler);
};

** Handling an activity **

Handling activities will be done trough System Message Handler. An
|ActivityHandlerRequest| will be passed in the Message.

** Launch an activity **

var a = new Activity({ name: "view", data: { type: "image/png", uri: ...
}});
a.onsuccess = function() {};
a.onerror = function() {};

** More information about ActivityOptions **

Activities are defined with a name and some data. Those data can be
stuff like the image to send, the type of the object or anything the
activity will require. Activities with a specific name should have
specific data the handlers will expect to see.
That means the initial specification should specify some basic
activities.

** More information about ActivityHandlerDescription **

Most of it is quite self-explanatory.
- href: can be used to register an activity handler in another page.
- disposition: could be window or inline for the moment.
- returnValue: the UA might want to know if the activity will return a
value. For the basic activities (view, edit, etc.) the UA knows that but
we need that at least for proprietary activities.
- filters: this object should mirror |data| from ActivityOptions but the
values for each fields can be an Array of string, a string or a regexp.
An activity will be considered as able to handle an activity only if the
filters are all satisfied. An array means OR for each items. If there is
no filter value for a field, that means it is always satisfied.

As usual, feedback are more than welcome.

Cheers,
--
Mounir

[Ian Bicking]

Do you mean ActivityHandlerDescription here? Can you give an example of
these?

> bool isActivityHandlerRegistered(ActivityHandler handler);
> };
>
> ** Handling an activity **
>
> Handling activities will be done trough System Message Handler. An
> |ActivityHandlerRequest| will be passed in the Message.
>
> ** Launch an activity **
>
> var a = new Activity({ name: "view", data: { type: "image/png", uri: ...
> }});
> a.onsuccess = function() {};
> a.onerror = function() {};
>
> ** More information about ActivityOptions **
>
> Activities are defined with a name and some data. Those data can be
> stuff like the image to send, the type of the object or anything the
> activity will require. Activities with a specific name should have
> specific data the handlers will expect to see.
> That means the initial specification should specify some basic
> activities.
>
> ** More information about ActivityHandlerDescription **
>
> Most of it is quite self-explanatory.
> - href: can be used to register an activity handler in another page.
> - disposition: could be window or inline for the moment.
> - returnValue: the UA might want to know if the activity will return a
> value. For the basic activities (view, edit, etc.) the UA knows that but
> we need that at least for proprietary activities.
>

I think there might be value in building in the concept of singular and
plural return values. It is possible that a UA could aggregate return
values from multiple sources, for instance, or that you could promote and
demote activities that provide something different than what is provided.
For instance, a camera service might only be setup to provide one image at
a time (i.e., it has no "return this picture and take another" option),
while a service like Flickr could support multiple return values easily.
But for a consumer both are probably okay. Also, types aren't easily
pluralized (i.e., there's no list-of-images mimetype), and this could avoid
a proliferation of plural-vs-singular Activity names.

Also, should the caller declare if they are expecting a return value or
not? If you have this property during registration, that means that some
Activity providers could declare a returnValue and some may not.

An example of a case that might be vague: one can imagine that the "share"
activity might return the URL of the shared item. Or, it might not. The
Activity provider could still, of course, return an invalid or vague URL
(to preserve a sort of sharing anonymity), but it seems like we're making a
stronger distinction here. If an activity has no return value does that
mean that there's no indication when or if it completes?

> - filters: this object should mirror |data| from ActivityOptions but the
> values for each fields can be an Array of string, a string or a regexp.
> An activity will be considered as able to handle an activity only if the
> filters are all satisfied. An array means OR for each items. If there is
> no filter value for a field, that means it is always satisfied.
>

One example I've thought about is unknown data during invocation. For
example, I'd like if we avoided type: "text/uri-list" (which is present in
many Web Intent examples), and instead distinguish between concrete data
and a pointer to data – so if you share something, you'd do {data: {type:
"text/html", uri: "http://some-fun-site.com"}} – with type referring to the
resource on the other side of that URL. But sometimes you don't know the
actual type of a URL, so it might be nice if you could say {data: {type:
"*", uri: "..."}}, and then the filter wouldn't be invoked (i.e., filters
would understand "*"). Though "*" might not be the best way to indicate
unknown. Null?

[Fabrice Desré]

Hi,

On 05/23/2012 08:55 AM, Mounir Lamouri wrote:

> partial interface Navigator {
> DOMRequest registerActivityHandler(ActivityDescription d);
> void unregisterActivityHandler(ActivityDescription d);

> bool isActivityHandlerRegistered(ActivityHandler handler);
> };

registerActivityHandler() needs an extra string parameter that will be
the title of the activity, used by the UA to display an activity picker
when we have several matches. We could also add an icon url.

> - returnValue: the UA might want to know if the activity will return a
> value. For the basic activities (view, edit, etc.) the UA knows that but
> we need that at least for proprietary activities.

The usefulness of this field is not obvious to me. Does it mean that
we'll guarantee that a.onsuccess() will be called if returnValue is
true? How can we force the provider to call postResult() ?

Fabrice
--
Fabrice Desré
b2g Team
Mozilla Corporation

[JOSE MANUEL CANTERA FONSECA]

El 25/05/12 01:41, "Fabrice Desré" <fab...@mozilla.com> escribió:

>Hi,
>
>On 05/23/2012 08:55 AM, Mounir Lamouri wrote:
>
>> partial interface Navigator {
>> DOMRequest registerActivityHandler(ActivityDescription d);
>> void unregisterActivityHandler(ActivityDescription d);
>> bool isActivityHandlerRegistered(ActivityHandler handler);
>> };
>
>registerActivityHandler() needs an extra string parameter that will be
>the title of the activity, used by the UA to display an activity picker
>when we have several matches. We could also add an icon url.

This has l10n issues. In addition adding an icon URL seems to couple the
API layer with the presentation layer.

>
>> - returnValue: the UA might want to know if the activity will return a
>> value. For the basic activities (view, edit, etc.) the UA knows that but
>> we need that at least for proprietary activities.
>
>The usefulness of this field is not obvious to me. Does it mean that
>we'll guarantee that a.onsuccess() will be called if returnValue is
>true? How can we force the provider to call postResult() ?

I agree on this point. I don't understand very well that parameter

>
> Fabrice
>--
>Fabrice Desré
>b2g Team
>Mozilla Corporation

>_______________________________________________
>dev-webapi mailing list
>dev-w...@lists.mozilla.org
>https://lists.mozilla.org/listinfo/dev-webapi
>



Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at
http://www.tid.es/ES/PAGINAS/disclaimer.aspx

[Fabrice Desré]

On 05/25/2012 12:39 AM, JOSE MANUEL CANTERA FONSECA wrote:
> El 25/05/12 01:41, "Fabrice Desré"<fab...@mozilla.com> escribió:

>> registerActivityHandler() needs an extra string parameter that will be
>> the title of the activity, used by the UA to display an activity picker
>> when we have several matches. We could also add an icon url.
>
> This has l10n issues. In addition adding an icon URL seems to couple the
> API layer with the presentation layer.

For sure l10n has to be managed by the caller. Why is this an issue?

What would be a better solution for you?

[Jonas Sicking]

On Thu, May 24, 2012 at 4:41 PM, Fabrice Desré <fab...@mozilla.com> wrote:
> Hi,
>
>
> On 05/23/2012 08:55 AM, Mounir Lamouri wrote:
>
>> partial interface Navigator {
>>   DOMRequest registerActivityHandler(ActivityDescription d);
>>   void       unregisterActivityHandler(ActivityDescription d);
>>   bool       isActivityHandlerRegistered(ActivityHandler handler);
>> };
>
>

> registerActivityHandler() needs an extra string parameter that will be the
> title of the activity, used by the UA to display an activity picker when we
> have several matches. We could also add an icon url.

I think we should just use the application name and application icon,
that makes it much harder to spoof.

/ Jonas

[Mounir Lamouri]

On 05/23/2012 07:33 PM, Ian Bicking wrote:

> On Wed, May 23, 2012 at 10:55 AM, Mounir Lamouri <mou...@lamouri.fr> wrote:
>> partial interface Navigator {
>> DOMRequest registerActivityHandler(ActivityDescription d);
>> void unregisterActivityHandler(ActivityDescription d);
>>
>

> Do you mean ActivityHandlerDescription here?

Yes.

> Can you give an example of these?

navigator.registerActivityHandler({name: "view", filters: { type:
"image/png" });

> I think there might be value in building in the concept of singular and
> plural return values. It is possible that a UA could aggregate return
> values from multiple sources, for instance, or that you could promote and
> demote activities that provide something different than what is provided.
> For instance, a camera service might only be setup to provide one image at
> a time (i.e., it has no "return this picture and take another" option),
> while a service like Flickr could support multiple return values easily.
> But for a consumer both are probably okay. Also, types aren't easily
> pluralized (i.e., there's no list-of-images mimetype), and this could avoid
> a proliferation of plural-vs-singular Activity names.

A camera app taking multiple pictures seems really weird. However, a
'pick' activity that would have multiple returned objects is exactly
what we currently have in HTML with <input type='file' multiple> so we
should definitely take that into account. However, that should be
specified by the 'pick' activity.

> Also, should the caller declare if they are expecting a return value or
> not? If you have this property during registration, that means that some
> Activity providers could declare a returnValue and some may not.
>
> An example of a case that might be vague: one can imagine that the "share"
> activity might return the URL of the shared item. Or, it might not. The
> Activity provider could still, of course, return an invalid or vague URL
> (to preserve a sort of sharing anonymity), but it seems like we're making a
> stronger distinction here. If an activity has no return value does that
> mean that there's no indication when or if it completes?

That is an interesting question! I think I would prefer if caller
doesn't say if it is waiting for a value or not. Maybe the 'share'
activity could be marked as returning a value. If an activity handler
doesn't return a value for it, it could simply return |null| as a return
value.

>> - filters: this object should mirror |data| from ActivityOptions but the
>> values for each fields can be an Array of string, a string or a regexp.
>> An activity will be considered as able to handle an activity only if the
>> filters are all satisfied. An array means OR for each items. If there is
>> no filter value for a field, that means it is always satisfied.
>>
>
> One example I've thought about is unknown data during invocation. For
> example, I'd like if we avoided type: "text/uri-list" (which is present in
> many Web Intent examples), and instead distinguish between concrete data
> and a pointer to data – so if you share something, you'd do {data: {type:
> "text/html", uri: "http://some-fun-site.com"}} – with type referring to the
> resource on the other side of that URL. But sometimes you don't know the
> actual type of a URL, so it might be nice if you could say {data: {type:
> "*", uri: "..."}}, and then the filter wouldn't be invoked (i.e., filters
> would understand "*"). Though "*" might not be the best way to indicate
> unknown. Null?

I'm not sure I understand. If you don't provide a value for a filter
item, it will always be fulfilled. In other words, not providing a value
will mean you do not filter on that item.

Cheers,
--
Mounir

[Mounir Lamouri]

On 05/25/2012 01:41 AM, Fabrice Desré wrote:

> On 05/23/2012 08:55 AM, Mounir Lamouri wrote:
>
>> partial interface Navigator {
>> DOMRequest registerActivityHandler(ActivityDescription d);
>> void unregisterActivityHandler(ActivityDescription d);

>> bool isActivityHandlerRegistered(ActivityHandler handler);
>> };
>
> registerActivityHandler() needs an extra string parameter that will be
> the title of the activity, used by the UA to display an activity picker
> when we have several matches. We could also add an icon url.

As Jonas said, using the application name/icon seems better. If it
happens to be a bad idea, we will be able to add that later.

>> - returnValue: the UA might want to know if the activity will return a
>> value. For the basic activities (view, edit, etc.) the UA knows that but
>> we need that at least for proprietary activities.
>
> The usefulness of this field is not obvious to me. Does it mean that
> we'll guarantee that a.onsuccess() will be called if returnValue is
> true? How can we force the provider to call postResult() ?

If there is no returned value, the success event will be sent as soon as
the user will pick an application to handle the activity.
Otherwise, the success event will be sent with postResult(). However, if
this is never called, the UA will be in charge to send an error event at
some point. For example, when the user leaves the application.

Cheers,
--
Mounir

[Fabrice Desré]

On 05/30/2012 06:49 AM, Mounir Lamouri wrote:
> On 05/25/2012 01:41 AM, Fabrice Desré wrote:
>> On 05/23/2012 08:55 AM, Mounir Lamouri wrote:
>>
>>> partial interface Navigator {
>>> DOMRequest registerActivityHandler(ActivityDescription d);
>>> void unregisterActivityHandler(ActivityDescription d);
>>> bool isActivityHandlerRegistered(ActivityHandler handler);
>>> };
>>
>> registerActivityHandler() needs an extra string parameter that will be
>> the title of the activity, used by the UA to display an activity picker
>> when we have several matches. We could also add an icon url.
>
> As Jonas said, using the application name/icon seems better. If it
> happens to be a bad idea, we will be able to add that later.

Where do we get the application name/icon? Is this the page title and
favicon? If so, how will the user differentiate different activities
registered by the same page?

> If there is no returned value, the success event will be sent as soon as
> the user will pick an application to handle the activity.
> Otherwise, the success event will be sent with postResult(). However, if
> this is never called, the UA will be in charge to send an error event at
> some point. For example, when the user leaves the application.

ok.

[Mounir Lamouri]

On 05/30/2012 07:07 PM, Fabrice Desré wrote:
> On 05/30/2012 06:49 AM, Mounir Lamouri wrote:
>> On 05/25/2012 01:41 AM, Fabrice Desré wrote:
>>> On 05/23/2012 08:55 AM, Mounir Lamouri wrote:
>>>
>>>> partial interface Navigator {
>>>> DOMRequest registerActivityHandler(ActivityDescription d);
>>>> void unregisterActivityHandler(ActivityDescription d);
>>>> bool isActivityHandlerRegistered(ActivityHandler handler);
>>>> };
>>>
>>> registerActivityHandler() needs an extra string parameter that will be
>>> the title of the activity, used by the UA to display an activity picker
>>> when we have several matches. We could also add an icon url.
>>
>> As Jonas said, using the application name/icon seems better. If it
>> happens to be a bad idea, we will be able to add that later.
>
> Where do we get the application name/icon? Is this the page title and
> favicon? If so, how will the user differentiate different activities
> registered by the same page?

It would be using the app manifest for installed apps and the page
title/icon for non-installed apps (that could be saved when
registerActivityHandler is called).
If an application (installed or not) register itself twice for the same
activity, the UA should just show it once.

Cheers,
--
Mounir

[Fabrice Desré]

On 05/30/2012 12:55 PM, Mounir Lamouri wrote:

>>> As Jonas said, using the application name/icon seems better. If it
>>> happens to be a bad idea, we will be able to add that later.
>>
>> Where do we get the application name/icon? Is this the page title and
>> favicon? If so, how will the user differentiate different activities
>> registered by the same page?
>
> It would be using the app manifest for installed apps and the page
> title/icon for non-installed apps (that could be saved when
> registerActivityHandler is called).
> If an application (installed or not) register itself twice for the same
> activity, the UA should just show it once.

But it can register the same page for *different* activities. How does
your proposal handle that?

[Mounir Lamouri]

I don't understand how that is a problem: if a page is registered for
more than one activity, it will be able to handle those and will be
shown as handling them in the UI when the user try to run such activity.

--
Mounir

[glennjones]

Hi
It’s great to see Mozilla moving forward with this idea. I have a few
questions about the API design:

1) I see you have included an isActivityHandlerRegistered function.
This is interesting as Google has decided not to implement this in Web
Intents because of the browser fingerprinting issue. Also of the 3
browsers that have registerProtocolHandler not one has implemented the
similar isProtocolHandlerRegistered.

Don’t get me wrong, I believe being able to see if a type of Activity
is registered will allow web developers to build the best possible UX.
I just wondered have you considered the fingerprinting problem. If so
how have you managed to side-step this issue?

2) The structure of the returning data property looks interesting. It
is hard to tell from the wiki page how this will be implemented. I
take it you are trying to define both a mime-type and the method of
data transfer, i.e.

a.postResult({ type: "image/png", url: ‘http://example.com/
img.png’ });
a.postResult({ type: "image/png", base64:‘AAQwMjIwkAMAAgAAABQAAA…’ });

Could you tell me if the above is what you are considering or have I
got the wrong idea?

3) The multiple property is a good idea. Having built a few Web
Intents services not knowing whether to present the user with a single
or multiple pick UI is not great.

4) The returnValue seems like overkill. It’s mostly implicit in the
choice of verb and the returning data is done through a call back so
the feature is asynchronous and non-blocking by nature.

5) After feedback Google added the extra property which is a key/value
dictionary for passing metadata. This is useful in a case such as an
image being passed back as a URL, but you also need to send metadata
about the photographer and date taken, etc. Did you consider this? If
so, why have you not included something similar?

It’s a bit of a shame Mozilla and Google could not work together on
one standard. The core features of both API’s apart from the
isActivityHandlerRegistered/suggestions map quite well. If Activities
and Intents take off in the future I see most developers using
abstraction libraries rather than the APIs directly.

Cheers
Glenn Jones
glennjones.net