It's not about what we have, it's about what we share... Part Four - Plankytronixx - Site Home

Well, at last! In this piece we get in to a little code and write something that runs! I'd recommend you read part one, part two and part three before playing with the code in this post because they describe what is happening. By understanding what data and tokens are moving between what services; by realising there are really 3 parts to Windows Live and by understanding a little about the OAuthWRAP profile, you'll have a much better understanding of what these different code elements are doing and therefore be better able to apply your own creativity to the things you'd like to achieve with Messenger Connect.

Client scope

The user is going to give a website access to some potentially very sensitive information. Recall in figure 5, there is a Windows Live UI element that shows what the site has asked for (in this case to view your contacts and view your profile). The site uses the client scope to communicate what parts of your Windows Live environment it wants access to.

I said it's a tetchy area, because it concerns privacy. For this reason there are 2 main classes of client scope. One is for pretty much any website. The other is for websites that have entered in to a special partnership arrangement with Microsoft, via the management portal (http://manage.dev.live.com). These sites can specify a client scope that gets access to more of the Windows Live information. The process to be permitted access to this scope is for the site to be vetted (by a human being) by Microsoft.

Remember though, the user still has control and still has to grant consent (see figures 4 and 5) for the site to get access to their information. The scope types are:

Public scopes: Available to any application. Your application's use of public scopes is governed by the Windows Live Developer Services Terms of Use and the Windows Live SDK License Agreement. When you connect your application by registering it with the Windows Live application management site (https://manage.dev.live.com), public scopes are available to your application.
Restricted scopes: Available to your application only with approval from Microsoft. These scopes are not available for use by your application until you have approval, for which you will have to email mcsup@microsoft.com, describing which restricted scope you want to access and how it will be used.

If you want to know more about what each type of scope gets you access to, click here. In short with public scopes your application can view the users' activities, photos, contacts and profiles. You can also update their activities and status. With restricted scopes your application can view the users' calendars and get full views of their profiles and contacts. You can also update their contacts and profiles. You can see why Microsoft would want to be assured of your authenticity if you had such power and therefore why some scopes are restricted.

Controls

The best way to see how the controls are used is to create a simple site. Bear in mind everything from parts 1, 2 and 3 to understand how the data is moving from the different parties.

The UI controls are javascript constructions. In your page you'll need a reference to an XML namespace which can go inside the HTML tag:

xmlns:wl="http://apis.live.net/js/2010"

From now on, in the page, whenever you can use wl:<control name> to start loading controls. The question is - how does that load controls? Well it doesn't, the controls themselves are loaded by a javascript loader. You put this in the script section of your page:

<script type="text/javascript" src="http://js.live.net/4.0/loader.js"></script>

Loader.js (and if you need to debug, loader.debug.js) will analyse your page and work out the additional javascript files you need to get the various controls and control features loaded. The aim is for it to be lightning fast which is why you'll want the debug version if you want to understand the magic it uses to do this. The javascript has been minimised and is highly unreadable, but it makes for fast load times: the same as the other javascript files it loads.

Then, down in the body of the page, you'll need to give the page information about the application. This is done with an app tag:

<wl:app  channel-url="/channel.htm" 

         callback-url="/OAuthWrapCallback.ashx?wl_session_id=<%= Session.SessionID %>"

         client-id="00000000xxxxxxxx" 

         scope="WL_Contacts.View,WL_Profiles.View, Messenger.SignIn">

</wl:app>

The channel.html file is included in the unzipped Windows Live SDK. This is another unreadable, minimised file. Recall in step 17 of figure 3 (in part two), and later when the tokens were presented to the Windows Live API service... This is the file that performs all that magic with the tokens that are codified in to cookies and means you don't have to store the token in your application - which in turn means the work can be done by client-side javascript. Make sure you add this file to your site.
The callback URL is the one mentioned in steps 11 and 12 of figure 3 (in part two) which accepted the verification code and passed over the client secret to the Windows Live Token URL. The callback code itself is actually supplied in an assembly that's part of the Windows Live SDK. We'll return to this later.
The client ID is the one you registered at manage.dev.live.com. There is a picture of it in figure 2 (in part one).
The scope is discussed in the client scope section which you've probably just read. In this case you can see the requested scopes fit with the consent screen shown in figure 5 (part two).

The next control to add is the signin control. Remember loader.js will analyse the page and see this control and any features. It will load the necessary javascript for you.

<wl:signin>

</wl:signin>

A good control to add now so you can see what Windows Live information you've asked for is the userinfo control.

<wl:userinfo>

</wl:userinfo>

Again loader.js will work its magic and load the necessary javascript for you. At this stage you could run the project and you'll see this in your web page:

Figure 6: The Sign In control and the User Info control

You'll also notice lots of javascript libraries loaded in Visual Studio:

Figure 7: Some of the javascript files fired up by loader.js

At this stage, your page will look something like this:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="WebForm1.aspx.cs" Inherits="Cantasa.WebForm1" %>

 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

 

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:wl="http://apis.live.net/js/2010">

<head runat="server">

    <title></title>

    <script type="text/javascript" src="http://js.live.net/4.0/loader.debug.js"></script>

    

</head>

<body>

    <form id="form1" runat="server">

    <div>

    <wl:app channel-url="/channel.htm" 

            callback-url="/OAuthWrapCallback.ashx?wl_session_id=<%= Session.SessionID %>"

            client-id="00000000xxxxxxxx" 

            scope="WL_Contacts.View,WL_Profiles.View, Messenger.SignIn">

    </wl:app>

 

    <wl:signin>

    </wl:signin>

 

    <wl:userinfo>

    </wl:userinfo>

 

    </div>

    </form>

</body>

</html>

The bold text shows the pieces you'd need to add to a standard naked web form.

When you click the signin control (curiously named "connect"), steps 1 through 8 in figure 3 (part one) are executed (if you attempt the authentication that is). Because the callback URL is not properly configured yet, the process stops at this point. Refer back to steps 1 through 8 of figure 3 (part one) and you'll see how information such as the client ID, the scope and so on are communicated between the different players.

In the next article we'll have a look at a little more of the code that implements steps 9 through 17 in figure 3 (part one).

Have fun…

Planky