Developing with Messenger Connect: Recognizable & intuitive

Windows Live REST Explorer screenshot The primary goal of Messenger Connect is to help web sites & apps grow their traffic and engagement, at a reasonable cost. To that end, the technical implementation and business terms have been designed to be predictable for web developers and marketers who are familiar with the social connections domain.

First question I get asked: Is Messenger Connect standards based?

We’ve tried to make Messenger Connect as easy as possible for developers to implement. Where possible, the latest emerging specifications and standards have been implemented and Microsoft engineers are actively involved in the community to help evolve the technologies which enable the relatively new use case of social connections. Some of the technologies we have implemented or contributed to are: OAuth WRAP, Portable Contacts, ActivityStrea.ms, and OData. What about the next big thing? As new technologies are created, and developers ask us to implement those technologies, we will work with the community and evaluate adding them to the mix.

Implementation options

Messenger Connect can be used on web sites (and other apps) to provide Windows Live users access to their information and communicate/share with their friends. This access to information and friends is made possible by several types of programmatic interfaces:

Badges – simple HTML tags that can be added to a page
JavaScript APIs (including user interface controls) which execute within most popular browsers and talk directly to the Windows Live services
.NET APIs which can be used in server-side ASP.NET code or in rich client applications
RESTful services end points which can be called in a server-to-server manner

Badges

Some developers don’t want to write JavaScript or server side code. That is OK. Our sharing badge can be simply added to a page in a few lines of code.

<a href="http://profile.live.com/badge?url={your URL}" title="Share with Messenger" target=”blank”>
  <img style="border-style:none; vertical-align:middle; margin-right:4px" 
     src="http://img.wlxrs.com/$Live.SN.MessengerBadge/icon16wh.png" 
     alt="Share with Messenger" />Messenger</a>

Try it: Share with Messenger Share

Consent, access, privacy, data rights, revocation

We recently posted about the privacy aspects of Messenger Connect (read it here). We strongly believe that users own their data and they should be able to share or access it from the websites and applications they want to. Web sites cannot access any of a user’s non-public information from Windows Live without prior consent (see the experience below) from the Windows Live user. App developers are encouraged to only request the bare minimum of permissions required to complete the desired scenario in a just in time manner (E.g. if a user is signing up, ask for their profile, if a user is adding something to their calendar, ask for calendar write permissions). If a user chooses not to grant permission for the site to access what they requested, the web site must handle the exception flow and reduce the permission requests, or explain why those permissions are required.

If the user leaves the “Remember this connection” checkbox checked (it is checked by default), the web site will be granted permission for 1 year (or until the user revokes the permissions). If the user unchecks the “Remember this connection” button, the web site will get access for 3 hours. At any point in time the user can browse to http://consent.live.com and revoke the permissions they previously granted the web site. After the token expires, or the user revokes permission, the web site would get 401 Unauthorized errors when trying to access the data, and would need to re-request that the user grants permission.

The web site renders a “sign in” button either manually by creating HTML, or using the wl:signin tag. If the web site uses the wl:signin tag (more info), an additional attribute can be added to only show the sign in button if a Windows Live cookie exists.
The user browsing the website (e.g. www.example.com) and sees a Messenger Connect button and clicks Sign In. To ensure the most Windows Live users know they can “Connect”, the iconography used for button will be aligned behind a single brand used across all “non-Windows Live” web sites (i.e. the current Hotmail / Messenger / Windows Live / SkyDrive brand fragmentation will be reduced in “off-network” scenarios).
A popup window is opened which includes the partner’s logo, a link to their Terms of Service and Privacy Statement. The partner must clearly outline in their ToS & Privacy Statement what they will be doing with the permission granted by the end user.
The user can click “What will I share?” to see each individual permission the partner is requesting.

Messenger Connect Consent User Experience

If the user grants permission, a token is returns to the site, and the window will be closed.

One a website has been granted the appropriate permissions and has received the token, access to the user’s Windows Live data & services is possible through two interfaces: JavaScript & RESTful interfaces.

The permission granted is for 1 year (unless the user unchecks Remember this Connection). If the web site wants to access the Windows Live resources without the user being present, or without the user seeing the Messenger Connect consent screen again, the token should be stored alongside the user’s profile in the partner’s website.

If the user changes their mind and no longer wants the web site to have the ability to interact with their Windows Live account, the user can go to http://consent.live.com to revoke permissions at any time. If the partner tries to interact with the user’s Windows Live account after consent has been revoked, they would get “unauthorized access” errors and would need to re-request access from the user.

JavaScript libraries & user interface controls

Adding a script reference to the Messenger Connect dynamic loader enables access to a wide range of Windows Live data and Messenger features, including IM conversations. Developers can choose to use the data objects only or can add UI elements such as <wl:signin>, <wl:userinfo> or <wl:bar> to their page. You can experiment with the data model and controls hands-on using our new interactive SDK at http://isdk.dev.live.com/.

RESTful service endpoints

A set of cloud endpoints are available to web sites and applications for the purposes of accessing and managing user data. Generally the RESTful service endpoints will be used for web sites that want more of a “roll your own” approach to data access. Additionally, the RESTful endpoints are useful for sites that want to access the user’s data while the user is not present (for example: out of band processing of data - each week the website could make a call to Windows Live to download a user’s address book to see if some of their Windows Live friends have joined the web site).

These endpoints are multi-headed (the data is generally available in several formats), and can be queried and sorted. If developers prefer the data to be returned in several formats this is easily configurable using the $format query string key (for plain XML $format=XML, for JavaScript Object Notation (JSON) use $format=JSON, the dynamic formatting is also applied to emerging specifications/standards such as $type=portable). Additional formats for representing user data will be added based on partner feedback.

The RESTful service endpoints are also intelligent and most data-types exposed will support filter, select, orderby, and count the protocol used is the Open Data Protocol (OData).

Developer tooling

To make it easy for developers to kick the tires, we’ve created a few tools: the Controls Playground, the API Playground, and the REST Explorer – these tools will evolve over time as we see where developers need help. In a future post we’ll share details about the statistics which will be available from the application management portal.

The Controls Playground lets you quickly preview the Windows Live UI controls in action, customize controls and see results in real-time and also generates markup for these controls for you to copy, paste in your application.

The API Playground lets you try out the API service to see what type of interactions are possible:

Select common tasks such as adding a new contact to Windows Live, and preview the code
See common API usage patterns
Run API code, using sample data, and see the output in real-time
See the underlying REST HTTP traffic including request and response