Ler em inglês

Compartilhar via


Phone Link para continuidade de tarefas entre dispositivos

Seu aplicativo móvel pode compartilhar programaticamente URLs de sites recentes e links de documentos para um computador Windows que tenha configurado o Phone Link. Esse recurso de continuidade de tarefas está disponível em dispositivos Android integrados com a experiência "Vincular ao Windows".

Esse recurso só está disponível em dispositivos compatíveis com experiências do Phone Link.

Essa documentação abordará como integrar seu aplicativo à API de continuidade de tarefas do Phone Link, incluindo os requisitos do cenário, a área de superfície e a aprovação do LAF (Recurso de Acesso Limitado).

Saiba mais sobre o Phone Link: sincronize seu smartphone com seu computador Windows.

Requisitos do cenário

A API de continuidade de tarefas permite sincronizar conteúdo do seu aplicativo Android com um computador Windows que tenha configurado o Phone Link. As seguintes condições devem ser atendidas para que o acesso a essa API seja concedido:

  • SINCRONIZE URLs da Web válidas que são acessíveis pelo computador Windows
  • SINCRONIZE links de documentos na nuvem que são acessíveis pelo computador Windows
  • SINCRONIZE links de documentos locais para o computador Windows que devem estar acessíveis no dispositivo móvel por meio de seu aplicativo
  • NÃO sincronize mais de 60 vezes por minuto
  • NÃO sincronize conteúdo se o usuário não estiver interagindo com sua experiência de aplicativo

O Phone Link exibirá seu conteúdo sincronizado no nó Aplicativos em "Usados recentemente" e "Sites recentes" e em um submenu de notificação.

Captura de tela do Phone Link de aplicativos e sites recentemente usados

Aprovação do Recurso de Acesso Limitado (LAF)

A continuidade de tarefa do Phone Link é um recurso de acesso limitado (LAF). Para obter acesso a essa API, você precisará obter aprovação da Microsoft para interoperar com o pacote "Vincular ao Windows" pré-carregado em dispositivos móveis Android.

Para solicitar o acesso, envie um email wincrossdeviceapi@microsoft.com com as informações listadas abaixo.

  • Descrição da sua experiência de usuário
  • Captura de tela do seu aplicativo onde um usuário acessa nativamente a Web ou documentos
  • PackageId do seu aplicativo
  • Link do Google Play Store para seu aplicativo

Se a solicitação for aprovada, você receberá instruções sobre como desbloquear o recurso. As aprovações serão baseadas em sua comunicação, desde que seu cenário atenda aos Requisitos de cenário descritos acima.

Processamento dos dados

Usando a API de continuidade de tarefas do Phone Link, a Microsoft processará e transferirá seus dados de acordo com o Contrato de Serviços da Microsoft e a Declaração de Privacidade da Microsoft. Os dados transferidos aos dispositivos vinculados do usuário podem ser processados por meio dos serviços de nuvem da Microsoft para garantir a transferência confiável de dados entre dispositivos. Os dados processados por esta API não são retidos pelos serviços de nuvem da Microsoft sujeitos ao controle do usuário final.

O SDK entre dispositivos que você integrará ao pacote garante que os dados fornecidos à API sejam manipulados apenas por pacotes confiáveis da Microsoft.

Para integrar seu aplicativo móvel Android com a API de continuidade de tarefas do Phone Link, você precisará atualizar suas declarações de manifesto e, em seguida, enviar o contexto do aplicativo. Consulte as amostras de código de exemplo abaixo.

Declarações de manifesto do aplicativo Android

Seu aplicativo deve registrar um receptor de transmissão para que o provedor de contexto de aplicativo entre dispositivos participe do contrato. O registro deve estar no manifesto da seguinte forma.

<?xml version="1.0" encoding="utf-8"?>   
<manifest xmlns:android="http://schemas.android.com/apk/res/android"   
    <!--   
        If the app targets API 30 or higher, be sure to use the <queries>   
        and add com.microsoft.appmanager to the included packages.   
    -->   
    <queries>   
        <package android:name="com.microsoft.appmanager" />   
    </queries>   
    <application …     
        <!-- … -->   
       <!--   
           This is the receiver declaration for receiving broadcasts from LTW.   
           It needs to be exported with meta-data as this is checked for    

           The package before we send the broadcast.   
       -->   
       <receiver   
           android:name="com.microsoft.crossdevicesdk.continuity.AppContextBroadcastReceiver"  
           android:enabled="true"   
           android:exported="true">   
           <intent-filter>   
               <action android:name="com.microsoft.crossdevice.appcontextrequest" />   
           </intent-filter>   
   
            <meta-data   
                android:name="com.microsoft.crossdevice.sampleProviderMetadataName"   
                android:value="true" />   
        </receiver>   
    </application>   
</manifest>

Exemplos de código para enviar contexto do aplicativo

Depois que as declarações de manifesto são adicionadas, os aplicativos parceiros podem enviar seu contexto de aplicativo, conforme visto nas amostras de código de exemplo abaixo.

Este exemplo demonstra o uso da interface IAppContextEventHandler com Java.

IAppContextEventHandler appContextEventHandler = new IAppContextEventHandler() {  
    @Override  
    public void onContextRequestReceived(ContextRequestInfo contextRequestInfo) {  
        Log.d(TAG, String.format("onContextRequestReceived, type:%s", contextRequestInfo.getType()));  
        //Not necessary to do following things in here, just  
        //make sure to send app context after receiving broadcast.  
        AppContext appContext = new AppContext();  
        //...  
        //set parameter  
        appContext.setType(ProtocolConstants.TYPE_APPLICATION_CONTEXT);  
        appContext.setCreateTime(System.currentTimeMillis());  
        appContext.setLastUpdatedTime(System.currentTimeMillis());  
        appContext.setTitle("New PowerPoint Presentation");  
        appContext.setExtras("{\"DocInfo\":\"[{\"timestamp\":1672,\"DocTitle\":\"Book Sharing\",\"Index\":\"8\"}]\"}");  
        //...  
        AppContextManager.INSTANCE.sendAppContext(getApplicationContext(),appContext);  
    }  
  
    @Override  
    public void onInvalidContextRequestReceived(@NonNull Throwable throwable) {  
        Log.e(TAG, String.format("onInvalidContextRequestReceived: " + throwable.getMessage()));  
    }  

    @Override   
    public void onSyncServiceDisconnected() {   
        Log.d(TAG, String.format("onSyncServiceDisconnected"));   
    }  
};  
AppContextManager.INSTANCE.setAppContextEventHandler(appContextEventHandler);

Este exemplo demonstra o uso de uma expressão de objeto para implementar a interface IAppContextEventHandler com Kotlin.

val appContextEventHandler = object : IAppContextEventHandler { 
    override fun onContextRequestReceived(contextRequestInfo: ContextRequestInfo) { 
        Log.d(TAG, String.format("onContextRequestReceived, type:%s", contextRequestInfo.type)); 
        //Not necessary to do following things in here, just 
        //make sure to send app context after receiving broadcast. 
        var appContext = AppContext() 
        //... 
        //set parameter 
        appContext.type = ProtocolConstants.TYPE_APPLICATION_CONTEXT 
        appContext.createTime = System.currentTimeMillis() 
        appContext.lastUpdatedTime = System.currentTimeMillis() 
        appContext.setTitle("New PowerPoint Presentation") 
        appContext.setExtras("{\"DocInfo\":\"[{\"timestamp\":1672,\"DocTitle\":\"Book Sharing\",\"Index\":\"8\"}]\"}") 
        //... 
        AppContextManager.sendAppContext(applicationContext,appContext) 
    } 
 
    override fun onInvalidContextRequestReceived(throwable: Throwable) { 
        Log.e(TAG, String.format("onInvalidContextRequestReceived: " + throwable.message)) 
    } 
 
    override fun onSyncServiceDisconnected() { 
        Log.d(TAG, String.format("onSyncServiceDisconnected")) 
    } 
} 
AppContextManager.setAppContextEventHandler(appContextEventHandler)

Descrição do protocolo

O protocolo é uma transmissão simples que é enviada do "Vincular ao Windows" para cada um dos pacotes que oferecem suporte a um tipo específico de recurso de contexto de aplicativo quando "Vincular ao Windows" está pronto para obter o contexto do aplicativo.

Campo de intenção Chave Valor
Ação N/D com.microsoft.crossdevice.appcontextrequest Corrigido para vincular ao Windows. O solicitante será com.microsoft.appmanager
Extras (pacote) version 2.0 (versão [menor].[maior])
Extras (pacote) contentProviderUri content://com.microsoft.taskcontinuity/b695d1d8 Gerado exclusivamente para cada pacote.
Extras (pacote) requestedContextType Se fornecido, indique qual tipo de contexto de aplicativo é solicitado. Esta é uma bandeira binária. Por enquanto, temos dois tipos: contexto do aplicativo: 0x01 e contexto do histórico do navegador: 0x02.

Após receber a transmissão, o SDK será responsável pela validação e processamento das informações. A expectativa dos pacotes que recebem a transmissão é enviar o contexto do aplicativo para vincular ao Windows. Os seguintes valores devem ser fornecidos pelos aplicativos parceiros ao enviar o contexto do aplicativo:

Chave Valor Informações adicionais
type [obrigatório] Um sinalizador binário que indica qual tipo de contexto de aplicativo é enviado para o LTW. O valor deve ser consistente com requestedContextType.
createTime [obrigatório] Carimbo de data/hora que representa o momento de criação do contexto do aplicativo.
lastUpdatedTime [obrigatório] Carimbo de data/hora que representa o momento da última atualização do contexto do aplicativo. Sempre que algum campo de contexto do aplicativo for atualizado, o momento atualizado precisará ser registrado.
teamId [opcional] Usado para identificar a organização ou o grupo ao qual o aplicativo pertence.
intentUri [opcional] Usado para indicar qual aplicativo pode continuar o contexto do aplicativo entregue do dispositivo de origem.
appId [opcional] O pacote do aplicativo para o qual o contexto se destina. Somente os provedores de serviços de contexto precisam usar isso. Consulte os documentos Java. Se omitido, o pacote do provedor de resposta de chamada será usado.
title [opcional] O título desse contexto de aplicativo, como um nome de documento ou título de página da Web.
weblink [opcional] A URL da página da Web a ser carregada em um navegador para continuar o contexto do aplicativo.
preview [opcional] Bytes da imagem de visualização que podem representar o contexto do aplicativo.
extras [opcional] Um objeto de par chave-valor que contém informações de estado específicas do aplicativo necessárias para continuar um contexto de aplicativo no dispositivo contínuo. Necessidade de fornecer quando o contexto do aplicativo tem seus dados exclusivos.
LifeTime [opcional] O tempo de vida do contexto do aplicativo em milissegundos. Usado somente para o cenário em andamento, se não for definido, o valor padrão será -1.

Para ser compatível com o recurso "Continuidade do navegador" anterior usando X-Device SDK 1.0, temos outros dois métodos adicionados. Os seguintes valores devem ser fornecidos ao usar esse recurso:

Campo de intenção Chave Valor
browserContextEmptyFlag [opcional] Sinalizador para indicar se o contexto do navegador está vazio. Isso é apenas para o recurso Continuidade do navegador.
browserHistory [opcional] Contexto do histórico de navegação do aplicativo. Isso é apenas para o recurso Continuidade do navegador. Atualmente, recomenda-se o fornecimento de até 3 URIs. Se mais forem fornecidas, elas serão ignoradas.

Os aplicativos parceiros podem chamar o método addBrowserContext para adicionar o histórico do navegador. Os seguintes valores devem ser fornecidos ao adicionar o histórico do navegador:

Chave Valor
browserWebUri Uma URI da Web que será aberta no navegador no PC.
(http: ou https:)
title O título da página da Web.
timestamp O carimbo de data/hora em que a página da Web foi aberta pela primeira vez ou atualizada pela última vez.
favIcon [opcional] O favicon da página da Web em bytes, deve ser pequeno em geral.

Repositório entre dispositivos do Windows no GitHub

Encontre informações sobre como integrar o Windows Cross-Device SDK ao seu projeto no repositório Windows-Cross-Device no GitHub.

Para obter uma lista de perguntas frequentes, consulte Perguntas frequentes sobre Phone Links.