Skip to content

Commit 06f76c5

Browse files
mattwojomattwojo
authored
Add cross device and phone link (#4093)
* Add cross device and phone link * cross dev toc test * toc link fix * TOC updates * toc update and image fix * Update based on latest word draft * Update supported devices link * Update to fix typo in Java sample * Update toc * Delete hub/images/desktop.ini
1 parent ced7990 commit 06f76c5

File tree

4 files changed

+236
-0
lines changed

4 files changed

+236
-0
lines changed

‎hub/cross-device/phonelink/index.md

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
---
2+
title: Phone Link Task Continuity
3+
description: Phone Link enables synchronization between your Windows PC and mobile device. Learn how to integrate your Windows app with Phone Link for task continuity.
4+
author: mattwojo
5+
ms.author: mattwoj
6+
manager: jken
7+
ms.topic: article
8+
ms.date: 02/20/2024
9+
---
10+
11+
# Phone Link for Cross-Device Task Continuity
12+
13+
Your mobile application can programmatically share recent website URLs and document links to a Windows PC that has [set up Phone Link](https://www.microsoft.com/windows/sync-across-your-devices). This task continuity feature is available on Android devices integrated with the "Link to Windows" experience.
14+
15+
This feature is only available on [Supported devices for Phone Link experiences](https://aka.ms/TaskContinuityAPI).
16+
17+
This documentation will cover how to integrate your app with the **Phone Link Task Continuity API**, including the scenario requirements, surface area, and Limited Access Feature (LAF) approval.
18+
19+
Learn more about Phone Link: [Sync Your Smartphone to Your Windows Computer](https://www.microsoft.com/windows/sync-across-your-devices).
20+
21+
## Scenario Requirements
22+
23+
The task continuity API lets you sync content from your Android app over to a Windows PC that has [set up Phone Link](https://www.microsoft.com/windows/sync-across-your-devices). The following conditions must be met for access to this API to be granted:
24+
25+
- DO sync web URLs that are valid URLs that are accessible by the Windows PC
26+
- DO sync cloud document links that are accessible by the Windows PC
27+
- DO sync local document links to the Windows PC that must be accessible on the mobile device through your application
28+
- DO NOT sync more than 60 times per minute
29+
- DO NOT sync content if the user is not engaging with your app experience
30+
31+
## Phone Link surface
32+
33+
Phone Link will surface your sync'ed content in the Apps node under "Recently used" and "Recent websites" and in a notification flyout.
34+
35+
![Phone Link screenshot of recently used apps and websites](../../images/phonelink-recents.png)
36+
37+
## Limited Access Feature (LAF) approval
38+
39+
Phone Link Task Continuity is a Limited Access Feature (LAF). To gain access to this API, you will need to get approval from Microsoft to interoperate with the "Link to Windows" package preloaded on Android mobile devices.
40+
41+
To request access, email `[email protected]` with the information listed below.
42+
43+
- Description of your user experience
44+
- Screenshot of your application where a user natively accesses web or documents
45+
- PackageId of your application
46+
- Google Play store link for your application
47+
48+
If the request is approved, you will receive instructions on how to unlock the feature. Approvals will be based on your communication, provided that your scenario meets the [Scenario Requirements](#scenario-requirements) outlined above.
49+
50+
## Data Handling
51+
52+
By using the Phone Link Task Continuity API, Microsoft will process and transfer your data in accordance with the [Microsoft Services Agreement](https://www.microsoft.com/servicesagreement) and the [Microsoft Privacy Statement](https://privacy.microsoft.com/privacystatement). Data that is transferred to the user’s linked devices may be processed through Microsoft’s cloud services to ensure reliable data transfer between devices. The data handled by this API is not retained by Microsoft's cloud services subject to end user control.
53+
54+
The Cross-Device SDK that you will integrate in your package ensures that data provided to the API is only handled by trusted Microsoft packages.
55+
56+
## How to integrate your app with the Phone Link Task Continuity API
57+
58+
To integrate your Android mobile app with the Phone Link Task Continuity API, you will need to update your manifest declarations and then send the app context. See the sample code examples below.
59+
60+
### Android app manifest declarations
61+
62+
Your app should register a broadcast receiver for the cross-device app context provider to participate in the contract. The registration should be in the manifest as follows.
63+
64+
```xml
65+
<?xml version="1.0" encoding="utf-8"?>  
66+
<manifest xmlns:android="http://schemas.android.com/apk/res/android"  
67+
    <!--  
68+
        If the app targets API 30 or higher, be sure to use the <queries>  
69+
        and add com.microsoft.appmanager to the included packages.  
70+
    -->  
71+
    <queries>  
72+
        <package android:name="com.microsoft.appmanager" />  
73+
    </queries>  
74+
    <application …    
75+
        <!-- … -->  
76+
       <!--  
77+
           This is the receiver declaration for receiving broadcasts from LTW.  
78+
           It needs to be exported with meta-data as this is checked for   
79+
80+
           The package before we send the broadcast.  
81+
       -->  
82+
       <receiver  
83+
           android:name="com.microsoft.crossdevicesdk.continuity.AppContextBroadcastReceiver" 
84+
           android:enabled="true"  
85+
           android:exported="true">  
86+
           <intent-filter>  
87+
               <action android:name="com.microsoft.crossdevice.appcontextrequest" />  
88+
           </intent-filter>  
89+
  
90+
            <meta-data  
91+
                android:name="com.microsoft.crossdevice.sampleProviderMetadataName"  
92+
                android:value="true" />  
93+
        </receiver>  
94+
    </application>  
95+
</manifest>
96+
```
97+
98+
### Code samples for sending app context
99+
100+
Once the manifest declarations are added, partner apps can send their app context as seen in the code sample examples below.
101+
102+
This example demonstrates using the `IAppContextEventHandler` interface with Java.
103+
104+
```java
105+
IAppContextEventHandler appContextEventHandler = new IAppContextEventHandler() { 
106+
    @Override 
107+
    public void onContextRequestReceived(ContextRequestInfo contextRequestInfo) { 
108+
        Log.d(TAG, String.format("onContextRequestReceived, type:%s", contextRequestInfo.getType())); 
109+
        //Not necessary to do following things in here, just 
110+
        //make sure to send app context after receiving broadcast. 
111+
        AppContext appContext = new AppContext(); 
112+
        //... 
113+
        //set parameter 
114+
        appContext.setType(ProtocolConstants.TYPE_APPLICATION_CONTEXT); 
115+
        appContext.setCreateTime(System.currentTimeMillis()); 
116+
        appContext.setLastUpdatedTime(System.currentTimeMillis()); 
117+
        appContext.setTitle("New PowerPoint Presentation"); 
118+
appContext.setExtras("{\"DocInfo\":\"[{\"timestamp\":1672,\"DocTitle\":\"Book Sharing\",\"Index\":\"8\"}]\"}"); 
119+
        //... 
120+
        AppContextManager.INSTANCE.sendAppContext(getApplicationContext(),appContext); 
121+
    } 
122+
 
123+
    @Override 
124+
    public void onInvalidContextRequestReceived(@NonNull Throwable throwable) { 
125+
        Log.e(TAG, String.format("onInvalidContextRequestReceived: " + throwable.getMessage())); 
126+
    } 
127+
128+
    @Override  
129+
    public void onSyncServiceDisconnected() {  
130+
        Log.d(TAG, String.format("onSyncServiceDisconnected"));  
131+
    } 
132+
}; 
133+
AppContextManager.INSTANCE.setAppContextEventHandler(appContextEventHandler);
134+
```
135+
136+
This example demonstrates using an object expression to implement the `IAppContextEventHandler` interface with Kotlin.
137+
138+
```kotlin
139+
val appContextEventHandler = object : IAppContextEventHandler {
140+
override fun onContextRequestReceived(contextRequestInfo: ContextRequestInfo) {
141+
Log.d(TAG, String.format("onContextRequestReceived, type:%s", contextRequestInfo.type));
142+
//Not necessary to do following things in here, just
143+
//make sure to send app context after receiving broadcast.
144+
var appContext = AppContext()
145+
//...
146+
//set parameter
147+
appContext.type = ProtocolConstants.TYPE_APPLICATION_CONTEXT
148+
appContext.createTime = System.currentTimeMillis()
149+
appContext.lastUpdatedTime = System.currentTimeMillis()
150+
appContext.setTitle("New PowerPoint Presentation")
151+
appContext.setExtras("{\"DocInfo\":\"[{\"timestamp\":1672,\"DocTitle\":\"Book Sharing\",\"Index\":\"8\"}]\"}")
152+
//...
153+
AppContextManager.sendAppContext(applicationContext,appContext)
154+
}
155+
156+
override fun onInvalidContextRequestReceived(throwable: Throwable) {
157+
Log.e(TAG, String.format("onInvalidContextRequestReceived: " + throwable.message))
158+
}
159+
160+
override fun onSyncServiceDisconnected() {
161+
Log.d(TAG, String.format("onSyncServiceDisconnected"))
162+
}
163+
}
164+
AppContextManager.setAppContextEventHandler(appContextEventHandler)
165+
```
166+
167+
### Protocol description
168+
169+
The protocol is a simple broadcast that is sent from "Link to Windows" to each of the packages that support a specific type of app context feature when "Link to Windows" is ready to get the app context.
170+
171+
172+
| Intent field | Key | Value |
173+
| --- | --- | --- |
174+
| Action | N/A | `com.microsoft.crossdevice.appcontextrequest` Fixed for link to Windows. The requester will be `com.microsoft.appmanager` |
175+
| Extras (bundle) | `version` | 2.0 (version [minor].[major]) |
176+
| Extras (bundle) | `contentProviderUri` | `content://com.microsoft.taskcontinuity/b695d1d8` Uniquely generated for each package. |
177+
| Extras (bundle) | `requestedContextType` | If provided, indicate what app context type is requested. This is a binary flag, for now we have two types... Application context: 0x01, and Browser history context: 0x02. |
178+
179+
After receiving the broadcast, the SDK will be responsible for validation and handling the information. The expectation from packages that receive the broadcast is to send the app context to link to Windows. The following values should be provided by partner apps when sending app context:
180+
181+
| Key | Value | Extra information |
182+
| --- | --- | --- |
183+
| `type` [required] | A binary flag that indicates what app context type is sent to LTW. The value should be consistent with the `requestedContextType`. |
184+
| `createTime` [required] | Timestamp representing the create time of the app context. | |
185+
| `lastUpdatedTime` [required] | Timestamp representing the last updated time of the app context. | Any time when any fields of app context is updated, the updated time needs to be recorded. |
186+
| `teamId` [optional] | Used to identify the organization or group the app belongs to. | |
187+
| `intentUri` [optional] | Used to indicate which app can continue the app context handed over from the originating device. | |
188+
| `appId` [optional] | The package of the application the context is for. | Only context service providers need to use this. Refer to the Java docs. If omitted, the calling response provider's package will be used. |
189+
| `title` [optional] | The title of this app context, such as a document name or web page title. | |
190+
| `weblink` [optional] | The URL of the webpage to load in a browser to continue the app context. | |
191+
| `preview` [optional] | Bytes of the preview image that can represent the app context. | |
192+
| `extras` [optional] | A key-value pair object containing app-specific state information needed to continue an app context on the continuing device. | Need to provide when the app context has its unique data. |
193+
| `LifeTime` [optional] | The lifetime of the app context in milliseconds. | Only used for ongoing scenario, if not set, the default value is -1. |
194+
195+
To be compatible with the previous "Browser Continuity" feature using **X-Device SDK 1.0**, we have another two additional methods added. The following values should be provided when using this feature:
196+
197+
| Intent field | Key | Value |
198+
| --- | --- | --- |
199+
| `browserContextEmptyFlag` [optional] | Flag to indicate if browser context is empty. | This is only for Browser Continuity feature. |
200+
| `browserHistory` [optional] | Browsing history context for the app. | This is only for the Browser Continuity feature. Currently recommend providing up to 3 URIs. If more are provided, they will be ignored. |
201+
202+
Partner apps can call `addBrowserContext` method to add browser history.
203+
The following values should be provided when adding browser history:
204+
205+
| Key | Value |
206+
| --- | --- |
207+
| `browserWebUri` | A web URI that will open in browser on PC.
208+
(http: or https:) |
209+
| `title` | The title of the web page. |
210+
| `timestamp` | The timestamp that the web page was first opened or last refreshed. |
211+
| `favIcon` [optional] | The favicon of the web page in bytes, should be small in general. |
212+
213+
## Windows Cross-Device repo on GitHub
214+
215+
Find information about integrating the Windows Cross-Device SDK into your project in the [Windows-Cross-Device repo on GitHub](https://github.com/microsoft/Windows-Cross-Device/).
216+
217+
## Phone Link FAQs
218+
219+
For a list of FAQs, see [Phone Link Frequently Asked Questions](https://www.microsoft.com/windows/sync-across-your-devices).

‎hub/cross-device/phonelink/toc.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
items:
2+
- name: Windows Developer Docs
3+
items:
4+
- name: Windows app development docs
5+
href: /windows/apps/
6+
- name: Cross-Device APIs
7+
items:
8+
- name: Phone Link Task Continuity
9+
href: ../phonelink/index.md
10+
- name: Project Rome cross-device experiences
11+
href: /windows/project-rome/
12+
- name: Microsoft Graph API
13+
href: /graph/cross-device-concept-overview/
14+
- name: Windows development environment and tools
15+
href: /windows/dev-environment/
16+
17+

‎hub/images/phonelink-icon.png

2.28 KB
Loading

‎hub/images/phonelink-recents.png

73.5 KB
Loading

0 commit comments

Comments
 (0)