Implementazione di attività utente per Android

2025-06-10

Le attività utente sono costrutti di dati che rappresentano le attività di un utente all'interno di un'applicazione. Consentono di salvare uno snapshot di un'attività da continuare in un secondo momento. La funzionalità Sequenza temporale di Windows presenta agli utenti di Windows un elenco scorrevole di tutte le attività recenti, rappresentate come schede con testo e grafica. Per altre informazioni sulle attività utente in generale, vedere Continuare l'attività degli utenti, anche tra i dispositivi. Per consigli su quando creare o aggiornare le attività, vedere la guida alle procedure consigliate per le attività utente .

Con il Project Rome SDK, la tua app Android non solo può pubblicare attività dell'utente per l'uso in funzionalità di Windows, ad esempio Sequenza temporale, ma può anche fungere da endpoint e leggere attività all'utente esattamente come fa Sequenza temporale sui dispositivi Windows. Ciò consente alle app tra dispositivi di superare le piattaforme e offrire esperienze che seguono gli utenti anziché i dispositivi.

Vedere la pagina di riferimento dell'API per i collegamenti alla documentazione di riferimento pertinente per questi scenari.

Questa procedura seguente farà riferimento al codice dell'app di esempio Project Rome Android.

Per tutte le funzionalità dei dispositivi connessi, è necessario un IDE di sviluppo di app Android e un dispositivo Android con una delle architetture supportate (armeabi-v7a, arm64-v8a, x86 o x86_64) o un emulatore. Il sistema deve eseguire Android 4.4.2 o versione successiva.

Configurazione preliminare per la piattaforma e le notifiche dei dispositivi connessi

Prima di implementare la connettività remota, è necessario eseguire alcuni passaggi per offrire all'app Android la possibilità di connettersi ai dispositivi remoti, nonché inviare e ricevere notifiche.

Registrare l'app

L'autenticazione dell'account Microsoft (MSA) o Di Azure Active Directory (AAD) è necessaria per quasi tutte le funzionalità di Project Rome SDK (l'eccezione è costituita dalle API di condivisione nelle vicinanze). Se non si dispone già di un account Microsoft e si desidera usarne uno, registrarsi su account.microsoft.com.

Annotazioni

Gli account Azure Active Directory (AAD) non sono supportati con le API di Inoltro dispositivi.

Usando il metodo di autenticazione scelto, è necessario registrare l'app con Microsoft seguendo le istruzioni nel portale di registrazione delle applicazioni. Se non si ha un account per sviluppatore Microsoft, è necessario crearne uno.

Quando si registra un'app utilizzando un account Microsoft, si dovrebbe ricevere una stringa ID client. Salvalo per più tardi. Ciò consentirà all'app di accedere alle risorse della piattaforma dispositivi connessi di Microsoft. Se si usa AAD, vedere Librerie di autenticazione di Azure Active Directory per istruzioni su come ottenere la stringa ID client.

Aggiungere l'SDK

Inserisci i seguenti riferimenti al repository nel file build.gradle nella directory principale del tuo progetto.

allprojects {
    repositories {
        jcenter()
    }
}

Inserire quindi la dipendenza seguente nel file build.gradle presente nella cartella del progetto.

dependencies { 
    ...
    implementation 'com.microsoft.connecteddevices:connecteddevices-sdk:+'
}

Nel file diAndroidManifest.xml del progetto aggiungere le autorizzazioni seguenti all'interno dell'elemento <manifest> (se non sono già presenti). Ciò consente all'app di connettersi a Internet e di abilitare l'individuazione Bluetooth nel dispositivo.

Si noti che le autorizzazioni correlate al Bluetooth sono necessarie solo per l'uso dell'individuazione Bluetooth; non sono necessarie per le altre funzionalità della piattaforma dispositivi connessi. Inoltre, ACCESS_COARSE_LOCATION è necessario solo negli SDK Android 21 e versioni successive. Negli SDK Android 23 e versioni successive, lo sviluppatore deve anche chiedere all'utente di concedere l'accesso alla posizione in fase di esecuzione.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Passare quindi alla classe di attività (es) in cui si vuole che la funzionalità Dispositivi connessi sia attiva. Importare i pacchetti seguenti.

import com.microsoft.connecteddevices;
import com.microsoft.connecteddevices.remotesystems;
import com.microsoft.connecteddevices.remotesystems.commanding;

Configurare l'autenticazione e la gestione degli account

La piattaforma dispositivi connessi richiede un token OAuth valido da usare nel processo di registrazione. È possibile usare il metodo preferito per generare e gestire i token OAuth. Tuttavia, per aiutare gli sviluppatori a iniziare a usare la piattaforma, è stato incluso un provider di autenticazione come parte dell'app di esempio Android che genera e gestisce i token di aggiornamento per praticità.

Se si vuole implementare manualmente l'interfaccia ConnectedDevicesAccountManager , prendere nota delle informazioni seguenti:

Se si usa un account Microsoft, è necessario includere gli ambiti seguenti nella richiesta di accesso: "wl.offline_access", "ccs.ReadWrite", "dds.read", "dds.register", "wns.connect", "asimovrome.telemetry" e "https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp".

Se si usa un account AAD, è necessario richiedere i destinatari seguenti: "https://cdpcs.access.microsoft.com", "https://cs.dds.microsoft.com", "https://wns.windows.com/"e "https://activity.microsoft.com".

Annotazioni

Gli account Azure Active Directory (AAD) non sono supportati con le API di Inoltro dispositivi.

Se si usa o meno l'implementazione connectedDevicesAccountManager fornita, se si usa AAD è necessario specificare le autorizzazioni seguenti nella registrazione dell'app nel portale di Azure (portal.azure.com > registrazioni dell'app di Azure Active Directory > ):

Servizio feed attività Microsoft
- Consegnare e modificare le notifiche dell'utente per questa app
- Leggi e scrivi l'attività dell'app nel feed delle attività degli utenti
Servizio di notifica di Windows
- Connettere il dispositivo al servizio di notifica di Windows
Servizio Microsoft Device Directory
- Visualizzare l'elenco dei dispositivi
- Essere aggiunto all'elenco di dispositivi e app
Servizio comandi Microsoft
- Comunicare con i dispositivi utente
- Leggere i dispositivi degli utenti

Registrare l'app per le notifiche push

Registra la tua applicazione presso Google per il supporto di Firebase Cloud Messaging. Assicurarsi di prendere nota dell'ID mittente e della chiave del server ricevuta; saranno necessari in un secondo momento.

Dopo la registrazione, è necessario associare la funzionalità di notifica push alla piattaforma dispositivi connessi nell'app.

mNotificationRegistration = new ConnectedDevicesNotificationRegistration();
mNotificationRegistration.setType(ConnectedDevicesNotificationType.FCM);
mNotificationRegistration.setToken(token);
mNotificationRegistration.setAppId(Secrets.FCM_SENDER_ID);
mNotificationRegistration.setAppDisplayName("SampleApp");

Registrare l'app in Microsoft Windows Dev Center per le esperienze tra dispositivi

Importante

Questo passaggio è necessario solo se si vogliono usare le funzionalità di Project Rome per accedere ai dati da o effettuare richieste di dispositivi non Windows. Se si specifica come destinazione solo i dispositivi Windows, non è necessario completare questo passaggio.

Passare a Dashboard di Dev Center, passare a Esperienze tra dispositivi dal riquadro di spostamento a sinistra e selezionare configurazione di una nuova app tra dispositivi, come illustrato di seguito. Dashboard di Dev Center - Esperienze tra dispositivi

Il processo di onboarding di Dev Center richiede i passaggi seguenti:

Selezionare le piattaforme supportate: selezionare le piattaforme in cui l'app avrà una presenza e essere abilitata per le esperienze tra dispositivi. Nel caso dell'integrazione di Graph Notifications, è possibile selezionare da Windows, Android e/o iOS.
Specificare gli ID app: specificare gli ID app per ogni piattaforma in cui l'app ha una presenza. Per le app Android, questo è il nome del pacchetto assegnato all'app al momento della creazione del progetto. Il nome del pacchetto è disponibile nella console Firebase sotto Panoramica del Progetto -> Generale. È possibile aggiungere ID diversi (fino a dieci) per ogni piattaforma: in questo caso si dispone di più versioni della stessa app o anche di app diverse, che vogliono essere in grado di ricevere le stesse notifiche inviate dal server app destinato allo stesso utente.
Specificare o selezionare gli ID delle app dalle registrazioni delle app MSA e/o AAD. Questi ID client, corrispondenti alla registrazione dell'app MSA o AAD, sono stati ottenuti nei passaggi precedenti di registrazione dell'app MSA/AAD.
Graph Notifications e altre funzionalità della piattaforma dispositivi connessi sfruttano ognuna delle piattaforme di notifica native su piattaforme principali per inviare notifiche agli endpoint client dell'app, vale a dire WNS (per Windows UWP), FCM (per Android) e APNS (per iOS). Specificare le credenziali per queste piattaforme di notifica per consentire a Graph Notifications di recapitare le notifiche per il server app quando si pubblicano notifiche mirate agli utenti. Per Android, l'abilitazione del servizio Di messaggistica cloud è un prerequisito per l'uso delle notifiche di Microsoft Graph. Si noti inoltre che l'ID mittente richiesto corrisponde all'ID mittente di Firebase Cloud Messaging e la chiave API corrisponde alla chiave del server legacy. Entrambi sono disponibili in Firebase Console -> Progetto -> Impostazioni, nella scheda Messaggistica cloud, come illustrato nello screenshot.
L'ultimo passaggio consiste nel verificare il dominio dell'app tra dispositivi, che funge da processo di verifica per dimostrare che l'app ha la proprietà di questo dominio che agisce come un'identità dell'app tra dispositivi per l'app registrata.

Uso della piattaforma

Creare la piattaforma

Per iniziare, è sufficiente avviare la piattaforma.

ConnectedDevicesPlatform sPlatform = new ConnectedDevicesPlatform(context);

La piattaforma richiede un utente autenticato per accedere alla piattaforma. È necessario sottoscrivere gli eventi ConnectedDevicesAccountManager per assicurarsi che venga usato un account valido.

 ConnectedDevicesPlatform sPlatform.getAccountManager().accessTokenRequested().subscribe((accountManager, args) -> {

    // Get access token
}

 ConnectedDevicesPlatform sPlatform.getAccountManager().accessTokenInvalidated().subscribe((accountManager, args) -> {

    // Refresh and renew existing access token
}

Analogamente, la piattaforma usa le notifiche per recapitare comandi tra i dispositivi. Pertanto, è necessario sottoscrivere gli eventi ConnectedDevicesNotificationRegistrationManager per assicurarsi che gli stati di registrazione cloud siano validi per l'account in uso. Verificare lo stato usando ConnectedDevicesNotificationRegistrationState

ConnectedDevicesPlatform sPlatform.getNotificationRegistrationManager().notificationRegistrationStateChanged().subscribe((notificationRegistrationManager, args) -> {
    
     // Check state using ConnectedDevicesNotificationRegistrationState enum

}

Avviare la piattaforma

Ora che la piattaforma è inizializzata e che sono presenti gestori eventi, è possibile iniziare a individuare i dispositivi di sistema remoti.

ConnectedDevicesPlatform sPlatform.start();

Recuperare gli account utente noti all'app

È importante assicurarsi che l'elenco di account utente noti all'app sia sincronizzato correttamente con ConnectedDevicesAccountManager.

Usare ConnectedDevicesAccountManager.addAccountAsync per aggiungere un nuovo account utente.

 public synchronized AsyncOperation<ConnectedDevicesAddAccountResult> addAccountToAccountManagerAsync(ConnectedDevicesAccount account) {
        return ConnectedDevicesPlatform sPlatform.getAccountManager().addAccountAsync(account);
    }

Per rimuovere un account non valido, è possibile usare ConnectedDevicesAccountManager.removeAccountAsync

 public synchronized AsyncOperation<ConnectedDevicesAddAccountResult> removeAccountToAccountManagerAsync(ConnectedDevicesAccount account) {
        return ConnectedDevicesPlatform sPlatform.getAccountManager().removeAccountAsync(account);
    }

Inizializzare un canale attività utente

Per implementare le funzionalità dell'attività utente nella tua app, dovrai prima inizializzare il feed di attività utente creando un UserActivityChannel. È consigliabile trattarlo come il passaggio di inizializzazione della piattaforma precedente: deve essere controllato ed eventualmente ripetere ogni volta che l'app viene in primo piano (ma non prima dell'inizializzazione della piattaforma).

Avrai bisogno anche del tuo ID app multipiattaforma, ottenuto tramite la registrazione al Dashboard per sviluppatori di Microsoft. I metodi seguenti inizializzano UserActivityChannel.

private UserActivityChannel mActivityChannel;
private UserDataFeed mUserDataFeed;

// ...

/**
 * Initializes the UserActivityFeed.
 */
public void initializeUserActivityFeed() {

    // define what scope of data this app needs
    SyncScope[] scopes = { UserActivityChannel.getSyncScope(), UserNotificationChannel.getSyncScope() };

    // Get a reference to the UserDataFeed. This method is defined below
    mUserDataFeed = getUserDataFeed(scopes, new EventListener<UserDataFeed, Void>() {
        @Override
        public void onEvent(UserDataFeed userDataFeed, Void aVoid) {
            if (userDataFeed.getSyncStatus() == UserDataSyncStatus.SYNCHRONIZED) {
                // log synchronized.
            } else {
                // log synchronization not completed.
            }
        }
    });

    // this method is defined below
    mActivityChannel = getUserActivityChannel();
}

// instantiate the UserDataFeed
private UserDataFeed getUserDataFeed(SyncScope[] scopes, EventListener<UserDataFeed, Void> listener) {
    UserAccount[] accounts = AccountProviderBroker.getSignInHelper().getUserAccounts();
    if (accounts.length <= 0) {
        // notify the user that sign-in is required
        return null;
    }

    // use the initialized Platform instance, along with the cross-device app ID.
    UserDataFeed feed = UserDataFeed.getForAccount(accounts[0], PlatformBroker.getPlatform(), Secrets.APP_HOST_NAME);
    feed.addSyncStatusChangedListener(listener);
    feed.addSyncScopes(scopes);
    // sync data with the server
    feed.startSync();
    return feed;
}

// use the UserDataFeed reference to create a UserActivityChannel
@Nullable
private UserActivityChannel getUserActivityChannel() {
    UserActivityChannel channel = null;
    try {
        // create a UserActivityChannel for the signed in account
        channel = new UserActivityChannel(mUserDataFeed);
    } catch (Exception e) {
        e.printStackTrace();
        // handle exception
    }
    return channel;
}

A questo punto, è necessario avere un riferimento UserActivityChannel in mActivityChannel.

Creare e pubblicare un'attività utente

Impostare quindi i dati ID, DisplayText e ActivationURI di ciò che sarà un nuovo UserActivity. L'ID deve essere una stringa univoca. DisplayText verrà visualizzato in altri dispositivi quando visualizzano l'attività (ad esempio in Sequenza temporale di Windows), quindi dovrebbe essere una descrizione concisa dell'attività. ActivationUri determinerà l'azione eseguita quando l'oggetto UserActivity viene attivato (ad esempio, quando è selezionato in Sequenza temporale). Il codice seguente compila i dati di esempio per questi campi.

private UserActivity mActivity;
private String mActivityId;
private String mDisplayText;
private String mActivationUri;

// ...

mActivityId = UUID.randomUUID().toString();
mDisplayText = "Created by OneSDK Sample App";
mActivationUri = "http://contoso.com");

Specificare quindi un metodo che crea una nuova istanza di UserActivity .

// Create the UserActivity (with unique ID) using a custom method. 
mActivity = createUserActivity(mActivityChannel, mActivityId);

// ...

// Custom method for creating a new UserActivity
@Nullable
private UserActivity createUserActivity(UserActivityChannel channel, String activityId)
{
    UserActivity activity = null;
    AsyncOperation<UserActivity> activityOperation = channel.getOrCreateUserActivityAsync(activityId);
    try {
        activity = activityOperation.get();
        Log.d("UserActivityFragment","Created user activity successfully");
    } catch (Exception e) {
        e.printStackTrace();
        Log.d("UserActivityFragment","Created user activity successfully");
    }
    return activity;
}

Dopo aver creato l'istanza userActivity , popolarla con i dati definiti in precedenza.

//set the properties of the UserActivity:
// Display Text will be shown when the UserActivity is viewed on other devices
mActivity.getVisualElements().setDisplayText(mDisplayText);
// ActivationURI will determine what is launched when your UserActivity is activated from other devices
mActivity.setActivationUri(mActivationUri);

Infine, pubblicare l'attività nel cloud.

// This code saves and publishes the activity
AsyncOperation<Void> operation = mActivity.saveAsync();
operation.whenCompleteAsync(new AsyncOperation.ResultBiConsumer<Void, Throwable>() {
    @Override
    public void accept(Void aVoid, Throwable throwable) throws Throwable {
        if (throwable != null)
        {
            Log.d("UserActivityFragment", "Failed to save");
        } else {
            Log.d("UserActivityFragment", "User activity saved");
        }
    }
});

Suggerimento

Oltre alle proprietà precedenti, è possibile configurare molte altre funzionalità. Per un'analisi completa dei diversi modi in cui è possibile personalizzare userActivity, vedere le classi UserActivity, UserActivityVisualElements e UserActivityAttribution. Per indicazioni dettagliate su come progettare le attività utente, vedere la guida alle procedure consigliate per le attività utente.

Aggiornare un'attività utente esistente

Se si dispone di un'attività esistente e si desidera aggiornarne le informazioni (in caso di un nuovo engagement, pagina modificata e così via), è possibile farlo usando un UserActivitySession.

private UserActivitySession mActivitySession;

// ...

if (mActivity != null)
{
    // create a session from a previous UserActivity instance.
    mActivitySession = mActivity.createSession();
    Log.d("UserActivityFragment", "Starting");
}

Dopo aver creato una sessione, l'app può apportare le modifiche desiderate alle proprietà di UserActivity. Al termine dell'esecuzione delle modifiche, chiudere la sessione.

mActivitySession.close();
mActivitySession = null;
Log.d("UserActivityFragment", "Stopping");

UserActivitySession può essere considerato come un modo per creare un oggetto UserActivitySessionHistoryItem (illustrato nella sezione successiva). Invece di creare un nuovo UserActivity ogni volta che un utente passa a una nuova pagina, è sufficiente creare una nuova sessione per ogni pagina. Questo renderà l'esperienza di lettura dell'attività più intuitiva e organizzata.

Leggere le attività utente

L'app può leggere Le attività utente e presentarle all'utente esattamente come avviene con la funzionalità Sequenza temporale di Windows. Per configurare la lettura dell'attività utente, usare la stessa istanza di UserActivityChannel precedente. Questa istanza può esporre istanze UserActivitySessionHistoryItem , che rappresentano l'engagement di un utente in una determinata attività durante un periodo di tempo specifico.

private ArrayList<UserActivitySessionHistoryItem> mHistoryItems; 

// ...

mHistoryItems.clear();

Log.d("UserActivityFragment", "Read");
//Async method to read activities. Last (most recent) 5 activities will be returned
AsyncOperation<UserActivitySessionHistoryItem[]> operation = mActivityChannel.getRecentUserActivitiesAsync(5);

operation.whenCompleteAsync(new AsyncOperation.ResultBiConsumer<UserActivitySessionHistoryItem[], Throwable>() {
    @Override
    public void accept(UserActivitySessionHistoryItem[] result, Throwable throwable) throws Throwable {
        if (throwable != null)
        {
            Log.d("UserActivityFragment", "Failed to read user activity!" + throwable.getMessage() + " " + throwable.getStackTrace());
        } else {
            // get the returned UserActivitySessionHistoryItems
            for (UserActivitySessionHistoryItem item : result)
            {
                mHistoryItems.add(item);
            }
        }
    }
});

Ora l'app dovrebbe avere un elenco popolato di UserActivitySessionHistoryItems. Ognuno di questi può fornire l'oggetto UserActivity sottostante (vedere UserActivitySessionHistoryItem per informazioni dettagliate), che puoi quindi mostrare all'utente.