Windows Live Contact Cards

The folks over at Windows Live have recently released an update for the Contact Cards API to v0.2 (see dev.live.com for details).

What is a contact card?
A contact card (or perhaps cards) is really the list of all your contacts that you have associated with a particular Microsoft Passport account.

Quick Demo.
Here is a quick demonstration of how to use this technology within your own web site.
All that this demo does is display the contact card, the user then selects which contact information they want to send your site and the site displays that information.
On a real site you could use this information for various purposes, perhaps storing it in a database for email alerts, if you’ve got some kind of greeting card or messaging system on your site then this would be an easy way for the user to select where to send the greeting card etc.
I’m still thinking of ideas on the actual practical uses for this so if anyone has any ideas, please sound off.
So onto the quick demo.

First off create a blank Web Site in Visual Studio. That should give you your App_Data folder and a single Default.aspx page.

Next right click in the Solution Explorer pane and select “Add a New Item”. Select Html Page from the choices available and name your page “channel.htm” (Note: This is actually a default name used by the contact card API and therefore best if you create the page with this name, although you can call it whatever you want).
Next copy the following code into your channel.htm page :-

<html xmlns=”http://www.w3.org/1999/xhtml“>
<head>
<title>Channel</title>
<meta name=”ROBOTS” content=”NONE”/>

<script type=”text/javascript”>
function doc_loaded()
{
    try
    {
        var hash = window.location.hash.substr(1);
        if (window.location.replace == null)
            window.location.replace = window.location.assign;
        window.location.replace(“about:blank”);
        var name = hash.split(“/”)[0];
        var win = null;
        if (name)
            win = window.parent.frames[name];
        else
            win = window.parent.parent;
        win.Microsoft.Live.Channels.Mux._recv_chunk(window.location);
    }
    catch (ex)
    {
        /* ignore */
    }
}
</script>
</head>
<body onload=”doc_loaded()”></body>
</html>

The Windows Live Contacts control uses a communication channel technique to send data between pages from different domains within the browser. That is the whole purpose of the above file. If you want to receive data from Contact Cards then you need the above file somewhere in your web site.

Next we’ll work on the main page that will host the contact card and display the information, so open your default.aspx page.

The first thing that you’ve got to do is to add a xml namespace reference to contact cards (actually the reference goes to dev.live), so ammend your <html> so that it’s the following :-

This keeps the original xml namesspace for xhtml so that your web pages will be xhtml compliant and adds a named namespace to devlive (contact cards).

The next thing is to add a couple of references to the javascript API files so add the following to your page.

The latest release of the contact cards api is v0.2.

The next thing you’ll want to do is to add the Contact Card itself to your page.
You do this through the xml namesspace reference you added earlier to the html tag and supply it with the appropriate parameters.
The contact card tag is :-
<devlive:contactscontrol

and the list of parameters is as follows :-

style=”width:250px;height:400px;float:right;border:solid 1px black;”
devlive:privacyStatementURL= “http://hackersoft.dyndns.org/privacyPolicy.aspx“
devlive:channelEndpointURL=”channel.htm”
devlive:dataDesired=”name,email,firstname,lastname”
devlive:market=”en”
devlive:onSignin=”onSignin”
devlive:onSignout=”onSignout”
devlive:onError=”onError”
devlive:onData=”onData”>

First off you have the style parameter which is your standard css style parameter for rendering the control.

Next you have a link to a privacy policy document held somewhere on your site.

Next a link to the channel endpoint page that we coded above. If you omit this parameter then the Contact card api will look for a file called “channel.htm” within the root of your site. If you called this file something else or placed it elsewhere then this is where you enter the fully qualified url to the file.

Next you specify which data you want to receive, in this demonstration we’re asking for name, email address, forename and surname. The information you require is a comma delimited list of the following :-

name (Name or nickname, or email address if no name is available.)
email (Primary email address, or personal or business email if no primary is indicated.)
phone (Primary phone number)
firstname,
middlename,
lastname,
nickname,
passportname (user’s Passport ID or Windows Live ID),
emailpersonal,
emailbusiness,
emailother,
phonepersonal,
phonebusiness,
phonemobile,
phonepager,
phonefax,
phoneother,
personalstreet,
personalcity,
personalstate,
personalcountry,
personalpostalcode,
businessname,
businessstreet,
businesscity,
businessstate,
businesscountry,
businesspostalcode,
websitepersonal,
websitebusiness

The next parameter is which language (defaults to english)

The next 4 parameters are Javascript callbacks for Login, Logout, Error and Data if you want to do any processing against these. The one we’re interested in Data as this is the data that will be sent back to us.

So now that you’ve got your contactscontrol tag in place with the appropriate parameters completed it’s time to code the javascript callback routines.
The first 3 calback routines are blank as we’re not interested in capturing these events in this demo :-

function onSignin()
{
// user is signed in
}
function onSignout()
{
// user is not signed in
}
function onError()
{
// there was a data transfer error
}

The last callback routine is the one that we’re interested in, onData. This accepts a parameter which is the data returned by the server. You can then simply extract the values from this class and do whatever you wish with them.

function onData(userContacts) { var s = userContacts.length + " records received. <br>"; for (var i = 0; i < userContacts.length; i++) { s += "<p>"; s += "Contact Name: " + userContacts[i].name +"<br>"; s += "Contact Email: " + userContacts[i].email +"<br>"; s += "Contact Forename: " + userContacts[i].firstname +"<br>"; s += "Contact Surname: " + userContacts[i].lastname; s += "</p>"; } var info = document.getElementById("lbl"); info.innerHTML = s; }

And that’s it, your final default.aspx page should look like this :-


<%@ Page Language="C#" AutoEventWireup="true"  CodeFile="Default.aspx.cs" Inherits="_Default" %>
<!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:devlive="http://dev.live.com/" >
<head runat="server">
    <title>Contact Card Test</title>
    <script type="text/javascript" src="http://dev.live.com/scripts/base/v0.2/live.js%22%3E%3C/script>
  <script type="text/javascript" src="http://dev.live.com/scripts/contacts/v0.2/control.js%22%3E%3C/script>
  <script type="text/javascript">
   function onSignin() 
   {
    // user is signed in
   }
   function onSignout() 
   {
    // user is not signed in 
   }
   function onError() 
   {
    // there was a data transfer error
   }
   function onData(userContacts) 
   {
    var s = userContacts.length + " records received. <br>";
    for (var i = 0; i < userContacts.length; i++) 
    {
     s += "<p>";
     s += "Contact Name: " + userContacts[i].name +"<br>";
     s += "Contact Email: " + userContacts[i].email +"<br>";
     s += "Contact Forename: " + userContacts[i].firstname +"<br>";
     s += "Contact Surname: " + userContacts[i].lastname;
     s += "</p>";
    }
   var info = document.getElementById("lbl");
   info.innerHTML = s;
   }
</script>
</head>
<body>
  <form id="frmContactCards" runat="server">
    <div>
  <devlive:contactscontrol 
   style="width:250px;height:400px;float:right;border:solid 1px black;"
   devlive:privacyStatementURL= "http://hackersoft.dyndns.org/privacyPolicy.html"
   devlive:channelEndpointURL="channel.htm"
   devlive:dataDesired="name,email,firstname,lastname"
   devlive:market="en"
   devlive:onSignin="onSignin"
   devlive:onSignout="onSignout"
   devlive:onError="onError"
   devlive:onData="onData">
   <noscript>The Windows Live Contact Cards requires Javascript</noscript>
  </devlive:contactscontrol>
    </div>
    <div id="ContactInfo">
   <asp:Label ID="lbl" runat="server" />
    </div>
  </form>
</body>
</html>

Run your example and start playing around with the API. Note that the user is always in control of which information they want to give to your website so you can’t just request information without the user knowing about the request.

Windows Live Contact Cards

Thanks for 9 great years!

The latest from OnMSFT.com