Partilhar via

Como adicionar serviços Microsoft ao seu aplicativo (HTML)

  • Artigo

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Aqui você descobre como adicionar recursos dos serviços Microsoft a seu aplicativo do Tempo de Execução do Windows para que ele possa acessar as informações de perfil, os arquivos e as fotos do usuário no Microsoft OneDrive, além de informações do Outlook.com. As etapas deste tutorial começam comum aplicativo vazio e adicionam os recursos de entrada à conta da Microsoft de um usuário, além de obter as informações do perfil do usuário para exibição no aplicativo.

Importante  O tutorial deste tópico demonstra um aplicativo da Windows Store. Você também pode adicionar serviços da Microsoft a um aplicativo da Loja do Windows Phone. No entanto, uma vez que a interface do usuário do Windows Phone não dá suporte a submenus, você precisa usar as páginas em um aplicativo da Loja do Windows Phone para implementar os recursos para os quais submenus são usados neste tópico.

 

O que você precisa saber

Tecnologias

Pré-requisitos

  • Windows 8
  • Microsoft Visual Studio
  • O Live SDK
  • Uma conta de desenvolvedor da Windows Store
  • Dois arquivos de imagem (formato PNG) para utilização no aplicativo

Instruções

Etapa 1: Crie um projeto de aplicativo em branco e inclua-o no Live SDK

Crie seu novo aplicativo usando um modelo do Visual Studio, assim:

  1. No Visual Studio, no menu Arquivo, clique em Novo Projeto...
  2. Na caixa de diálogo Novo Projeto..., vá para Instalado > Modelos > JavaScript > Windows Store.
  3. Selecione Aplicativo em Branco.
  4. Insira nome e local do novo aplicativo e clique em OK.
  5. Compile e teste seu aplicativo. Ele deve iniciar e mostrar uma página em branco que exibe apenas "O conteúdo vai aqui". Caso veja isso, feche o aplicativo e continue.

Etapa 2: Adicione o aplicativo à sua conta de desenvolvedor da Windows Store

Para que seu aplicativo use os serviços em nuvem acessados pelo Live SDK, ele deve estar registrado em sua conta de desenvolvedor da Windows Store. Você não precisa enviar o aplicativo à Windows Store para certificação. Você só precisa inserir um nome para ele na sua conta de desenvolvedor da Windows Store.

Etapa 3: Adicionar dados de aplicativo e submenus Configurações

Um aplicativo da Windows Store que usa o Live SDK deve realizar pelo menos uma destas duas ações:

  • Permitir que o usuário entre em sua conta da Microsoft (e saia, se possível).
  • Exibir uma política de privacidade que descreva como você protegerá os dados pessoais acessados pelo aplicativo.

Para saber mais sobre a experiência de entrada e saída e a política de privacidade, veja as Requisitos para entrada da conta da Microsoft.

Em um aplicativo da Windows Store, o acesso é feito pelos submenus Configurações.

Adicione submenus ao aplicativo assim:

  1. Crie uma página de submenu Conta.

    1. Crie uma nova pasta para os arquivos do submenu Conta. No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto, selecione Adicionar e selecione Nova Pasta.

    2. Renomeie-a como account.

    3. Clique com o botão direito na pasta account, selecione Adicionar e Novo Item...

    4. Na caixa de diálogo Adicionar Novo Item, vá para Instalado > JavaScript > Windows Store e selecione Controle de Página.

    5. No campo Nome, digite "account.html" e clique em Adicionar.

    6. Modifique os novos arquivos do aplicativo.

      No arquivo account.html, substitua o 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>

      Adicione o código a seguir ao final do arquivo 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 ; 
}

  2. Crie uma página de submenu Privacidade.

    1. Crie uma nova pasta para os arquivos do submenu Privacidade. No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto, selecione Adicionar e selecione Nova Pasta.

    2. Renomeie-a como privacy.

    3. Clique com o botão direito na pasta privacy, selecione Adicionar e Novo Item...

    4. Na caixa de diálogo Adicionar Novo Item, vá para Instalado > JavaScript > Windows Store e selecione Controle de Página.

    5. No campo Nome, digite "privacy.html" e clique em Adicionar.

    6. Modifique os novos arquivos do aplicativo.

      No arquivo privacy.html, substitua o 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>

      Não se esqueça de mudar o conteúdo de privacy.html para que faça referência à política de privacidade.

      Adicione o código a seguir ao final do arquivo 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 ; 
}

  3. Adicione os comandos de configurações.

    No arquivo default.js, adicione este código ao manipulador 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);
}

  4. Compile e execute o aplicativo.

  5. Abra o botão Configurações. Verifique se os comandos Conta e Privacidade aparecem no painel Configurações.

  6. Clique em cada comando para verificar se abre um submenu.

    Após ver os dois submenus, feche o aplicativo e continue.

Etapa 4: Adicione o conteúdo da interface do usuário e a vinculação de dados

É interessante que a interface do usuário do aplicativo represente o estado atual de sua conexão com a conta da Microsoft do usuário. Em vez de posicionar texto estático na interface do usuário do aplicativo, use a vinculação de dados para que o conteúdo da interface mude quando o valor de dados correspondente mudar.

Nesta etapa, você adicionará o código que conecta os dados do aplicativo à interface do usuário.

  1. Atualize default.html para que inclua os elementos da interface do usuário com os atributos de vinculação que conectam a interface aos dados do aplicativo.

    Para isso, substitua o conteúdo da marca <body> em 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>

    Nas marcas com atributos data-win-bind, o campo de dados que está vinculado a um atributo também aparece no valor da marca. Isso é feito apenas para depuração. Quando a vinculação é bem-sucedida, os valores de dados do programa substituem esse texto. Quando há erro de vinculação, é possível ver o nome do valor de dados que não é mostrado na interface do usuário. Isso pode ajudá-lo a depurar o erro.

  2. Crie o objeto de dados a ser usado como objeto de vinculação.

    Crie um novo arquivo chamado data.js na pasta js de seu projeto e adicione código a ele. Para isso, faça o seguinte:

    1. No Gerenciador de Soluções, clique com o botão direito na pasta js, selecione Adicionar e Novo Item...

    2. Vá para Instalado > JavaScript > Código e selecione Arquivo JavaScript.

    3. No campo Nome, digite "data.js" e clique em Adicionar.

    4. Substitua o conteúdo de data.js pelo código neste exemplo.

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

})();

  3. Adicione a referência a este novo arquivo em default.html inserindo o código antes da marca <script> que faz referência a default.js.

    
<!-- The app's data definition -->
<script src="/js/data.js"></script>

  4. Adicione o código para vincular o objeto de dados à interface do usuário.

    Em default.js, no manipulador de eventos app.onactivated, adicione este código para criar um objeto de vinculação e inicializá-lo.

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

  5. Adicione um manipulador de eventos para atualizar a interface do usuário com os dados do objeto de vinculação após carregar o documento do aplicativo.

    Em default.js, adicione esse manipulador de eventos imediatamente antes da atribuição 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);
}

  6. Adicione a função que sincronizará os dados do aplicativo com os do usuário.

    Nesta etapa, a função fornece apenas dados estáticos para testes. As funções de obtenção de dados do usuário da conta de Microsoft serão adicionadas em uma etapa posterior.

    Em default.js, adicione essa função após a função anônima, de modo que ela fique visível para outros módulos no aplicativo.

    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.";
    }
}

  7. Adicione seus arquivos de imagem.

    1. Copie os dois arquivos de imagem à pasta images do projeto. Renomeie uma imagem como "SignedOutImage.png" e a outra como "SignedInImage.png".

    2. No Gerenciador de Soluções, clique com o botão direito do mouse na pasta images e selecione Adicionar > Item Existente...

    3. Selecione os dois arquivos de imagem recém-adicionados e clique em Adicionar.

  8. Compile e teste seu aplicativo. Caso ele mostre texto e a imagem SignedOutImage.png na página, prossiga para a próxima etapa.

    Caso o aplicativo mostre o nome do campo de dados em vez de texto, significa que há um problema com a vinculação de dados. Corrija-o antes de continuar.

Etapa 5: Atualize o submenu Conta para usar o objeto de vinculação

  1. No account.html, altere as marcas <button> para que fiquem deste jeito, de modo que o estado de entrada seja usado para exibir o botão correto no submenu.

    
<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>

  2. Em account.js, adicione estas funções após a função 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();
}

    Em seguida, modifique a função do caso ready da chamada WinJS.UI.Pages.define, de modo a incluir uma chamada para updateDisplay, como neste exemplo.

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

  3. Adicione as funções para default.js que permitem a entrada e saída do usuário da conta da Microsoft.

    Essas funções não interagem com recursos do Windows Live Services — ainda. Eles serão adicionados em uma etapa posterior. Essas funções apenas permitem testar o objeto de associação para garantir que ele funcione nos dois estados de entrada e atualize a interface do usuário quando o estado de entrada mudar.

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

  4. Compile e teste seu aplicativo.

    1. O aplicativo é iniciado e exibe SignedOutImage.png.

    2. Abra o botão Configurações e selecione o comando Conta. Verifique se o prompt e o botão Entrar aparecem.

    3. Clique no botão Entrar e verifique se o estado do aplicativo e o conteúdo do submenu Conta mudam para refletir o estado conectado.

    4. No submenu Conta, verifique se o prompt e o botão Sair aparecem.

    5. Clique no botão Sair e verifique se o estado do aplicativo e o conteúdo do submenu Conta mudam para refletir o estado desconectado.

    Quando o aplicativo funciona desse modo, você já pode adicionar os recursos do Windows Live Services.

Etapa 6: Adicione as funções do Live SDK

  1. Adicione a referência ao Live SDK a seu aplicativo.

    1. No Gerenciador de Soluções, clique com o botão direito do mouse em Referências e selecione Adicionar Referência...

    2. Vá para Windows > Extensões, marque Live SDK e clique em OK.

    3. Na marca <head> de default.html, adicione esta linha antes do link default.css.

      <!-- The Live SDK -->
<script src="///LiveSDKHTML/js/wl.js"></script>

  2. Inicialize o Live SDK.

    Em default.js, insira este código após a atribuição binding.Person no manipulador app.onactivated.

    // Initialize the Live SDK.
WL.init();

  3. Atualize a função getInfoFromAccount de modo que o aplicativo obtenha o estado de entrada do usuário da conta da Microsoft.

    Em default.js, getInfoFromAccount, substitua as duas instruções if que testam p.index por 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.";
    }
);

  4. Atualize a função SignInNewUser para permitir a entrada do usuário na conta da Microsoft.

    Em default.js, SignInNewUser, substitua o código após o teste de parâmetro por 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);
});

  5. Atualize a função SignOutUser.

    Em default.js, SignOutUser, substitua o código após o teste de parâmetro por este código.

    // Sign out and then refresh the app's data object.
WL.logout().then(function (response) {
    getInfoFromAccount(p);
});

  6. Adicione a função ShowSignOutButton.

    Ao final de default.js, adicione a função ShowSignOutButton mostrada aqui.

    function ShowSignOutButton() {
    // Return true or false to indicate whether the user 
    // can sign out of the app.
    return (WL.canLogout());
}

  7. Adicione o teste para ver se o usuário pode sair. Quando o usuário entra no aplicativo com uma conta do computador associada a uma conta da Microsoft, ele não pode sair do aplicativo. A função testa essa condição para exibir o prompt correto ao usuário.

    Em account.js, na função updateDisplay, substitua a declaração if por este código. Observe o teste que adicionado para dizer se o botão Sair deve ser exibido.

        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"
    }

  8. Remova o código fictício usado para testes anteriores.

    Em account.js, signInCmd, remova as chamadas para updateDisplay e WinJS.UI.SettingsFlyout.show de modo que a única linha de código da função seja esta.

    // Sign the new user in.
//  This call closes the Flyout and Settings charm.
SignInNewUser(p);

    Em account.js, signOutCmd, remova a chamada para updateDisplay de modo que as únicas linhas de código da função sejam estas.

    // Sign the current user out.
SignOutUser(p);

// Return to the Settings flyout.   
WinJS.UI.SettingsFlyout.show();

Seu aplicativo já pode ser testado com uma conta da Microsoft.

Etapa 7: Teste seu aplicativo

Compile e execute seu aplicativo, testando estas ações.

  1. Teste a entrada em uma conta da Microsoft.

    Começando com o aplicativo desconectado da conta da Microsoft do usuário, tente executar estas etapas:

    1. Abra o submenu Configurações, selecione o comando Conta e clique em Entrar.
    2. Entre usando uma conta da Microsoft. Caso o aplicativo solicite permissão para continuar, clique em Sim.
    3. Verifique se o texto e a imagem no aplicativo mudam para o texto e imagem de entrada.

  2. Teste a saída do aplicativo.

    Observação  Caso esteja testando o aplicativo em uma conta do computador associada a uma conta da Microsoft, o botão Sair será desabilitado. Esse é o comportamento esperado. Para executar este teste, execute o aplicativo com uma conta que não esteja associada a uma conta da Microsoft.

     

    Começando com o aplicativo conectado à conta da Microsoft do usuário, tente executar estas etapas:

    1. Abra o submenu Configurações, selecione o comando Conta e clique em Sair.
    2. Verifique se o texto e a imagem no aplicativo mudam para o texto e imagem de saída.

  3. Teste o logon único.

    O logon único é um recurso do Windows que permite associar a conta do computador à conta da Microsoft. Se você estiver executando o aplicativo com esse tipo de conta, o comportamento do aplicativo será diferente do descrito anteriormente.

    Por exemplo:

    • O aplicativo pode iniciar no estado conectado automaticamente.
    • O botão Sair não aparece no submenu Conta, pois não é possível sair de sua conta a partir do aplicativo.
    • O submenu Conta mostra uma mensagem adicional, dizendo que não é possível sair a partir do aplicativo.

Tópicos relacionados

Vinculação de dados

data-win-control

data-win-options

data-win-bind

SDK do Live

WinJS.Namespace

WinJS.UI.SettingsFlyout

WL.api

WL.canLogout

WL.init

WL.login

WL.logout