Cómo agregar servicios Microsoft a tu aplicación (HTML)
[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente
Aquí puedes aprender a agregar funciones de los servicios Microsoft a tu aplicación de Windows en tiempo de ejecución para permitirle acceder a la información del perfil, los archivos y las fotos de un usuario en su Microsoft OneDrive y a la información de Outlook.com. En los pasos de este tutorial se usa una aplicación vacía como punto de partida y se agregan características para iniciar sesión en la cuenta Microsoft de un usuario y para obtener la información de su perfil para mostrarla en la aplicación.
Importante El tutorial de este tema muestra una aplicación de la Tienda Windows. También puedes agregar servicios Microsoft a una aplicación de la Tienda de Windows Phone. Sin embargo, dado que la interfaz de usuario de Windows Phone no admite controles flotantes, debes usar las páginas en una aplicación de la Tienda de Windows Phone para implementar las funciones que se usan los controles flotantes en este tema.
Lo que debes saber
Tecnologías
Requisitos previos
- Windows 8
- Microsoft Visual Studio
- El SDK de Live
- Cuenta de desarrollador para la Tienda Windows
- Dos archivos de imagen (formato PNG) para usarlos en la aplicación
Instrucciones
Paso 1: Crear un proyecto de aplicación vacía e incluir el SDK de Live
Crea tu nueva aplicación a partir de una plantilla de Visual Studio siguiendo estos pasos:
- Desde Visual Studio, en el menú Archivo, haz clic en Nuevo proyecto...
- En el cuadro de diálogo Nuevo proyecto..., ve a Instaladas > Plantillas > JavaScript > Tienda Windows.
- Selecciona Aplicación vacía.
- Escribe el nombre y la ubicación de tu nueva aplicación y haz clic en Aceptar.
- Compila y prueba la aplicación. Debería iniciarse y mostrar una página vacía en la que solo aparezca "Aquí se debe incluir el contenido". Si ves eso, cierra la aplicación y continúa.
Paso 2: Agregar la aplicación a tu cuenta de desarrollador para la Tienda Windows
Para que tu aplicación use los servicios en la nube a los que accede el SDK de Live, debes registrarla en tu cuenta de desarrollador para la Tienda Windows. No es necesario que envíes tu aplicación a la Tienda Windows para certificarla. Deberás escribir un nombre en tu cuenta de desarrollador para la Tienda Windows.
Paso 3: Agregar los datos de la aplicación y controles flotantes de Configuración
Una aplicación de la Tienda Windows que usa el SDK de Live debe hacer, al menos, estas dos cosas:
- Debe permitir al usuario iniciar sesión en su cuenta Microsoft y cerrarla, si es posible.
- Debe mostrar una política de privacidad que describa el modo en que se protegerán los datos personales a los que accederá la aplicación.
Para obtener más información sobre la experiencia de inicio y cierre de sesión y la política de privacidad, consulta el tema sobre las Requisitos para el inicio de sesión con una cuenta Microsoft.
En una aplicación de la Tienda Windows, puedes acceder a ellas a través de los controles flotantes de Configuración.
Para agregar controles flotantes a tu aplicación, haz lo siguiente:
Crea la página del control flotante Cuenta.
Crea una nueva carpeta para los archivos del control flotante Cuenta. En el Explorador de soluciones, haz clic con el botón secundario en el nombre del proyecto, selecciona Agregar y luego Nueva carpeta.
Cambia el nombre de la carpeta nueva por account.
Haz clic con el botón secundario en la carpeta account, selecciona Agregar y luego Nuevo elemento...
En el cuadro de diálogo Agregar nuevo elemento, ve a Instaladas > JavaScript > Tienda Windows y selecciona Control de página.
En el campo Nombre, escribe "account.html" y haz clic en Agregar.
Modifica los nuevos archivos de tu aplicación.
En el archivo account.html, reemplaza el elemento <div> por este código.
<div id="account" data-win-control="WinJS.UI.SettingsFlyout" data-win-options="{width: 'narrow'}"> <div class="SettingsPane"> <div class="win-label"> <button onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"> </button> <span class="SettingsTitle">Account</span> </div> <article class="SettingsContent"> <p id="accountPrompt"></p> </article> <div> <!-- define one button to sign in and another to sign out, but show only --> <!-- one at a time, depending on whether the user is currently signed in or not. --> <button id="signInBtn" onclick="signInCmd()" style="display: none">Sign in</button> <button id="signOutBtn" onclick="signOutCmd()" style="display: none">Sign out</button> </div> </div> </div>Agrega el siguiente código al final del archivo account.css.
.account p { margin-left: 120px; } .SettingsPane { margin-top:36px; margin-left:48px; } .SettingsTitle { margin-left: 36px; } .SettingsContent { margin-top: 24px; } #account { background-color: gray ; }
Crea la página del control flotante Privacidad.
Crea una nueva carpeta para los archivos del control flotante Privacidad. En el Explorador de soluciones, haz clic con el botón secundario en el nombre del proyecto, selecciona Agregar y luego Nueva carpeta.
Cambia el nombre de la carpeta nueva por privacy.
Haz clic con el botón secundario en la carpeta privacy, selecciona Agregar y luego Nuevo elemento...
En el cuadro de diálogo Agregar nuevo elemento, ve a Instaladas > JavaScript > Tienda Windows y selecciona Control de página.
En el campo Nombre, escribe "privacy.html" y haz clic en Agregar.
Modifica los nuevos archivos de tu aplicación.
En el archivo privacy.html, reemplaza el elemento <div> por este código.
<div id="privacy" data-win-control="WinJS.UI.SettingsFlyout" data-win-options="{width: 'narrow'}"> <div class="SettingsPane"> <div class="win-label"> <button onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"> </button> <span class="SettingsTitle">Privacy</span> </div> <article class="SettingsContent"> <!-- Customize this text to fit your application. --> <h2>How we protect your personal information</h2> <h4>Your privacy statement or a link to your privacy statement goes here.</h4> </article> </div> </div>Asegúrate de cambiar el contenido de privacy.html para que haga referencia a tu declaración de privacidad.
Agrega el siguiente código al final del archivo account.css.
.privacy p { margin-left: 120px; } .SettingsPane { margin-top:36px; margin-left:48px; } .SettingsTitle { margin-left: 36px; } .SettingsContent { margin-top: 24px; } #privacy { background-color: gray ; }
Agrega los comandos de configuración.
En el archivo default.js, agrega este código al controlador de eventos app.onactivated.
// Define the Settings flyout commands. // The commands appear in the Settings charm from top-to-bottom // in the order they are added. app.onsettings = function (e) { e.detail.applicationcommands = { // Add the Account command "account": { // Location of page content href: "/account/account.html", // Command to show in settings menu title: "Account" }, // Add the privacy command. "privacy": { // Location of page content href: "/privacy/privacy.html", // Command to show in settings menu title: "Privacy" } } // Command to update app's settings menu // using the preceding definition. WinJS.UI.SettingsFlyout.populateSettings(e); }Compila y ejecuta tu aplicación.
Abre el acceso a Configuración. Comprueba que los comandos Cuenta y Privacidad aparezcan en el panel Configuración.
Haz clic en cada comando para comprobar que abra un control flotante.
Cuando hayas visto los dos controles flotantes, cierra la aplicación y continúa.
Paso 4: Agregar el contenido de la interfaz de usuario y el enlace de datos
Probablemente querrás que la interfaz de usuario de tu aplicación represente el estado actual de su conexión con la cuenta Microsoft del usuario. En lugar de colocar texto estático en la interfaz de usuario de tu aplicación, usa el enlace de datos para que el contenido de la interfaz de usuario cambie cuando se modifique el valor de datos correspondiente.
En este paso, agregarás código que conecte los datos de tu aplicación con la interfaz de usuario.
Actualiza default.html para incluir los elementos de la interfaz de usuario con los atributos de enlace que conectan la interfaz de usuario con los datos de la aplicación.
Para ello, reemplaza el contenido de la etiqueta <body> en default.html por este código.
<div id="bindingDiv"> <!-- The elements in this div get their data from the app's data object by using a binding object. --> <div class="heading"> <h1> <!-- The app's title. This is configured by the program. --> <span id="titleText" data-win-bind="innerText: person.titleText">person.titleText</span> </h1> </div> <div class="content"> <!-- The app's content. This is a photo for this example. When the user is signed out, one photo is shown; when they are signed in, another is shown. --> <img id="appImage" data-win-bind="src: image.url; title: image.caption" /> <!-- Show the caption as text in the display as well as hover text in the image. --> <p id="appImageCaption" data-win-bind="innerText: image.caption">image.caption</p> </div> </div>En las etiquetas con atributos data-win-bind, el campo de datos que se enlaza a un atributo también aparece en el valor de la etiqueta. Esto se realiza solo para la depuración. Si el enlace se realiza correctamente, los valores de datos del programa reemplazan este texto. Si el enlace no se realiza correctamente, verás el nombre del valor de datos que no se muestra en la interfaz de usuario, lo que puede ayudarte a depurar el error.
Crea el objeto de datos que se usará como objeto de enlace.
Crea un nuevo archivo llamado data.js en la carpeta js de tu proyecto y agrégale código. Para ello, haz lo siguiente:
En el Explorador de soluciones, haz clic con el botón secundario en la carpeta js, selecciona Agregar y luego Nuevo elemento...
Ve a Instaladas > JavaScript > Código y luego selecciona Archivo JavaScript.
En el campo Nombre, escribe "data.js" y luego haz clic en Agregar.
Reemplaza el contenido de data.js por el código de este ejemplo.
(function () { "use strict"; // The global data object used to reference the binding object WinJS.Namespace.define("binding", { Person: null } ); // Static text WinJS.Namespace.define("display", { state: ["Some nice photo", "'s favorite photo"] } ); // The app's data object that is used to map the // sign-in state to the UI. WinJS.Namespace.define("appInfo", { index: 0, // The sign-in state. image: { // The image to show url: "/images/SignedOutImage.png", caption: "Something not so special." }, person: { // The info about the user userName: null, titleText: display.state[0] } } ); })();
Agrega la referencia de este archivo nuevo en default.html escribiendo este código antes de la etiqueta <script> que hace referencia a default.js.
<!-- The app's data definition --> <script src="/js/data.js"></script>Agrega el código para enlazar el objeto de datos con la interfaz de usuario.
En default.js, en el controlador de eventos app.onactivated, agrega este código para crear el objeto de enlace e inicializarlo.
// Create the binding object that connects the appInfo data // to the app's UI. binding.Person = WinJS.Binding.as(appInfo); // Update the binding object so that it reflects the state // of the app and updates the UI to reflect that state. getInfoFromAccount(binding.Person);Agrega un controlador de eventos para actualizar la interfaz de usuario con los datos del objeto de enlace una vez cargado el documento de la aplicación.
En default.js, agrega este controlador de eventos justo antes de la asignación app.oncheckpoint.
app.onloaded = function (args) { // Initialize the UI to match the corresponding data object. var div = document.getElementById("bindingDiv"); WinJS.Binding.processAll(div, appInfo); }Agrega la función que sincronizará los datos de la aplicación con los datos del usuario.
En este paso, esta función solo proporciona datos estáticos para realizar las pruebas necesarias. Las funciones para obtener los datos del usuario de su cuenta Microsoft se agregarán en un paso posterior.
En default.js, agrega esta función después de la función anónima para que aparezca visible en otros módulos de la aplicación.
function getInfoFromAccount(p) { // Test for a parameter and assign the unbound data object // if a parameter wasn't passed. This doesn't refresh the binding // object, but it does keep the data object coherent with the // sign-in state. if (undefined === p) { p = appInfo; } if (0 == p.index) { // The program executes this branch when the user is // not signed in. // Set the data to the signed-out state values // and update the app title. p.person.userName = null; p.person.titleText = display.state[p.index]; // These elements are the default values to show // when the user is not signed in. p.image.url = "/images/SignedOutImage.png"; p.image.caption = "Something not so special."; } if (1 == p.index) { // The program executes this branch when the user is // signed in. // Set the data to the signed-in state, // get the user's first name, and update the app title. p.person.userName = "Bob"; p.person.titleText = p.person.userName + display.state[p.index]; // These elements would normally be read from the user's data, // but in this example, app resources are used. p.image.url = "/images/SignedInImage.png"; p.image.caption = "Something special to me."; } }Agrega los archivos de imagen.
Copia los dos archivos de imagen en la carpeta images de tu proyecto. Cambia el nombre de una imagen a "SignedOutImage.png" y el de la otra a "SignedInImage.png".
En el Explorador de soluciones, haz clic con el botón secundario en la carpeta images y selecciona Agregar > Elemento existente....
Selecciona los dos archivos de imagen que acabas de agregar y haz clic en Agregar.
Compila y prueba la aplicación. Si se muestra el texto correcto y la imagen SignedOutImage.png en la página, continúa al siguiente paso.
Si la aplicación muestra el nombre del campo de datos en lugar del texto, hay un problema con el enlace de datos que tendrás que solucionar antes de continuar.
Paso 5: Actualizar el control flotante Cuenta para usar el objeto de enlace
En account.html, cambia las etiquetas <button> para que aparezcan de este modo, a fin de que el estado de inicio de sesión se use para mostrar el botón correcto en el control flotante.
<button id="signInBtn" onclick="signInCmd(binding.Person)" style="display:none">Sign in</button> <button id="signOutBtn" onclick="signOutCmd(binding.Person)" style="display:none">Sign out</button>En account.js, agrega estas funciones después de la función anónima.
function updateDisplay(p) { // Update the display to show the caption text and button // that apply to the current sign-in state. // Test for a parameter and assign the unbound global data object // if a parameter wasn't passed. This doesn't refresh the screen // but it does keep the data object coherent. if (undefined === p) { p = appInfo; } // Get the elements in the display for this function to update. var prompt = document.getElementById("accountPrompt"); var inBtn = document.getElementById("signInBtn"); var outBtn = document.getElementById("signOutBtn"); // Update the elements to show the correct text and button for the // the sign-in state. if (0 == p.index) { // The user is signed out, so prompt them to sign in. prompt.innerText = "Sign in to see your favorite photo." outBtn.style.display = "none"; inBtn.style.display = "block"; } else { // The user is signed in so welcome them and show the sign-out button. prompt.innerText = "Welcome, " + p.person.userName + "!" inBtn.style.display = "none"; outBtn.style.display = "block"; } } function signInCmd(p) { // Sign the new user in. // This call closes the Flyout and Settings charm. SignInNewUser(p); // Update the display to the signed-in state but keep the Flyout open // in case they want to sign in again. updateDisplay(p); // Return to the Settings flyout. WinJS.UI.SettingsFlyout.show(); } function signOutCmd(p) { // Sign the current user out. SignOutUser(p); // Update the display to the signed-out state but keep the Flyout open // in case they want to sign in again. updateDisplay(p); // Return to the Settings flyout. WinJS.UI.SettingsFlyout.show(); }Luego modifica la función del caso ready de la llamada WinJS.UI.Pages.define para que incluya una llamada a updateDisplay, como en este ejemplo.
ready: function (element, options) { // TODO: Initialize the page here. // Update the Account Flyout to reflect // the user's current sign-in state. updateDisplay(binding.Person); },Agrega a default.js las funciones que inician y cierran la sesión del usuario en su cuenta Microsoft.
Estas funciones aún no interactúan con las funciónes de Servicios de Windows Live—aún. Esto se agregará en un paso posterior. Estas funciones solo te permiten probar el objeto de enlace para asegurarte de que funcione en ambos estados de inicio de sesión y actualice la interfaz de usuario cuando el estado cambie.
function SignInNewUser(p) { // Sign the user in. // Test for a parameter and assign the unbound global data object // if a parameter wasn't passed. This doesn't refresh the screen // but it does keep the data object coherent. if (undefined === p) { p = appInfo; } p.index = 1; getInfoFromAccount(p); } function SignOutUser(p) { // Sign the user out. // Test for a parameter and assign the unbound global data object // if a parameter wasn't passed. This doesn't refresh the screen // but it does keep the data object coherent. if (undefined === p) { p = appInfo; } p.index = 0; getInfoFromAccount(p); }Compila y prueba la aplicación.
Tu aplicación se iniciará y mostrará SignedOutImage.png.
Abre el acceso a Configuración y selecciona el comando Cuenta. Comprueba que aparezcan el botón y el aviso de Iniciar sesión.
Haz clic en el botón Iniciar sesión y comprueba que el estado de la aplicación y el contenido del control flotante Cuenta cambien para reflejar el estado de sesión iniciada.
En el control flotante Cuenta, comprueba que aparezcan el botón y el aviso de Cerrar sesión.
Haz clic en el botón Cerrar sesión y comprueba que el estado de la aplicación y el contenido del control flotante Cuenta cambien para reflejar el estado de sesión cerrada.
Cuando tu aplicación funcione de este modo, estarás listo para agregar las funciones de Servicios de Windows Live.
Paso 6: Agregar las funciones del SDK de Live
Agrega la referencia al SDK de Live a tu aplicación.
En el Explorador de soluciones, haz clic con el botón secundario en Referencias y selecciona Agregar referencia...
Ve a Windows > Extensiones, activa SDK de Live y luego haz clic en Aceptar.
En la etiqueta <head> de default.html, agrega esta línea antes del vínculo default.css.
<!-- The Live SDK --> <script src="///LiveSDKHTML/js/wl.js"></script>
Inicializa el SDK de Live.
En default.js, escribe este código después de la asignación binding.Person en el controlador app.onactivated.
// Initialize the Live SDK. WL.init();Actualiza la función getInfoFromAccount para que tu aplicación obtenga el estado de inicio de sesión del usuario de su cuenta Microsoft.
En default.js, en getInfoFromAccount, reemplaza las dos instrucciones if que prueban p.index con este código.
// Call the user's Microsoft account to get the identity of the current // user. If the user is signed in, the success branch runs. // If the user is not signed in, the failure branch runs. WL.api({ path: "me", method: "GET" }).then( function (response) { // The program executes this branch when the user is // signed in. // Save the app's sign-in state. p.index = 1; // Set the data to the signed-in state, // get the user's first name, and update the app title. p.person.userName = response.first_name; p.person.titleText = p.person.userName + display.state[p.index]; // These elements would normally be read from the user's data, // but in this example, app resources are used. p.image.url = "/images/SignedInImage.png"; p.image.caption = "Something special to me."; }, function (responseFailed) { // The program executes this branch when the user is // not signed in. // Reset the app state. p.index = 0; // Set the data to the signed-out state values // and update the app title. p.person.userName = null; p.person.titleText = display.state[p.index]; // These elements are the default values to show // when the user is not signed in. p.image.url = "/images/SignedOutImage.png"; p.image.caption = "Something not so special."; } );Actualiza la función SignInNewUser para iniciar la sesión del usuario en su cuenta Microsoft.
En default.js, en SignInNewUser, reemplaza el código después de la prueba del parámetro con este código.
// Sign the user in with the minimum scope necessary for the app. WL.login({ scope: ["wl.signin"] }).then(function (response) { getInfoFromAccount(p); });Actualiza la función SignOutUser.
En default.js, en SignOutUser, reemplaza el código después de la prueba del parámetro con este código.
// Sign out and then refresh the app's data object. WL.logout().then(function (response) { getInfoFromAccount(p); });Agrega la función ShowSignOutButton.
Al final de default.js, agrega la función ShowSignOutButton que se muestra aquí.
function ShowSignOutButton() { // Return true or false to indicate whether the user // can sign out of the app. return (WL.canLogout()); }Agrega la prueba para comprobar si el usuario puede cerrar sesión. Si el usuario inicia sesión en su aplicación desde una cuenta de equipo asociada con una cuenta Microsoft, no podrá cerrar sesión en la aplicación. Esta función prueba esta condición para que se muestre al usuario el aviso correcto.
En account.js, en la función updateDisplay, reemplaza la instrucción if por este código. Observa la prueba que se agregó para indicar si se debe mostrar el botón Cerrar sesión.
if (0 == p.index) { // The user is signed out, so prompt them to sign in. prompt.innerText = "Sign in to see your favorite photo." outBtn.style.display = "none"; inBtn.style.display = "block"; } else { // The user is signed in, so welcome them. // If the user can sign out, show them the sign-out button. var promptText = "Welcome, " + p.person.userName + "!"; var signOutBtnStyle = "block"; if (ShowSignOutButton()) { // The user is signed in and can sign out later, // so welcome them and show the sign-out button. signOutBtnStyle = "block"; } else { // The user is signed in and can't sign out later, // so welcome them and hide the sign-out button. promptText = promptText + " The app is signed in through your Windows 8 account." signOutBtnStyle = "none"; } prompt.innerText = promptText; outBtn.style.display = signOutBtnStyle; inBtn.style.display = "none" }Quita el código ficticio que se usó para las pruebas anteriores.
En account.js, en signInCmd, quita las llamadas a updateDisplay y a WinJS.UI.SettingsFlyout.show para que la única línea de código que funcione sea esta.
// Sign the new user in. // This call closes the Flyout and Settings charm. SignInNewUser(p);En account.js, en signOutCmd, quita la llamada a updateDisplay para que las únicas líneas de código que funcionen sean estas.
// Sign the current user out. SignOutUser(p); // Return to the Settings flyout. WinJS.UI.SettingsFlyout.show();
Tu aplicación ahora está lista para probarla con una cuenta Microsoft.
Paso 7: Probar la aplicación
Compila y ejecuta tu aplicación y prueba estas acciones.
Prueba el inicio de sesión en una cuenta Microsoft.
Comienza con una aplicación cuya sesión en la cuenta Microsoft del usuario esté cerrada y realiza estos pasos:
- Abre el control flotante Configuración, selecciona el comando Cuenta y haz clic en Iniciar sesión.
- Inicia sesión con una cuenta Microsoft. Si la aplicación te pide permiso para continuar, haz clic en Sí.
- Comprueba que el texto y la imagen de la aplicación cambien al texto y a la imagen de sesión iniciada.
Prueba el cierre de sesión en la aplicación.
Nota Si pruebas tu aplicación desde una cuenta de equipo asociada con una cuenta Microsoft, el botón Cerrar sesión estará deshabilitado. Este es el comportamiento esperado. Para ejecutar esta prueba, debes ejecutar tu aplicación desde una cuenta de equipo que no esté asociada a una cuenta Microsoft.
Comienza con una aplicación que tenga la sesión iniciada en la cuenta Microsoft del usuario y realiza estos pasos:
- Abre el control flotante Configuración, selecciona el comando Cuenta y haz clic en Cerrar sesión.
- Comprueba que el texto y la imagen de la aplicación cambien al texto y a la imagen de sesión cerrada.
Prueba el inicio de sesión único.
El inicio de sesión único es la característica de Windows que te permite asociar tu cuenta de equipo con tu cuenta Microsoft. Si ejecutas la aplicación desde una cuenta de equipo de este tipo, esta se comportará de un modo distinto del que se describió anteriormente.
Por ejemplo:
- La aplicación podría iniciarse automáticamente en el estado de sesión iniciada.
- El botón Cerrar sesión no aparece en el control flotante Cuenta porque no es posible cerrar sesión en la cuenta desde la aplicación.
- El control flotante Configuración muestra un mensaje adicional que indica que no es posible cerrar sesión desde la aplicación.