Hosting the Sign-in Control

Article
10/02/2008

Before using any Messenger-based application, site visitors must be authenticated using a Windows Live ID and sign in to Messenger. You can embed the Messenger Library Sign-in Control on a Web page so that users can initiate the authentication and sign in process. In this three-part tutorial you will learn how to add the Sign-in Control to a Web page.

When the sample code from this topic is run, it displays the Sign-in Control. When a user signs in, the flow of events is as follows:

When the page loads, it loads the Windows Live Messenger Library JavaScript file from https://www.wlmessenger.net/api/2.5/messenger.js. This must be done prior to calling any library methods.
The application code creates the Sign-in Control and registers the AuthenticationCompleted event.
The Sign-in Control is displayed.
The user clicks the "Sign In" button.
If the user is not already authenticated, the user is prompted to sign in to Windows Live ID.
When the user is authenticated, the Messenger Library initiates a series of checks:
- If the user is a Windows Live OneCare Family Safety restricted user, then the user is prevented from continuing.
- If the application is not currently authorized to sign the user into Messenger, the user is prompted for permission. The user can choose to authorize the application or cancel.
- If the application has permission to sign the user in to Messenger, and the user is currently signed in to Messenger elsewhere (such as with the desktop Windows Live Messenger client), the user is asked if they want to proceed with sign in and possibly sign out from the other location.
When the above checks are complegted, any AuthenticationCompleted event handlers are called. This event handler should contain code to create the SignInCompleted event delegate.
The AuthenticationCompleted event includes the AuthenticationStatus property, which indicates the result of authentication. Assuming authentication is successful, the application can sign the user in to Messenger with the User.SignIn method.
When the user is signed in to the Messenger service, any SignInCompleted event handlers registered by the application are invoked. Applications should initialize the user's state based on this event. For example, applications can now show the user's contact list, show presence of contacts, enable sending and receiving of instant messages, and so on.

Overview

For this sample, the following tasks are demonstrated:

Adding the Sign-in Control to a Web page.
Using the SigninCompleted and AuthenticationCompleted events.

The following Windows Live Messenger Library classes and members are used:

Microsoft.Live.Messenger.UI.SignInControl

Creating the Project Files

The sample application consists of these files:

Default.htm — Contains all JavaScript and HTML for hosting the Sign-in Control.

Channel.htm — Facilitates cross-domain communication between your application domain and the Windows Live service domain ("live.com").

Privacy.htm — Displays your Web site's privacy policy to site visitors.

Default.css — A style sheet that defines the appearance of the sample.

Note

Default.htm is the only file that you will change throughout the tutorial. You can find a completed version of the file at the end of this topic. The code for other files in the sample application of this tutorial, Channel.htm, Privacy.htm, and Default.css, does not change.

Default.htm

Default.htm contains the application JavaScript and UI including the Sign-in Control. The Sign-In Control control is set to display inside a <div> element with the ID signinframe. Default.htm should be set as the default page for the Web site.

To Create Default.htm

Using the IDE or text editor of your choice, create a new file and name it Default.htm.

Copy the following code, paste it into the file, and save the file.

<html xmlns="https://www.w3.org/1999/xhtml" >
<head>
<title>Windows Live Messenger Library</title>
<link rel="stylesheet" href="Default.css" type="text/css" />   
<script src="https://www.wlmessenger.net/api/2.5/messenger.js" type="text/javascript" language="javascript"></script>
<script type="text/javascript" language="javascript">
// Add code here.
</script>
</head>
<body onload="scriptMain()">
    <div id="msgr">
     <table>
         <tr>
             <td style="height:150px">
                 <div id="signinframe">
                    </div>
             </td>
         </tr>
         <tr>
             <td>
                 <div id="userInfo">
                    </div>
             </td>
         </tr>
     </table>


 </div>
</body>
</html>

Adding the Control Code

This procedure walks you through adding the JavaScript for hosting the Sign-In Control.

The authenticationCompleted function creates a new Microsoft.Live.Messenger.User object for the user, creates a delegate for Microsoft.Live.Messenger.User.SignInCompleted and signs in the user to Messenger.

If the sign-in was successful, the signInCompleted function displays a message.

To add code for the Sign-in Control

Using the IDE or text editor of your choice, open Default.htm.
Add the following code between the <script> tags, where it says // Add code here.
```
function scriptMain() 
{
    var hostUrl = window.location.href;
    var index = hostUrl.lastIndexOf("/");
    hostUrl = hostUrl.substring(0, index);
    var privUrl = hostUrl + "/Privacy.htm";
    var chanUrl = hostUrl + "/Channel.htm";

    _signin = new Microsoft.Live.Messenger.UI.SignInControl('signinframe', privUrl, chanUrl, 'en-US');
    _signin.add_authenticationCompleted(authenticationCompleted);
}
```
The script scriptMain() is the first function to execute. This function creates an instance of Microsoft.Live.Messenger.UI.SignInControl and registers an event handler for Microsoft.Live.Messenger.UI.SignInControl.AuthenticationCompleted. The Sign-in Control is created using the following parameters:
- The ID of the DOM element to display the control (signinframe).
- URLs for the channel page (Channel.htm) and the privacy page (Privacy.htm). Note that these files must be hosted at the root of the application domain server.
- The Culture ID for the language in which the control should be displayed. If this value is left blank, the default value, U.S. English (en-US), is used. For a list of supported languages, see Appendix A: Supported Languages.
The authenticationCompleted function obtains the identity of the user that just signed in, registers a handler for the signInCompleted event, and calls the User.signIn method to sign in the user to the Messenger service. Add the following code immediately after scriptMain():
```
function authenticationCompleted(sender, e) 
{
    _user = new Microsoft.Live.Messenger.User(e.get_identity());
    _user.add_signInCompleted(signInCompleted);
    _user.signIn(null);
}
```

Lastly, paste the following code after authenticationCompleted.

function signInCompleted(sender, e) 
{
    if (e.get_resultCode() === Microsoft.Live.Messenger.SignInResultCode.success) 
    {
        document.getElementById('userInfo').innerHTML = '<p>' + _user.get_address().get_address() + ' is now signed in.</p>';   
    }
}

_user = null;
_signin = null;

The signInCompleted event handler is used to perform any tasks that should occur immediately after sign-in. In this example it is used to announce that the user has signed in.

Channel.htm

The purpose of Channel.htm is to facilitate cross-domain communication between the application domain and the Windows Live service domain. You don't have to make any changes to the code contained here, but the page must be present on your site to use the Sign-in Control and the rest of the Messenger Library.

To Create Channel.htm

Messenger Using the IDE or text editor of your choice, create a new file and name it Channel.htm.

Copy the following code, paste it into the file, and save the file.

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

<script type="text/javascript">
function onLoad()
{
    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 && (name != ".parent"))
        {
            win = window.parent.frames[name];
        }
        else
        {
            win = window.parent.parent;
        }
        if (win.Microsoft)
        {
            win.Microsoft.Live.Channels.Mux._recv_chunk(hash);
        }
    }
    catch (ex)
    {
        /* ignore */
    }
}
</script>
</head>
<body onload="onLoad();"></body>
</html>

Privacy.htm

The purpose of Privacy.htm is to display your Web site's privacy policy to site visitors. This file is required. For more information about privacy, see https://privacy.microsoft.com/en-us/default.aspx.

To Create Privacy.htm

Using the IDE or text editor of your choice, create a new file and name it Privacy.htm.

Copy the following code, paste it into the file, and save the file.

<html xmlns="https://www.w3.org/1999/xhtml">
<head>
<title>Privacy Policy</title>
<meta name="ROBOTS" content="NONE"/>
</head>
<body>
<!-- The privacy policy for your Web site goes here. -->
</body>
</html>

Default.css

The style sheet defines the appearance of the sample.

To Create Default.css

Using the IDE or text editor of your choice, create a new file and name it Default.css.

Copy the following code, paste it into the file, and save the file.

#msgr 
{
    font-family: Tahoma,arial,sans-serif;
    font-size: 12px;
    float: right;
    width: 400px;
    border: solid 1px black;
}

#signinframe
{
    width: 400px
    position: relative;
}

#userInfo
{
    position: relative;
}

#setUserStatus
{
    position: relative;
}

#selectStatus
{
    width: 250px;
}

#setPersonalMessage
{
    position: relative;
}

#personalMessage
{
    width: 200px;
}

#txtConv
{
    width: 375px;
    height: 150px;
    border: black 1px solid;
    overflow: auto;
    font-family: Tahoma,arial,sans-serif;
    font-size: 12px;
}

#txtMessage
{
    width: 375px;
}

#divConversations
{
    width: 375px;
    height: 125px;
    border: solid 1px gray;
    position: relative;
    overflow: auto;
}

#divContacts
{
    width: 375px;
    height: 150px;
    border: solid 1px gray;
    position: relative;
    overflow: auto;
}

#introPage
{
    font-family: Tahoma,arial,sans-serif;
    font-size: 12px;
}

.ContactItem
{
    cursor: hand;
    text-decoration: underline;
    color: blue;
}

To Run the Sample

Upload the completed project files to your Web server.
Navigate to Default.htm on your Web site.
Click on the button to Sign In.

Default.htm (completed)

The following code example shows the completed version of Default.htm.

Default.htm

<html xmlns="https://www.w3.org/1999/xhtml" >
<head>
<title>Windows Live Messenger Library</title>
<link rel="stylesheet" href="Default.css" type="text/css" />   
<script src="https://www.wlmessenger.net/api/2.5/messenger.js" type="text/javascript" 
    language="javascript"></script>
<script type="text/javascript" language="javascript">
function scriptMain() 
{
    var hostUrl = window.location.href;
    var index = hostUrl.lastIndexOf("/");
    hostUrl = hostUrl.substring(0, index);

    var privUrl = hostUrl + "/Privacy.htm";
    var chanUrl = hostUrl + "/Channel.htm";
    _signin = new Microsoft.Live.Messenger.UI.SignInControl('signinframe', privUrl, chanUrl, 'en-US');
    _signin.add_authenticationCompleted(authenticationCompleted);
}

function authenticationCompleted(sender, e) 
{
    _user = new Microsoft.Live.Messenger.User(e.get_identity());
    _user.add_signInCompleted(signInCompleted);
    _user.signIn(null);
}

function signInCompleted(sender, e) 
{
    if (e.get_resultCode() === Microsoft.Live.Messenger.SignInResultCode.success) 
    {
        document.getElementById('userInfo').innerHTML = '<p>' + _user.get_address().get_address() + ' is now signed in.</p>';   
    }
}

_user = null;
_signin = null;
</script>
</head>
<body onload="scriptMain()">
    <div id="msgr">
        <table>
            <tr>
                <td style="height:150px">
                    <div id="signinframe">
                    </div>
                </td>
            </tr>
            <tr>
                <td>
                    <div id="userInfo">
                    </div>
                </td>
            </tr>
        </table>


    </div>
</body>
</html>

Overview

Creating the Project Files

Default.htm

Adding the Control Code

Channel.htm

Privacy.htm

Default.css

Default.htm (completed)

See Also

Concepts

Additional resources