DOCSEARCHbyAlgolia
Submit Docs

Project Rome

repository·master·Indexed 19 days ago

https://github.com/microsoft/project-rome

A cross-device experiences platform from Microsoft that enables applications to provide seamless, user-centric experiences across different devices. It decouples applications from specific hardware and provides SDKs for Windows, Android, and iOS, as well as integration via Microsoft Graph REST API endpoints for features like the Activity Feed API and Device Relay API.

Tokens
5.1K
Snippets
7
Records
30
Agent score
66%

What's inside Project Rome

  1. Overview of Project Rome

    master
    Project Rome is Microsoft's cross-device experiences platform. It is designed to decouple applications from specific hardware, allowing developers to build user-centric experiences that persist and function across multiple devices.

  3. What is a cross-device app in Project Rome?

    master

    A cross-device app is a configuration that associates multiple platform-specific applications (e.g., Windows, iOS, Android, Web) into a single logical group. This configuration is required to enable seamless user experiences across different devices using Project Rome APIs.

    By configuring a cross-device app, you can enable:

    1. Activity Feed API (Microsoft Graph): Allows a group of apps to read and write shared user activities, enabling features like "pick up where you left off."
    2. Project Rome SDK (Windows, Android, iOS): Enables reading and writing user activities published by any app within the configured group.
    3. Device Relay API (Android, iOS): Allows targeting specific apps on mobile devices using push notification credentials, enabling real-time workflow transitions (e.g., moving a video from a phone to an Xbox).

  4. How Graph Notifications work with UNS ID

    master

    In the Graph Notifications workflow, an App Service (e.g., Outlook) needs a way to identify a specific user to deliver a notification. This is achieved using the User Notification Subscription ID (UNS ID).

    The Workflow:

    1. The Client App (Windows, iOS, Android, or Web) signs the user in.
    2. The Client App receives a UNS ID as part of the response after subscribing to notifications.
    3. The Client App sends this UNS ID to the App Service.
    4. The App Service uses the UNS ID to call Microsoft Graph and post a notification specifically to that user on their device.

  5. Terminology for Graph Notifications

    master

    When working with this sample and the underlying notification architecture, use the following terms:

    • Sample App/Client App: The application (Windows, iOS, Android, or Web) where the user signs in.
    • Sample API/App Service: The service that intends to post a notification.
    • Azure AD: The Identity Service.
    • AFS/WNS: Internal Microsoft services supporting the graph notifications scenario.

  6. Understand the On-Behalf-Of (OBO) flow for Graph Notifications

    master

    In the Graph Notifications scenario, an App Service (A.S.) needs to identify a user to post notifications. While the client app can send a User Access Token (AT) directly, these tokens expire every hour.

    To provide a more permanent solution, the On-Behalf-Of (OBO) flow is used:

    1. The client app sends the User's AT to the App Service.
    2. The App Service exchanges this User AT for an OBO token (Access Token and Refresh Token) from the Identity Service (Azure AD) using its own client credentials.
    3. The App Service uses the OBO token to hit the Graph endpoint.

    Note: This is a transitional solution. Future versions of the SDK/API will replace user authentication with a User Identifier (UNSId), which only needs to be sent to the App Service once during subscription.

  7. Configure app clients with the cross-device host value

    master

    Once your domain is defined in the JSON file, your individual app clients must be configured to recognize that domain as their host.

    MSGraph Apps

    If using the Activity Feed API on MSGraph, provide your domain in the activitySourceHost property.

    Universal Windows (UWP) Apps

    Configure the host value in your app manifest under the uap5:userActivity element before publishing data.

    iOS & Android Apps

    Details coming soon.

  8. Setup the Graph Notifications Sample App Service

    master

    To run the sample application which demonstrates using the On-Behalf-Of (OBO) flow for Graph notifications, follow these steps:

    1. Clone the repository to your local machine.
    2. Configure credentials in the following files:
      • siteConfig.js: Update appServiceClientId with your App Service ID from the Azure Portal.
      • Web.config: Update appServiceClientSecret with your App Service Secret from the Azure Portal.
      • Update TargetHostName with the Domain name verified and associated with the App Service ID in the Dev Portal.
    3. Deploy locally using IIS Express within Visual Studio.
    # No specific command provided, follow manual steps above

  9. Access Project Rome developer documentation and samples

    master

    To integrate Project Rome features into your application, use the following resources:

    • Samples: This repository contains various samples of Project Rome implementations.
    • Developer Docs: For detailed how-to guides and API reference documentation, visit the Project Rome developer docs.
    • Microsoft Graph Integration: Project Rome capabilities are exposed via Microsoft Graph REST API endpoints. For conceptual overviews of cross-device experiences via Graph, refer to the Cross-Device Experience docs.

  10. Demo Flow: Obtaining User AT and Exchanging for OBO Token

    master

    The sample demonstrates a two-stage authentication flow:

    1. Getting User's AT with correct Scopes

    This logic typically resides in the client app:

    • User signs in via 'Sign In with Microsoft'.
    • User consents to Graph authorization scopes (defined in siteConfig.js under site.graphNotificationScopes).
    • If the 'Access resources via On-Behalf-of' switch is enabled in the UI, the user also consents to App Service scopes (site.appServiceScopes in siteConfig.js), resulting in an access token with cumulative scopes.

    2. Exchanging User's AT for OBO AT/RT

    This logic resides in the App Service (OboController.cs):

    • The client calls the submission endpoint (e.g., site.createNotificationsViaObo in site.js).
    • The App Service calls GetOboTokenAsync (via PostAsync) to exchange the User's AT for an OBO token from Azure AD.
    • The App Service then uses the OBO token to send the request payload to the Graph endpoint.

  11. Get started with Project Rome for Android

    master

    Project Rome for Android provides sample applications that demonstrate its features. To use these features, you must have:

    • An Android app development IDE (such as Android Studio).
    • An Android device or emulator running Android 4.4.2 or later.

  12. Set up the Graph Notifications Sample App Service

    master

    To run the sample App Service that demonstrates sending notifications using a User Notification Subscription ID (UNS ID), follow these steps:

    1. Clone the repository to your local environment.
    2. Configure credentials and identifiers in the configuration files (see Configuration Reference).
    3. Deploy locally using IIS Express within Visual Studio.