Using Microsofts Messenger Connect API

for Effective Social Distribution

At the 2010 Next Web Conference in Amsterdam, Microsoft announced Messenger Connect - a
collection of APIs that enable users to communicate, share and connect with friends on Windows
Live services like Messenger, Hotmail and even Windows Phone 7 mobile phone.

As a launch partner, Gigya worked with Microsoft to showcase a live example of how CBS News
utilizes the Gigya Share plugin with Messenger Connect to let website users share content with
friends on Windows Live. Gigya continues to work closely with Microsoft to make sure site
owners receive the greatest value for interfacing with Messenger Connect.

This developer whitepaper outlines different ways in which site owners can (i) use the Microsoft
Connect API to increase traffic acquisition and (ii) use analytics to measure the effectiveness of
social distribution.

1. Background: Social Updates in Windows Live

2. Writing to Messenger Connect API
3. Using Activity Templates to Increase Traffic Acquisition
4. Measuring the Impact of Messenger Connect
5. Additional Resources

1. Background: Social Updates in Windows Live

Windows Live is an integrated suite of products that help you communicate and share on the PC,
web and mobile phone. Windows Live includes Hotmail, Messenger, SkyDrive, Photo Gallery,
Movie Maker and a number of other great apps and services.

To connect these applications with more personal user experiences, Microsoft built a
comprehensive newsfeed infrastructure called Windows Live Messenger Social Updates. This
activity stream flows throughout Windows Live properties, carrying an index of recent social
activities performed by individuals such as posting a comment, sharing a link, earning a high
score in an online game, etc.

The Windows Live social updates dont just include activities generated within Windows Live.
Users can configure their Windows Live account to bring activities friends have been doing from
across the web. A growing list of over 70 industry leaders like Facebook, LinkedIn, Flickr and

Page 1 of 15
Whitepaper: Using Microsofts Messenger Connect API

YouTube have partnered with Microsoft and are writing activity streams to Windows Live. So
when a Windows Messenger user asks, What are my Facebook friends doing on messenger?
the answer will be right in front of them.

Extensive Reach
Microsoft architected activity streams in Windows Live as a social layer in their technology
stack. As a result, the activity stream is also integrated into products like Outlook, MSN and the
mobile platform Windows Phone 7. This offers site owners a unique and far-reaching pipeline to
an enormous number of users:

500 million people use their windows live accounts for logging in to websites
Connecting to the over 298 million Messenger customers worldwide.
359 million people that use hotmail
Windows Live Messenger climbed to #2 worldwide in total daily active users connecting to
Facebook
iPhone client has been installed millions of times
Windows Live activities flow to the People Hub of the new Windows Phone 7

Windows Phone 7 Windows Live Hotmail

As you can see, the activity stream flows through applications where some of the most
meaningful social interactions are taking place on a daily basis (chat, email, mobile phones, etc).

Page 2 of 15
Whitepaper: Using Microsofts Messenger Connect API

Its hard to understate the value of writing to an activity stream that reaches such a valuable
group of people.

There are three effective ways you can enable users to publish activities from your project or
service to the activity stream. The options ranging from simplest (least amount of time to code)
to most flexible:

1. Badge - a simple HTML tag embedded on your website that users click on to share content
from your site with their Windows Live friends. If youre looking for the quickest way to
publish, this is probably it.
2. Activity Feed - if your application has an RSS, atom or activity stream feed, users can
configure Windows Live to poll their activity stream feed from your feed service.
3. REST & JavaScript APIs Messenger Connect contains both javascript and REST interfaces
for writing activities to Windows Live.

Our focus for this paper will be using the Messenger Connect javascript and REST APIs.

2. Writing Activities Using Messenger Connect

One of the advantages to Messenger Connect is that it doesnt require a long list of prerequisites
before starting to code. Microsoft has a terrific developers guide on MSDN which provides all
details needed for getting started with the API, including how to register and configure your
application, API libraries for handling OAuth WRAP exchanges, etc:

Messenger Connect Developers Guide

http://msdn.microsoft.com/en-us/library/gg251990.aspx

The following summarizes the key points of writing Messenger social updates to Windows Live.

First, Lets Trust Each Other

Your application is publishing Messenger social updates to Windows Live on behalf of the user.
So before doing anything, we need to first authenticate the user to ensure privacy and security.
This is a required step whether youre writing activities using javascript or calling REST
endpoints. The authentication process accomplishes four things:

1. Establishes a valid Windows Live user with an active session

2. Allows the user to grant permission to your application for writing activities
3. Returns back an OAuth access token needed for calling API endpoints
4. Identifies your application to Windows Live as a trusted, verified application

Page 3 of 15
Whitepaper: Using Microsofts Messenger Connect API

Messenger Connect makes it easy for users to sign in by using their Windows Live ID. While
there are several ways to implement authentication on your site, the simplest way is by
embedding the JavaScript UI Sign In control <wl:signin>. Heres a quick example demonstrated
how a simple authentication screen can be implemented:

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

<head>
<title>SignIn Example</title>
<script type="text/javascript" src="http://js.live.net/4.0/loader.js"></script>
<script type="text/javascript">
function appLoaded(appLoadedEventArgs) {
}
function signInCallback(signInCompletedEventArgs) {
if (signInCompletedEventArgs.get_resultCode() ===Microsoft.Live.AsyncResultCode.success) {
alert('Sign-in successful.');
}
else {
alert('Sign-in failed.');
}
}
</script>
</head>
<body>
<wl:app channel-url="http://<Your-Domain>/channel.html"
callback-url="http://<Your-Domain>/OAuthWrapCallback.axd"
client-id="<Your-Client-Id>"
scope="WL_Profiles.View"
onload="{{appLoaded}}">
</wl:app>
<wl:signin
id="signInControl"
signedintext="Click to sign out."
signedouttext="Login with Messenger"
onsignin="{{signInCallback}}" />
</body>
</html>

The <wl:signin> control causes a Messenger Connect login button to be rendered on the page.

When a user clicks this button, underlying JavaScript API calls initiate the Windows Live ID sign-
in process by opening a new browser window:

Page 4 of 15
Whitepaper: Using Microsofts Messenger Connect API

If the user successfully authenticates and grants permissions to your application, an access
token will be available for sending your request to the Messenger Connect endpoint.

If you choose to invoke the JavaScript API declaratively by using controls like <wl:signin>, youll
need to include the <wl:app> tag which provides metadata that identifies your application to
Windows Live Services. For a complete rundown on each <wl:app> tag property plus , please go to
Adding a Sign-in Page on MSDN.

Writing an Activity
Once youve authenticated, the process of writing Messenger social updates to Windows Live
boils down to (i) formatting your activity and (ii) sending it to a Messenger Connect API
endpoint.

STEP 1 Choose an Activity Template

Windows Live uses an emerging standard called Activity Streams for pulling and syndicating social
activities across the web. According to the specification, each activity follows the same basic
pattern:

[actor] [verb] [object] [target]

Even if youre unfamiliar with Activity Streams, youre probably familiar with the output on
feeds anywhere from Facebook to LinkedIn:

CHRIS bought Architecting Applications at Amazon

SARAH updated her resume at LinkedIn
CHRIS listened to Theme from Jaws by John Williams on Pandora
CARLOS favorited this photo on Flickr.
SANDY bought The Matrix at Amazon.com

Page 5 of 15
Whitepaper: Using Microsofts Messenger Connect API

While there are potentially hundreds of [verb] + [object] combinations, Windows Live supports
a growing number of the most common combinations in a format they call Activity Templates.
There are many different types of activity templates (e.g. pictures, comments, links,
boookmarks) and as well see later in this paper, they can be important for increasing traffic
acquisition.

STEP 2 - Send to a Microsoft Connect API endpoint

Exactly how you package these activity template payloads is dependent on the manner in which
youll be sending it to Messenger Connect API. Microsoft Connect provides both javascript and
REST interfaces.

USING JAVASCRIPT

In javascript, activity templates take the form of derived classes from the
Microsoft.Live.Services.Activity class. For this reason, you can choose the activity template simply
by using the constructor such as AddBookmarkActivity and MarkFavoriteActivity. The following
example demonstrates how to enable authenticated users to add a status update to their activity
stream using the StatusActivityObject and Add classes:
function addStatusActivity() {
if (myActivitiesCollection) {
var statusActivityObject = new Microsoft.Live.Services.StatusActivityObject();
statusActivityObject.set_content(I am testing Messenger Connect);
var addStatusActivity = new Microsoft.Live.Services.AddStatusActivity(
[statusActivityObject],
'http://www.contoso.com/appLink');
if (addStatusActivity.validateParams([statusActivityObject], 'http://www.contoso.com/appLink')) {
myActivitiesCollection.add(addStatusActivity);
myActivitiesCollection.save(operationCompleted);
}
}
}

This simple example shows how the authenticated user (John Smith) publishes a status update
to Windows Live using your application. Heres how it would look:

USING REST

When sending to REST endpoints, your application is making an HTTP POST with the body of
your requests containing the user's activity template in a standard format (Atom, RSS, or JSON).
This simple example shows how the authenticated user (John Smith) publishes a game

Page 6 of 15
Whitepaper: Using Microsofts Messenger Connect API

achievement to Windows Live using your application. It uses the following JSON activity
template payload:

{
"__type": "SaveAchievementActivity:http://schemas.microsoft.com/ado/2007/08/dataservices",
"ActivityVerb": "http://activitystrea.ms/schema/1.0/save",
"ApplicationLink": "http://www.contoso.com",
"ActivityObjects": [
{
"ActivityObjectType": "http://activitystrea.ms/schema/1.0/achievement",
v"Title": "Old School",
"Summary": "Experienced the original, classic adventure game, as it was in the early 90s."
}
],
"ActivityTarget":
{
"ActivityObjectType": "http://activitystrea.ms/schema/1.0/achievement",
"Title": "The Secret of Monkey Island: Special Edition",
"AlternateLink": "http://www.contoso.com/link_to_content",
"PreviewLink": "http://www.contoso.com/thumbnail.jpg"
}
}

Here is how it would look on Windows Live:

Writing activities by means of the REST API requires acquiring an OAuth WRAP access token.
For a complete overview of how OAUTH WRAP and making REST calls to Messenger Connect,
please read Using the REST API Service on MSDN.

Note About Gigya Share

If youre using the Gigya Share plugin or socialize.publishUserAction method, Gigya is essentially
publishing activities to the Messenger Connect API on behalf of your application. In doing so,
Gigya automatically selects the most appropriate activity template based on your supplied
parameters. For instance, a user (John Smith) comes to sports news website (Bay News) and
wishes to share an article on Windows Live. The photo caption is already set (Lincecum comes
through) so John simply fills in his comments (Im so Excited!)

Page 7 of 15
Whitepaper: Using Microsofts Messenger Connect API

The following represents the social update published on Windows Live:

Gigyas socialize.publishUserAction method is supported in the Gigya REST API allowing

developers to publish activities directly from the server.

3. Using Activity Templates to Increase Traffic Acquisition

When writing Messenger social updates, site owners are like real-estate agents working on
behalf of the user. Both parties have a mutual interest in selling the activity in a way that
recipients (friends, colleagues, etc) will be interested enough to take some action such as
clicking through a link, beginning a chat session, sending an email, etc.

For developers and site owners, one of the best ways to increase sales (i.e., traffic acquisition)
is to make efficient use of Windows Live Activity Templates. Since weve already described
activity templates above, lets take a look at how they can potentially play a part in traffic
acquisition.

Enhanced User Experience

From a user interface perspective, knowing which activity template will appear best in Windows
Live is an important first step in getting clickthroughs to your site. Microsoft recently created a
great online utility called ActivityStrea.ms Template Selection Tool which helps you (i) select the most
appropriate activity template, (ii) view the RSS, ATOM and JSON markup and (iii) see how it is
going to be rendered in Windows Live. Making sure the activity you post on a users behalf is
visually effective is a simple step that sometimes gets overlooked.

Heres a quick example. Say your site allows users to post a video to their Windows Live stream.
If you choose to use the custom activity template when packaging a REST payload, heres how
it would probably look:

Page 8 of 15
Whitepaper: Using Microsofts Messenger Connect API

Compare that to using the video activity template:

Friends may be more inclined to click through the second example because theyll identify the
link as a video due to the cinematic style that automatically gets added by using the Video
activity template.

Weighted Relevance in Windows Live

No matter where the activity stream is ultimately viewed (Windows Phone 7, Messenger,
Hotmail, etc.), Microsoft prioritizes updates from the people who matter most to the user and
favor the most interesting things their friends are doing. Social updates written using activity
templates are given more weight/relevance in aggregated lists throughout Windows Live, so
activities that include photos, videos, and the updates receiving significant clickthroughs will
generally rise to the top.

For example, posting a video using AddVideoActivity javascript class will likely show up higher in
Windows Live, opposed to activities written using only the Microsoft.Live.Services.Activity class.
So make it a point to use activity templates wherever possible to give your social updates a
chance at making it to the top of a users stream.

Smart Aggregation

Another benefit to using activity templates is that their ATOM, RSS or JSON formats provide
structure for your social updates. This means that each activity will have properties like
activityType which can be used as a filter for smart aggregation scenarios. For example, if an
application pulls a collection of users activity stream, filters can be easily coded that:

Page 9 of 15
Whitepaper: Using Microsofts Messenger Connect API

Display all of a user's contacts who recently started a new garden in FarmVille.
Create a Since Graduation photo album that includes a timeline and photos of what a
user's contacts have been doing since graduation.
List of all the movies a users Facebook, MySpace and Windows Live friends have
commented on

Nearly every activity surfaced in these smart aggregation scenarios will have a link back to your
application or website. So making smart use of activity templates can lead to traffic acquisition
now and in the future.

NOTE: There are several restrictions to what applications can pull from a users activity
stream. For example, Company X can read social updates from activities that happened in
Windows Live or Zune (according that users privacy settings). However, Company X
cannot read the activities that Company Y wrote to the Windows Live activity feed. Please
read more about Messenger Connect scopes in Working with Activities (JavaScript Library).

4. Measuring the Impact of Messenger Connect

Encouraging social participation within applications is quickly becoming the norm. But how do
you know its actually creating value for your application or site? How can you measure the
impact of all this social integration? Precise analytics will not only help your site determine
which features are popular, but also help decide which features to kill because theyre NOT
working.

Here are a few strategies for measuring the impact of Messenger Connect:

Messenger Connect Analytics

DIY (Do It Yourself)
Gigya Analytics Module
Google Analytics

Messenger Connect Analytics

The analytics component in Messenger Connect provides standard report information like
number of users (including demographics) as well as the types of API calls they are making. You
can download data to a CSV file for up to 1,500 rows of data for any one-hour period. So if youre
looking for basic usage statistics, the Messenger Connect analytics page is a great place to start:

Page 10 of 15
Whitepaper: Using Microsofts Messenger Connect API

DIY Method (Do It Yourself)

If you want to go down the DIY route and measure the impact yourself, here are a few
recommendations.

Track the # of clicks on share

Measuring the # of clicks from shares tells you how many users wanted to share the content,
independent of how many users actually click back from Messenger. This indicates the level of
interest in the content.

When the user clicks the share button, this should trigger an event which the partner captures in
their own analytics database (can be done with JavaScript). Alternatively, they could do
something like redirect through another page which captures analytics (pop a window to
http://example.com/share?type=messenger&url=http://example.com).

Track the # of views in Messenger/Windows Live

Depending on your goals, driving impressions inside Windows Live may be important and worth
measuring. When images appear in Windows Live they are served directly from your website.
You can measure the number of impressions by either QueryString parameters (recommended)
or detecting the User Agent on the request.

Page 11 of 15
Whitepaper: Using Microsofts Messenger Connect API

QueryString Parameter Detection (recommended)

When passing through parameters for thumbnail images, just add a QueryString of
ref=Messenger (or whatever). When the image is rendered in any Windows Live property, that
parameter will be sent back to the image source.

Images are served directly from your website. You can add the querystring parameter to this
image URL.

User Agent Detection

The Windows Live Messenger client serves up requests with the User Agent header set to
Messenger Client 15. The problem with relying on this user agent, is that if the image is served
from other properties such as Hotmail or profile.live.com or Windows Phone/iPhone, those
requests wont be counted.

Page 12 of 15
Whitepaper: Using Microsofts Messenger Connect API

Gigya Analytics Module

If youre using Gigya, an analytics module tracks all social interaction and traffic data passing to
Messenger Connect. Reports are available through an administrative webpage on the Gigya
website, while a subset of these reports is available via the reports.getSocializeStats method in
the Gigya API.

Referrals & Clickthrough Rates

A particularly useful the report entitled Referred Traffic by Provider will return statistics on
the number of time users came to your site from supported platforms such as Messenger
Connect. Each report (i) can be viewed in a number of formats, (ii) are easily exported and (iii)
can be filtered by a number of properties such as date range and demographics.

Reports can be used in conjunction to measure the effectiveness of activities sent to Messenger
Connect. One such approach is to establish a Clickthrough Rate (CTR) by dividing Referral
Traffic sent to your site from Messenger Connect by the total Number of Messages sent to
Messenger Connect:

Referral Traffic from

Messenger Connect
Clickthrough Rate =
Number of Shares sent
to Messenger Connect

To gather more precise data, developers can utilize the Context ID (cid) field found in Gigyas
Conf object. The cid is an optional, user-defined string associated with every transaction sent to
Gigya and is available on analytic reports. This field is particularly useful because it allows
developers to associate report information with their own internal data. A Context ID combo box
in the report page view lets you filter the report data by site/application context.

Using the clickthrough rate concept, some compelling measurements can be realized with
regards to Messenger Connect. For example, by mapping each activity template to some internal
key, you can measure things like:

clickthrough rate of using the AddComment template in males 18-34

clickthrough rate of AddPhoto template when using a small thumbnail vs. large
which type of user content receives the most ShareLink posts and clickthroughs

Google Analytics

If you already use Google Analytics for tracking statistics on your site, it makes perfect sense to
extend that implementation to track the performance of your Messenger Connect
implementation. Weve generated some of the URL parameters which can be appended to any
links to your site on Windows Live which may result in a user landing on your site (note: this
doesnt include image embeds).

Page 13 of 15
Whitepaper: Using Microsofts Messenger Connect API

Social distribution is a feature of your website, but because it helps generate user acquisition
and also user re-engagement, you should think of it as a campaign. You can make the campaign
more aggressive by placing the ads (i.e. the functionality) on your site in more prominent
positions. Well utilize some of Google Analytics functionality for campaign tracking by using page
tagging which is the process of adding URL parameters (e.g. ?utm_source=messenger). For more
information on tagging see this article.

The dimensions well use are:

Campaign = Social and Sharing

Source = Messenger / Hotmail / Facebook / Sharing
Medium = Newsfeed / IM / Email
Content we will utilize this for additional information such as Badge or Activity Pull or
Activity Push (sub details of the medium)
Term = we wont use this field as it may skew your search keyword traffic reporting

These parameters should be added to your URL for example:

http://www.anguslogan.com/?utm_source=WL&utm_medium=Social&utm_campaign=Sharing%2Band%2BSo
cial

You should measure all social as one campaign Sharing and Social no matter which service
provider (e.g. Windows Live, Facebook, Twitter, etc.) you are working with. Below are some
recommendations for how you can measure Windows Live specific properties.

Write Mode Surfaces in Medium Content Example Notes

Write to activities Messenger Client Newsfeed Feed Example Combine with thumbnail query string parameters to track the
(push or pull) / Hotmail / Profile impressions on WL
/ WP7 / iPhone
Sharing badge & Messenger Client Newsfeed Status Example Combine with thumbnail query string parameters to track the
companion / Hotmail / Profile impressions on WL
/ WP7 / iPhone
plus Facebook / Generate the URL for the sharing badge using JavaScript to
LinkedIn / inject these parameters in realtime.
MySpace (if
connected)

When the user doing the sharing selects the Sharing badge,
you should track a JavaScript event, so you can see how many
shares are occurring.
Send email Hotmail Email Hotmail Example When emailing an @live.com or @hotmail.com or any other
Hotmail namespace, add the
Send IM Messenger end IM IM Example If sending the URL via instant messaging, it is recommended to
points use a short URL such as bit.ly

NOTE: The Google Analytics URL parameter values are case sensitive, it is best to keep them
lowercase to reduce the chase of errors.

For additional information see the Google Analytics URL builder. To track JavaScript events such as
clicking on the share button or the connect button, use the trackPageview function.

Page 14 of 15
Whitepaper: Using Microsofts Messenger Connect API

5. Additional Resources
ActivityStreams Template Selection Tool
http://messengerconnectactivities.mslivelabs.com/

Windows Live Development Center

http://msdn.microsoft.com/en-us/windowslive/default.aspx

Windows Live Application Management

https://manage.dev.live.com

Messenger Connect Controls Playground

http://isdk.dev.live.com/ControlsPlayground.aspx#controlId=signincontrol

Windows Live REST Explorer

http://rex.mslivelabs.com/

Windows Live API Playground

http://isdk.dev.live.com/ApiPlayground.aspx

Blogpost: Windows Live and Activity Streams

http://windowsteamblog.com/windows_live/b/developer/archive/2010/08/25/windows-live-and-activity-
streams.aspx

Blogpost: Windows Phone People Hub Powered by Activity Streams

http://windowsteamblog.com/windows_live/b/developer/archive/2010/10/11/windows-phone-people-hub-
powered-by-activity-streams.aspx

Gigya Online Documentation

http://wiki.gigya.com/

Page 15 of 15