For simplicity, the functions are described as if they are regular blocking functions (ie, they specify a return value). However, as they are implemented using jschannels, the actual implementation will be that the caller obtains the "return value" via jschannel 'success' callback.
Authentication is all performed by the WMF library - see Labs/F1/Modularity#Authentication for details.
To be implemented by the app (ie, APIs called by F1)
Get enough metadata about the application so the necessary UI for the service can be dynamically built. This is similar to the current F1 "services" global, and allows F1 to offer "send to wall" for facebook versus "send to my contacts" for linkedin.
The information returned by this method is static and must not depend on the logged-in user, if any. IOW, this method may be called before a user is logged in and may not be called again after login/logout events.
NOTE: As all the information here is relatively static, there was some discussion about putting them directly in the app manifest. However, in the interests of keeping the manifest small and not requiring regular refreshes of the manifest to get new information, it is currently defined as a method. This may want to be re-evaluated if these calls add to a perception of poor performance.
The result is an object with the following fields (mostly taken from the current F1 implementation)
- The (localized) name of the service as displayed to the user. If not specified the service name as defined in the manifest will be used. The name may be rendered as a link to the 'serviceUrl'.
- serviceUrl; A link to the 'home page' for this particular service. If not specified the application's origin (as defined by the app manifest) will be used.
- Whether the app supports a 'subject' field.
- A list of ways an item can be shared with this service. If the service supports direct messaging, then this must be reflected in shareTypes. Each element in the list may have fields type (an identifier passed back to the service if this item is selected), label (what is shown to the user) and toLabel (the label for the 'to' field - if not specified, the 'to' field is hidden)
- The maximum number of characters allowed. If specified, a counter will be displayed and the limit will be enforced.
Note the following fields from the current F1 implementation have been removed (mainly as they can be derived from the above fields.)
- A boolean indicating if links must be shortened, but this can be derived on a per-share basis based on the specified textLimit and the amount of text currently entered.
- The webapp manifest already defines the icons.
- Indicated if direct messaging is supported, but this can be reflected in the 'shareTypes' field and need not have its own flag.
- This URL is (or may be) specific to the currently logged in user,
so is reflected in the user-info field.
- As above.
- The service logout() method will be used.
- Why is this needed in F1 and why can't the service work this out itself?
- This referred to F1 implementation details so can't be supported generically. If F1 still chooses to use overlays for selected services, these will need to be defined internally and not reflected here.
- Seems to be a hangover from an old F1 impl?
- Can be derived from whether the 'toLabel' field exists.
Get all the autocomplete entries for the "to" field based on the current setting of the "send to" field for the specified user and the text currently entered in the 'to' field. For example, the facebook app might return the (filtered) list of all groups you are a member of if send_to="group wall", and twitter would send a (filtered) list of all your followers for send_to="direct".
There is no concept of "paging" the results as it seem unlikely users will actively "page" an auto-complete list - instead they should focus on providing a shorter list of relevant results.
The size of the returned list is not constrained by this method, but WebMods will be encouraged to keep the result list to a reasonable (but relevant) size, or risk offering a poor UX for users of that service.
If the above size restrictions are a problem, we probably need to add the concept of a "chooser ui" which is different from the auto-complete UI?
NOTE: This method exists as a way to avoid introducing a full-blown Contacts concept and the complexity that would involve. However, a key downside is that cross-service sharing of this information becomes impossible - eg, if 2 different services provide email addresses, nothing in this spec allows F1 to notice that fact and reuse the email addresses for all services which support sending emails.
NOTE: This might need fine-tuning for performance reasons - currently F1 uses a cache of contacts, but the technique described here probably needs one call per character typed. I guess we can still make the caching (or lack thereof) the responsibility of the service itself (so while we may still make one call per character typed, that call need not result in network activity)
NOTE: The OWA spec defines that this method should be called confirm - this needs to be clarified.
Send an item as described by "data" - ie, perform the actual share.
credentials_blob is the blob returned by the authentication process, or null if the WebMod does not provide the blob during auth.
data is a json object describing the message to be send. The fields are TBD but will be based closely on the F1 implementation. No user info will be included in this data.
The result will be a json object with the following fields:
- The status of the send. Currently the only supported value is sent, but services may also return, eg, pending to indicate it has been queued and will be sent when (eg) the network becomes available.
- A link to the message that was just shared - eg, if the message was sent via twitter, the link would point at the specific tweet.
If an error occurs, it will be reported via the normal jschannel error callback (ie, with error and message parameters, where the content of message will depend on the value of error. All strings which will be displayed to the user should be localized. The following error values are supported:
- Indicates the message failed due to an authentication problem (eg, the cookie expired). Authentication will be re-performed and the user will be given the opportunity of retrying the error. message will be null.
- Indicates validation of the data failed for some reason. message will be an object with properties name (the name of the field in the send data which failed validation) and reason (the reason the field is invalid). The F1 UI will display the error and focus the appropriate field so the user can fix it and retry.
- Indicates a HTTP error occurred sending the item. message will be the http error code. This would be an appropriate error if a back-end server returned a 500 error (eg, twitter was down), but is not appropriate for a 401 error - the service should translate a 401 to an authentication error if re-authentication is necessary.
- Indicates that even though the user is correctly logged in, the service requested a captcha be solved before the message can be sent. message will be an object with fields imageurl, audiourl and message. F1 will display the message and the image, and provide a way to play the audio, and after the user enters the answer, will re-try the send request with the optional captcha fields included.
Any other value will cause message to be displayed in a generic error dialog, after which the user may either retry or abandon the share.