next parameters for requestShareApp

[Lou]

In order to better track information about invites developers need to
have the ability to pass parameters to requestShareApp that the
container can pass on to the app after completion.

I'd propose we consider for 0.8 the addition on a params field to
requestShareApp, similar to view-params in
gadgets.views.requestNavigateTo for this purpose:


<static> requestShareApp(recipients, reason, params, opt_callback)
Requests the container to share this gadget with the specified
users

Map.<String, String> params - Parameters to pass to the gadget after
it has been navigated to on the surface

-Lou

[Kevin Brown]

I think the view that is displayed should be explicit as well; otherwise developers will be forced to handle the shared post navigation in all views.

-Lou

--
~Kevin

[Evan Gilbert]

Parameters sound great.

I think we should consider folding the "view" in to be just another parameter, as there is usually an intelligent default (the canvas page). We may also want to support an "app" parameter in the future to allow navigating to different gadgets - you can easily see this as useful for multiple gadgets by the same developer.

[Louis Ryan]

+1

in addition to this we need a way for app developers to create links that they can embed in content to trigger the same behavior, this is something they are doing today in activites and is something that containers should allow or disallow in their TOS. This would be an excellent use case for templates.

The resultant view is very likely to be a policy decision by the container so we will need to figure out in the  API how best to represent this.

On Tue, Mar 25, 2008 at 9:42 PM, Kevin Brown <et...@google.com> wrote:

[Kevin Brown]

On Wed, Mar 26, 2008 at 10:26 AM, Louis Ryan <lr...@google.com> wrote:

+1

in addition to this we need a way for app developers to create links that they can embed in content to trigger the same behavior, this is something they are doing today in activites and is something that containers should allow or disallow in their TOS. This would be an excellent use case for templates.

Embed in what kind of content? In the gadget itself you can always set an onclick handler. Automatically generating anchors with click handlers sounds like the job of the templating helpers, but those don't really need to be in the spec yet since they can be used as external js dependencies anyway.

The resultant view is very likely to be a policy decision by the container so we will need to figure out in the  API how best to represent this.

On Tue, Mar 25, 2008 at 9:42 PM, Kevin Brown <et...@google.com> wrote:

On Tue, Mar 25, 2008 at 8:10 PM, Lou <lour...@gmail.com> wrote:

In order to better track information about invites developers need to
have the ability to pass parameters to requestShareApp that the
container can pass on to the app after completion.

I'd propose we consider for 0.8 the addition on a params field to
requestShareApp, similar to view-params in
gadgets.views.requestNavigateTo for this purpose:


<static>  requestShareApp(recipients, reason, params, opt_callback)
   Requests the container to share this gadget with the specified
users

Map.<String, String> params  - Parameters to pass to the gadget after
it has been navigated to on the surface

I think the view that is displayed should be explicit as well; otherwise developers will be forced to handle the shared post navigation in all views.

-Lou

--

~Kevin

--
~Kevin

[Cassie]

Please let me know if this would work as a spec change:

/**
 * Requests the container to share this gadget with the specified users.
 *
...
 * @param {opensocial.View} view The view to navigate to once the app has
 *     been shared
 * @param {Map<String, String>} params The parameters to pass to the app after
 * it has been navigated to on the specified view
...
 * @member opensocial
 */
opensocial.requestShareApp = function(recipients, reason, view, params,
    opt_callback) {};


- Cassie

[fer...@gmail.com]

"once app has been shared"

does that mean, after the requestShareApp has executed? Or does that
mean, after the recipient of the share adds the app??

On Mar 31, 8:08 am, Cassie <d...@google.com> wrote:
> Please let me know if this would work as a spec change:
>
> /**
> * Requests the container to share this gadget with the specified users.
> *
> ...
> * @param {opensocial.View} view The view to navigate to once the app has
> * been shared
> * @param {Map<String, String>} params The parameters to pass to the app
> after
> * it has been navigated to on the specified view
> ...
> * @member opensocial
> */
> opensocial.requestShareApp = function(recipients, reason, view, params,
> opt_callback) {};
>
> - Cassie
>

> On Wed, Mar 26, 2008 at 10:24 PM, Kevin Brown <e...@google.com> wrote:
> > On Wed, Mar 26, 2008 at 10:26 AM, Louis Ryan <lr...@google.com> wrote:
>
> > > +1
>
> > > in addition to this we need a way for app developers to create links
> > > that they can embed in content to trigger the same behavior, this is
> > > something they are doing today in activites and is something that containers
> > > should allow or disallow in their TOS. This would be an excellent use case
> > > for templates.
>
> > Embed in what kind of content? In the gadget itself you can always set an
> > onclick handler. Automatically generating anchors with click handlers sounds
> > like the job of the templating helpers, but those don't really need to be in
> > the spec yet since they can be used as external js dependencies anyway.
>
> > > The resultant view is very likely to be a policy decision by the
> > > container so we will need to figure out in the API how best to represent
> > > this.
>

> > > On Tue, Mar 25, 2008 at 9:42 PM, Kevin Brown <e...@google.com> wrote:

[Cassie]

Hmm.. I meant, and believe others meant that it was "once the
requestShareApp has been executed". I did not intend for it to mean
that each person who saw the invite would go to that view if they
accepted it. This is a perfectly valid request though, do you think we
need two parameters or can we stick with the first meaning for now and
add support for the second meaning later?

Thanks.

- Cassie

[Nat Brown (ilike.com)]

+1. in general any requestFoo functions that generate interstitial (as
opposed to pop-up) pages should support a next parameter. also would
be useful to standardize a "success" parameter. to support telling the
application that the user canceled what they started (e.g. sending a
message to another user if that was done interstitially). n@

[fer...@gmail.com]

Yes. The original post is quoted below. The whole point is to track
invitations, both sent and successfully accepted! :)

"In order to better track information about invites developers need to
have the ability to pass parameters to requestShareApp that the
container can pass on to the app after completion."

It basically boils down to workflow control.. as Nat Brown states,
allowing the app to control what happens after a particular
"interstitial". Joining an app through a particular invitation is a
major usability flow, that each app should be allowed to hook into.
Any such "interstitial" should accept something like
"NavigationParameters", that expose normal requestNavigateTo
parameters ( view, path, parameters, ownerId )!

For apps that just want to track successful invitations, you can add
something like an "inviteTrackingToken" to the appAdded-Ping feature.
The token could be generated by app and passed into requestShareApp,
or it could generated by container and returned from the
requestShareApp-response object.

On Apr 14, 5:37 am, Cassie <d...@google.com> wrote:
> Hmm.. I meant, and believe others meant that it was "once the
> requestShareApp has been executed". I did not intend for it to mean
> that each person who saw the invite would go to that view if they
> accepted it. This is a perfectly valid request though, do you think we
> need two parameters or can we stick with the first meaning for now and
> add support for the second meaning later?
>
> Thanks.
>
> - Cassie
>

[Cassie]

Okay, so I think -maybe- we have a +1 on this from the following people:

- fernman, Nat Brown, Lou,
- Louis?, Evan?

Louis and Evan, if you can confirm that you think this proposal is good (or bad) then we can resolve this.
For reference:

/**
 * Requests the container to share this gadget with the specified users.
 *
...
 * @param {opensocial.View} view The view to navigate to once the app has
 *     been shared
 * @param {Map<String, String>} params The parameters to pass to the app after
 * it has been navigated to on the specified view
...
 * @member opensocial
 */
opensocial.requestShareApp = function(recipients, reason, view, params,
    opt_callback) {};

Thanks!

- Cassie

[fer...@gmail.com]

+1

(oops i posted +1 to the other thread unnecessarily)

I also voiced a requirement that the opt_callback or the
ResponseObject from the DataRequest would contain the list of people
that were actually sent invitations (much like the requestSendMessage
call)

On Apr 20, 9:40 am, Cassie <d...@google.com> wrote:
> Okay, so I think -maybe- we have a +1 on this from the following people:
>
> - fernman, Nat Brown, Lou,
> - Louis?, Evan?
>
> Louis and Evan, if you can confirm that you think this proposal is good (or
> bad) then we can resolve this.
> For reference:
>
> /**
> * Requests the container to share this gadget with the specified users.
> *
> ...
> * @param {opensocial.View} view The view to navigate to once the app has
> * been shared
> * @param {Map<String, String>} params The parameters to pass to the app
> after
> * it has been navigated to on the specified view
> ...
> * @member opensocial
> */
> opensocial.requestShareApp = function(recipients, reason, view, params,
> opt_callback) {};
>
> Thanks!
>
> - Cassie
>

> On Mon, Apr 14, 2008 at 7:21 PM, fern...@gmail.com <fern...@gmail.com>

[Cassie]

On Mon, Apr 21, 2008 at 1:10 AM, fer...@gmail.com <fer...@gmail.com> wrote:

+1

(oops i posted +1 to the other thread unnecessarily)

I also voiced a requirement that the opt_callback or the
ResponseObject from the DataRequest would contain the list of people
that were actually sent invitations (much like the requestSendMessage
call)

This is already being discussed over here:
http://groups.google.com/group/opensocial-and-gadgets-spec/browse_frm/thread/04d654c18fc52c06#

It would be great if you could chime in as it has no consensus.
Thanks!

- Cassie
 

[Louis Ryan]

What is the expectation that containers will use interstitials? The opt_callback is pretty much useless in the interstitial case so would the container be expected to pass back the selected recipients in view-params? 

+1 on allowing params to be passed through to the invite recipients first post-install view via requestShareApp, Apps can choose to pass the inviting user id in that set.

-1 on allowing the app to specify what view of the gadget to go to if 'requestShareApp' requires an interstitial. The behavior should be return to the current view including the same view-params with the invite recipients added.

so I would propose

/**

 * Requests the container to share this gadget with the specified users.

 * Containers may navigate to an interstitial to complete the invitation process, in this case the opt_callback function will not be called with the list of actual recipients,

 * instead the recipient list will be included in the viewParams of the gadget once the interstitial process is complete along with the same viewParams that were present

 * before navigating to the interstitial.

 * @param {Map<String, String>} recipientParams The parameters to pass to the recipients first view of the app if they install the application as a result of this invitation

 *

opensocial.requestShareApp = function(recipients, reason, recipientParams, opt_callback)

[Marco Ensing]

It seems we need a bit more thought on this. I like Cassie's spec
change.
But we've also received requests that an application would like to be
notified when an application is removed/uninstalled.

So probably both onAcceptedAppInvitation, onApplicationInstall,
onApplicationRemove etc

It would be good if we have a general spec where all of these event
handlers can be defined.
Currently I don't have a good understanding if the current proposal is
a 'one-off' spec or a general solution.

No '+' or '-' for me.

Marco

On Mar 31, 8:08 am, Cassie <d...@google.com> wrote:

> > > On Tue, Mar 25, 2008 at 9:42 PM, Kevin Brown <e...@google.com> wrote:

>
> > > > On Tue, Mar 25, 2008 at 8:10 PM, Lou <lourmo...@gmail.com> wrote:
>
> > > > > In order to better track information about invites developers need
> > > > > to
> > > > > have the ability to pass parameters to requestShareApp that the
> > > > > container can pass on to the app after completion.
>
> > > > > I'd propose we consider for 0.8 the addition on a params field to
> > > > > requestShareApp, similar to view-params in
> > > > > gadgets.views.requestNavigateTo for this purpose:
>
> > > > > <static>  requestShareApp(recipients, reason, params, opt_callback)
> > > > >    Requests the container to share this gadget with the specified
> > > > > users
>
> > > > > Map.<String, String> params  - Parameters to pass to the gadget
> > > > > after
> > > > > it has been navigated to on the surface
>
> > > > I think the view that is displayed should be explicit as well;
> > > > otherwise developers will be forced to handle the shared post navigation in
> > > > all views.
>
> > > > > -Lou
>
> > > > --
> > > > ~Kevin
>
> > --

> > ~Kevin- Hide quoted text -
>
> - Show quoted text -

[Paul]

-1 to any specific solution for requestShareApp.

I would consider a generic solution as Nat suggested, but I don't see
a clear proposal in this thread.

~Paul

[Lou]

+1 to Louis' proposal. This can easily be extended to requestMessage
and is already supported in requestNavigateTo. Are there other methods
that could generate interstitials? The other main request from
developers for this feature is to pass next parameters through
installation process. But as there's no requestInstall, I don't see
where this would fit. For us it's just
requestNavigateTo(preview,params) which will work fine.

[Louis Ryan]

As a general note we could adopt the convention of using the function name which initiated the interstital process as the key which identifies success/failure/results in the view-params when control is eventually returned to the gadget.

This doesn't have to be a concrete part of the spec at this time.

[Cassie]

Okay, I'm going to attempt to summarize everything here (sorry fernman for losing to original intent before)

Marco - lifecycle events are now part of the approved set of 0.8 changes.  they were discussed over here and should solve what you were talking about:
http://groups.google.com/group/opensocial-and-gadgets-spec/browse_frm/thread/64f588e6daa72b0f

Paul - I think the proposal below defines something that could be used by both requestShareApp and requestShareMessage (and anything else that this eventually makes sense for)


Goal:
- after a user gets a shareApp invitation or receives a message a gadget developer should be able to send that user to a context sensitive place
- after a viewer actually shares an app with someone else the gadget developer should be able to redirect the viewer to a context sensitive place

My new proposal:
1. make an opensocial.NavigationParameters object, fields are "view", "parameters", "owner".
2. add an opt_params parameter to both the requestShareApp and the requestSendMessage methods
3. add two values that will be recognized in the opt_params bucket for both methods = "viewerDestination", "recipientDestination". these will both have type opensocial.NavigationParameters.
4. containers are free to ignore whichever parts of these new optional params they want but of course will make their gadget developers happier if they respect more of the params. this way, orkut doesn't have to change the view if it doesn't want to, but it can still respect the passed in params. on the other hand, hi5 could theoretically respect the view type, but always have viewer = owner (or whatever)


note: i'm putting this in the opensocial namespace instead of gadgets because gadgets.* a) we don't know if this will stick and opensocial has better versioning so we can take riskier steps and b) gadgets doesn't need it yet

alright, i think this fits everyones needs in but, as usual, please let me know your thoughts.
thanks.

- cassie

[fer...@gmail.com]

+1 cool. :) great to move forward with :)

On Apr 28, 9:19 am, Cassie <d...@google.com> wrote:
> Okay, I'm going to attempt to summarize everything here (sorry fernman for
> losing to original intent before)
>
> Marco - lifecycle events are now part of the approved set of 0.8 changes.

> they were discussed over here and should solve what you were talking about:http://groups.google.com/group/opensocial-and-gadgets-spec/browse_frm...

> - cassieOn Sat, Apr 26, 2008 at 4:12 AM, Louis Ryan <lr...@google.com> wrote:
> > As a general note we could adopt the convention of using the function name
> > which initiated the interstital process as the key which identifies
> > success/failure/results in the view-params when control is eventually
> > returned to the gadget.
>
> > This doesn't have to be a concrete part of the spec at this time.
>

[Evan Gilbert]

+1

Have a preference for view and owner ID just to be parameters, and have the NavParameters just take one params object. Will +1 either way, but wanted to mention the alternative.

[Lou Moore]

+1

[Louis Ryan]

+1

Can you propose for 0.9 that requestNavigateTo be switched to take a NavigationParams object or should we just bite that off here too?

[Cassie]

We should probably leave this for a later change as the gadgets js files don't have versioning... So, if we make this change we will break all gadgets using the feature. Once we have some concept of versioning then we can definitely switch. (That issue is probably a bigger bite though :)

- Cassie

[Cassie]

We should probably leave this for a later change as the gadgets js files don't have versioning... So, if we make this change we will break all gadgets using the feature. Once we have some concept of versioning then we can definitely switch. (That issue is probably a bigger bite though :)

- Cassie

On Wed, Apr 30, 2008 at 8:23 PM, Louis Ryan <lr...@google.com> wrote:

[Cassie]

This change is approved for 0.8
Thanks.

- Cassie