Changes

This The Presence service is hooked onto SimplePush, such that when a client ping comes in that includes presence info (either O,A, or U to indicate Online/Away/Unavailable based on the devices Presence policy dictated by the devices userand its idel time), then SimplePush will broadcast that to Presence somehow, that client id XXYYY is now O/A/U orwhatever. Presence then updates its record and relays the status update to the services the user has authorized.three functions:

The service stores records for every # let a user that has Presence 'activated'. The device is tied to the users FxA suchupdate her online status that if the device is lost, when they get # let a new one they will still identify the same. If/When user manages applications permissions# let a client needs todeveloper register an applicationre-register for SimplePush, the SimplePush client-id is sent to Presence to tie # let an application receive status updates# let an application send a live notification and a user receive it to the existing FxA record.

To avoid a call for every single status change, the Presence service may batch === Status updates to the various services sothat the webhook URL for each service is only called every 30+ seconds with all the updates intended for it (in thelist POST format explained above).===

# appmaker asks for a token# appmaker register to the presence server to ask for presence info - basically a POST with the web hook + the token as an auth## Bob decides to give appmaker Presence access.## Bob is redirected with appmaker token to Presence service.## Bob hits 'Yes' to grant appmaker access to his Presence## Bob is redirected back to appmaker with token that includes Presence UID (the one you'll get with the update in step 5)# bob updates his status with the presence# sarah updates her status with the presence# the presence service calls the webhook to notify status updates XXX define and detail "lively notification" === Proposed Modifications to SimplePush ===SimplePush protocol is [https://wiki.mozilla.org/WebAPI/SimplePush/Protocol defined here]. Principle changes to the protocol involve introducing a change to the "hello" and "ping" packets.  The "hello" packet needs to be modified to include a GUID as the user's Presence ID (PrID). This is required because SimplePush UserAgentIDs (UIAD) can change at any time, where the PrID is more "stable", but only active when the user opts into Presence. In an effort to save bandwidth, keys are reduced to x + "p" + sub identifier. old format:  {messageType": "hello", "uaid":"...", "channelIDs":[...]} new format:   {"messageType": "hello", "uaid":"...", "channelIDs":[...], "'''xpi'''":"..."} It is important to note that future simplepush reregistrations use the same "xpi" value (if defined). This will allow the SimplePush socket plugin monitor to associate the correct to the correct Presence server.  "ping" packets would use the optional long form and contain the Presence Status (xps).   {"messageType": "ping", "'''xps'''":"(UAO)?"} A simplepush "ping" packet is exchanged between the client and server when the user's status changes. User's status is indicated by * "A"way (user is idle or temporarily unavailable)* "U"navailable (user has gone offline)* "O"nline This information would be picked up by the Presence Plug-in to SimplePush which would send the status change to the Presence monitoring system using ''TBD'' REST calls. === For App Developers === Using presence in you application is done by: # including extra information in your app manifest# registering your app in the Presence service to receive notifications# Decide if you want to use the stream API or to get notified via a webhook# add a Presence doorhanger into your application so user can grant you access to their Presence info  ==== Changes to the app manifest ==== An app developer wishes to get presence information, the following can be added to the app manifest:  { "permissions": { "push": {"description": "To receive notifications about the newest phone releases"}, "presence": {"description": "To broadcast presence"} }, "messages": [ {"push": "/view_to_launch.html"}, {"push-register": "/view_to_launch.html"} ] } Note that the existing bits for SimplePush are retained, as Presence merely adds broadcast of the user's Presenceto the app. ==== Register the app in Mozilla Presence ==== The application developer must register their application separately with Mozilla Presence. XXX define the registering API here  ==== WebHook ====  It may optionally set a "Webhook URL" that will be called with presence updates for users that look like the following:   POST /some/webhook/callback {[ ["UID2949293", "away"], ["UID4823888", "online"], ["UID482838", "offline"], ["UID4828382", "online"] ]} In case the WebHook was not set by the application, updates have to be requested by using thestream API, as explained in the next section. ==== Stream ==== When the application is registered, it gets back a unique application id <appid>. This <appid> can be used to get a stream of presence updates by calling "GET <appid>/presence.json" This will return a stream of presence updates for usersthat look like the following:   GET <appid>/presence.json {[ ["UID2949293", "away"], ["UID4823888", "online"], ["UID482838", "offline"], ["UID4828382", "online"] ]} The application can consume the resulting stream for as long as is practical. The Presence server will hold the connection open indefinitely,barring server-side error, excessive client-side lag, network hiccups, routine server maintenance or duplicate logins.  ==== Setting up a doorhanger ==== When the user grants access, your application will get a unique ID that you should associate with the user recordyour application stores. A doorhanger will be needed in applications to prompt the user to grant an application Presence notification datashould the user not grant it initially when installing the app (and for websites that don't necessarilly installas 'apps'). Setup of a doorhanger will require the app developer to register their application with Mozilla Services and getan application token. This application token can be used with Mozilla TokenServer to register access with theMozilla Presence server. The app developer may then enter the "Webhook URL" in their Settings page for MozillaPresence. When a user signs-in to your application/website and you wish to ask for Presence notifications, you may redirectthe user to Mozilla Services asking for "Presence" access. The user will be prompted to grant access or deny andredirected back to your application. If the user granted access, the redirect will include an encoded UID that youshould store and associate with the user as this UID will be the one sent in the Webhook calls. App developers should account for the possibility that 'updates' may get lost, and automatically mark a user asoffline if no status is sent in an hour. === For Device Users ===  A separate Settings page is available, that looks similar to the iOS Notifications page, showing a list of apps andwebsites that have been granted Presence access. The page also lets one set a "Presence Policy" that determineswhat liveliness is communicated, for example: http://ziade.org/ffosx.png  Perhaps these will be sliders, UX is not determined this is only a possible example of how the user determineswhat type of 'livliness' data is sent based on whether they're using the device or not, and how recently. A list of toggles for each app the user has granted access to will be here, so that a user may turn off Presencefor individual apps temporailly without fully revoking possible future Presence broadcasts to the app/website.