[Update on 12/27/2012] If you’re looking for the starter guide for Live SDK on Windows Phone 8, please refer to this post. If you’re looking for the starter guide for Live SDK on Windows 8 or Asp.Net, please refer to this post.
[Update on 4/17/2012] We now have an iOS SDK and an Android SDK as well. Check it out! The 5.1 release is now live on Live Connect Developer Center. This release fixes some known issues with the 5.0 release. It also include a version of the SDK for Windows 8 that’s compatible with the Windows 8 Consumer Preview.
A few words on the behind the scene stuff before I start the step-by-step guide. When building Metro style apps on Windows 8 Consumer Preview, Single-Sign-On (SSO) is achieved with support from the OS. On Windows Phone, however, such support is not available for third party apps. To provide a good sign-in experience on mobile devices, Live Connect allows a mobile client to obtain a refresh token and use it to exchange for an access token. This provides a way for mobile clients to implement a Sign-In-Once experience and avoid the need to ask user for password every time the app is activated. To opt-in for this experience, your app needs to satisfy two criteria:
- The app must be provisioned as a mobile app.
- User must grant the app offline access permission.
We will discuss the details on how to meet these two criteria in the following step-by-step guide.
- Download and install the latest Windows Phone Developer Tools from App Hub.
- Download and install Live SDK.
Let’s start by creating a new Windows Phone application.
1. Create a new HelloWorldPhone Windows Phone application in Microsoft Visual Studio 2010 or Microsoft Visual Studio 2010 Express for Windows Phone using the Visual C# -> Silverlight for Windows Phone -> Windows Phone Application project template.
2. Bring up the Add Reference dialog and go to the .Net tab. Scroll down to find the Microsoft.Live and Microsoft.Live.Controls assemblies. Add them to your project.
3. Open MainPage.xaml in the designer. Bring the Toolbox in view and right-click to select Choose Items… Under Windows Phone Components tab, find the SignInButton control in the Microsoft.Live.Control namespace and add to your toolbox (You only need to do this once).
The SignInButton control should now show up in your toolbox.
4. Drag the SignInButton onto your designer surface. In your xaml file, change the generated xml for the SignInButton to the following:
<my:SignInButton Name="btnLogin" HorizontalAlignment="Left" Scopes="wl.signin wl.basic wl.offline_access"
5. Add a couple TextBlock elements to display the greeting and the error message (in case something goes wrong). Here’s the complete xaml for MainPage.xaml.
6. Add the following code in your MainPage.xaml.cs file.
Before proceeding, let’s take a look at what the above code does.
- The xaml definition of the SignInButton control specifies the scopes that the app needs to ask user permissions for. We’re including 3 scopes here: wl.sign, wl.basic and wl.offline_access. Together these 3 scopes give the app access to user’s basic profile information and allows the app to access data even when the user is not actively using the app. For more information on Live Connect scopes, read here. In addition, the documentation you can download from the Live SDK download site includes updated information on this release.
- The xaml definition also adds an event handler for the SessionChanged event on the SignInButton. This event is fired when the sign-in process has finished.
- If access is granted and the LiveConnectSession object indicates the LiveConnectSessionStatus as Connected, a new instance of the LiveConnectClient class is created with the current Session object.
- In the function GetMe(), the code talks to the Live Connect REST API to retrieve user’s basic profile information by calling LiveConnectClient.GetAsync on “me”.
- When the result comes back, the GetCompleted event on LiveConnectClient is fired, the app can then obtain user’s first and last names through the e.Result IDictionary object.
8. After you click “I accept”, an application is created for you with a client id and a client secret (values removed for discretion).
9. Go to Application Settings Page and click on the API Settings tab. Check “Yes” for “Mobile client app” and save.
10. The app is now provisioned and ready to go. Go back to your MainPage.xaml, and add the ClientId property on the SignInButton.
<my:SignInButton Name="btnLogin" ClientId="[Your Client ID here]" HorizontalAlignment="Left" SessionChanged="btnLogin_SessionChanged" Scopes="wl.signin wl.basic wl.offline_access" />
11. You’re done. Hit F5 and run the app in the emulator. Click the “Sign In” button and type in a username and password to sign into Windows Live. Next you will see a screen asking user permission to access data.
13. Click Yes. Notice that the SignInButton has changed to “Sign Out” state and a greetings with your name is displayed.
14. At this point, the app can continue to access user data until user signs out or until the refresh token is expired. A refresh token is valid for one year and is reset every time a new access token is issued. The user will not be asked for credentials again as long as the app is activated at least once a year.
For more Live Connect code samples, visit our github site at https://github.com/liveservices/livesdk.