Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Working with Activities (JavaScript Library)

Ff748295.note(en-us,MSDN.10).gifNote:
Current information about Live Connect is now available in the Windows Live Developer Center. The information in the following sections is provided for legacy purposes only.

A key part of the Windows Live Messenger Connect experience is communication and sharing. Sharing functionality is enabled by Messenger Social, also known as a newsfeed. A newsfeed is a list of your activities and those of your contacts—activities such as commenting on a photo, changing your personal status message, or becoming friends with someone. There are two activity types in Messenger Connect: user activities and contact activities. User activities are the activities of the authenticated user. Contact activities are the activities of the authenticated user's contacts in the current application or webpage to which the user is signed in, along with contact activities created by Windows Live that are public according that contact’s privacy settings. Activities created by other applications are not part of the fetched collection.

Viewing user activities and contact activities requires the wl_Activities_View scope. Adding activities using the Messenger Connect API requires the wl_Activities_Update scope.

Activities in Messenger Connect follow the Activity Streams specification. An activity in Activity Streams can be described by using [Actor][Verb][Object][Target] notation. For example, in the activity "John added party.jpg to Vacation Album", "John" is the actor, "added" is the verb, "party.jpg" is the object, and "Vacation Album" is the target. In this section, you will learn about viewing and creating activities by using the Messenger Connect library, which provides properties that map to the Activity Streams concepts of [Actor], [Verb], [Object], and [Target]. For more information, see Activities Resource.

To create an activity by using the Messenger Connect API, you use activity templates, which use the Activity Streams format and provide categories of activity updates that users of your website are likely to want to do. The Activity Streams templates assist you by providing structure for activity updates. In general, initializing a new instance of a template creates an activity that is ready to be used. The benefit of using activity templates is that each activity has an activityType property that can be used to aggregate activities and enable smart aggregation scenarios, such as displaying all of a user's contacts who played a particular game recently.

In the Microsoft.Live.Services namespace in the Messenger Connect Library, there are two key groups of classes that you work with when constructing activities. The Activity template classes, such as Microsoft.Live.Services.AddCommentActivity, derive from the Activity class, which in turn derives from the LiveItem class. LiveItem provides a wrapper around resources to simplify development.

The second group of classes is the Activity Object classes, such as Microsoft.Live.Services.CommentActivityObject. They derive from the DataItem class and are reflections of Windows Live data.

To work with activity templates, follow these general steps:

  1. Choose a template that represents your activity. (A table of templates is provided later in this topic.)
  2. Create the activity by specifying the constructor method of the template class.
  3. Set additional properties as needed.
  4. Add the activity to the current activity collection and then save the collection.

To request an activity collection from the application's data context, request data for the Microsoft.Live.DataType.myActivities data type or the Microsoft.Live.DataType.contactsActivities data type. For an overview of data context usage, see Using the Data Context.

The activity templates are designed so that you can provide the essential information about the activity by using the constructor. You use the templates in a two-step process. First, you construct the supporting activity object (for example, Microsoft.Live.Services.StatusActivityObject). Then, you use the activity object in the constructor of the activity template (for example, Microsoft.Live.Services.AddStatusActivity).

As an example, the following sample demonstrates how to add a status activity. The example assumes that the page contains a TEXTBOX element named "txtActivity" that provides customized text for the status activity, and that there already is a data context and an in-memory activities collection.

function addStatusActivity() {
    if (myActivitiesCollection) {
        var statusActivityObject = new Microsoft.Live.Services.StatusActivityObject('Status activity text.');
        statusActivityObject.set_content($get('txtActivity').value + "  " + new Date());

        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);
        }
    }
}

The applicationLink parameter that appears in constructors is the application URI that will be associated with the activity; for example, http://www.contoso.com/.

The following table lists the available activity templates.

Activity template Constructor parameters

AddArticleActivity

Article [], applicationLink

AddBookmarkActivity

Bookmark [], applicationLink

AddCommentActivity

Comment [], applicationLink

AddPhotoActivity

Photo [], PhotoAlbumActivityObject, applicationLink

AddProductActivity

ProductActivityObject [], applicationLink

AddReviewActivity

ReviewActivityObject [], applicationLink

AddStatusActivity

StatusActivityObject [], applicationLink

AddVideoActivity

VideoActivityObject [], applicationLink

CustomActivity

CustomActivity [], CustomActivityObject, applicationLink, verb

DefeatUserActivity

UserActivityObject [], GameActivityObject, applicationLink

MarkFavoriteActivity

ProductActivityObject [], applicationLink

PlayVideoActivity

VideoActivityObject [], applicationLink

RateProductActivity

ProductActivityObject [], applicationLink

SaveAchievementActivity

AchievementActivityObject [], GameActivityObject, applicationLink

SaveHighScoreActivity

HighScore [], GameActivityObject, applicationLink

SaveProductActivity

ProductActivityObject [], ListActivityObject, applicationLink

TagPersonActivity

UserActivityObject [], ActivityObject, applicationLink

Some activity template constructors have activityTarget parameters that are required to fully specify the template. For example, the AddPhotoActivity template requires you to specify the following:

  • A PhotoActivityObject object, which is an array of photo objects.
  • A PhotoAlbumActivityObject object, which is the target of the photo activity or the album that contains the photos.
  • An applicationLink argument, which specifies a link to the application (registered with Windows Live) that is posting the activity.

The AddPhotoActivity, CustomActivity, DefeatUserActivity, SaveAchievementActivity, SaveHighScoreActivity, SaveProductActivity, and TagPersonActivity constructors take an activityTarget argument.

The following sections discuss additional points to consider when you work with activities under certain circumstances.

Large Activity Collections

When you request user activities or contact activities for an authenticated user, keep the following in mind:

  • The Windows Live endpoint will return up to 100 activities. If you use the loadAll method of the DataContext class once and there are more than 100 activities, you will not receive all of the activities.
  • For large activity collections, use a recursive load approach as shown in Working with Large Contact Collections.
  • Whenever possible, load only what you need. You can use the load method of the DataContext class to specify filter arguments to reduce is the results that are returned.
  • Consider using a view of activities. A view provides paging and filtering functions and takes care of the requests for more data as the user pages through activities. For an example of how to use a view, see Enumerating Contacts by Using a View.
  • Use the activityType property or applicationName property to refine what is displayed.

Activity Times

When you fetch an activity collection from Windows Live, the activities are returned in reverse chronological order with the most recent activity at the start of the collection.

There is no expiration date for an activity. For example, if the activities are requested for a user, and the user's last activity was six months ago, this activity would be the first activity in the returned collection.

Activity Duplicates

If two activities are duplicates of each other, adding the second activity will cause an error. The determination of whether two activities are duplicates depends on the activity type. The following table explains the logic for determining duplicates.

Activity type Activity property used for duplicate determination

Adding a photo to an album

Thumbnail

Adding a photo

Thumbnail

Adding a video

Thumbnail

Playing a video

Thumbnail

Adding an article

Summary

Updating a status

Summary

Sharing an item

Summary

Posting an item

Summary

Custom activity

Summary

Listing User Activities

Enumerate an authenticated user's activities.

Listing Contact Activities

Enumerate user contact activities.

Displaying Details for Activities

List details of an authenticated user's activities.

Creating an Activity and Posting it to Your Activity Stream

Enable authenticated users to post messages to their activity streams.

Organizing Activities by Activity Type

Organize a list of activities that are displayed on a webpage.

Show:
© 2014 Microsoft. All rights reserved.