Using the JavaScript library

This topic covers the basic tasks involved in using the Live SDK JavaScript library in web apps and Windows Store apps using JavaScript.

Referencing the JavaScript library in a web app

To use the Live SDK JavaScript APIs with a web-based app, you must load the JavaScript library (wl.js) by adding a reference in your code to the location of the latest version of the library file. The default locale of wl.js is English. The following is an example of how to reference the JavaScript library in a standard web-based app.

<script src="//js.live.net/v5.0/wl.js"></script>

Referencing the JavaScript library in a Windows Store app using JavaScript

To reference the Live SDK JavaScript APIs from a Microsoft Visual Studio project, do this:

  1. Install the Live SDK, if you have not already done so.

  2. In your project, in Solution Explorer, right-click References > Add Reference.

  3. Click Windows > Extension SDKs > Live SDK for Windows Store app.

  4. Click Add, and then click Close.

Enabling Microsoft IntelliSense

To enable Microsoft IntelliSense in an HTML file, do this:

  1. Add this <script> element in the <head> element.

    <script src="///LiveSDKHTML/js/wl.js"></script>
    
  2. Create a new file named default.js.

  3. Add this comment to the top of the default.js file.

    /// <reference path="///LiveSDKHTML/js/wl.js" />
    

    Note

    In Visual Studio, you can drag wl.js from the solution explorer and drop it onto default.js to add this reference.

Loading the debug version

If you need to debug the JavaScript API, you can reference an uncompressed version of the library file, named wl.debug.js. Use the following code to reference the debugging version in a web app.

<script src="//js.live.net/v5.0/wl.debug.js"></script>

If you are creating a Windows Store app using JavaScript, the solution configuration that is selected in Visual Studio, for example, debug or release, determines which version of wl.js will be loaded.

International support

For Windows Store apps using JavaScript, the locale for the current app session defaults to use the settings of the user's local computer. However, the developer may override the locale setting programmatically, as shown in the following example.

...
var ns = Windows.ApplicationModel.Resources.Core;
var rm = ns.ResourceManager;
var context = rm.current.defaultContext;
context.language = "fr";
...

Note

Setting the locale must be done before calling WL.init.

To set the locale for a web app, you must load a localized version of the JavaScript library by adding to the URL a segment that specifies the culture name string for the localized version that you want. Insert this segment immediately after the version number segment. For example, to load the Japanese version of the JavaScript library, you might use the following code.

<script src="//js.live.net/v5.0/ja/wl.js"></script>

For a complete list of localized versions, see Supported locales.

Live SDK authentication cookies

The JavaScript library uses a session cookie, wl_auth, to track and transmit OAuth authentication data as the user signs in to her Microsoft account. For more info about OAuth authentication, see OAuth 2.0.

When the JavaScript library is loaded as part of the OAuth redirect Uniform Resource Identifier (URI), it sets this cookie automatically. When it is loaded as part of a typical page, the library polls the cookie to determine when the sign-in state of the user changes.

The following table lists the data that is stored in subkeys in the wl_auth cookie.

Subkey

Data

access_token

The OAuth access token.

authentication_token

The authentication token.

error

The OAuth error, if one occurred.

error_description

The description of the OAuth error, if one occurred.

expires_in

The time remaining, in seconds, until the OAuth access token expires, if the token was provided.

scope

The OAuth scope value, if it was provided.

Note

The wl_auth cookie is stored in the domain as the domain of your redirect URL. Cookies are applicable only to web apps. Developers of Windows Store apps using JavaScript will have no need to interact with cookies.

In general, you do not have to handle the wl_auth cookie directly; the JavaScript library handles it for you. However, if your callback page processes the user s authentication token through server-side code, such as with the wl.offline_access scope, your code is responsible for updating the cookie according to the following rules:

  • If the app successfully retrieves the authentication token, it must write the access_token, scope, and expires_in subkeys in the cookie that was received.

  • If an error is received from the authentication server, the app must write two subkeys: error and error_description. The value of the error subkey must be "access_denied". The value of the error_description subkey must be "Failed to retrieve user access token".

  • The callback page must load wl.js.

In all cases, your app must not overwrite any existing subkeys.