Implementieren von Benutzeraktivitäten für Android

2025-06-10

Benutzeraktivitäten sind Datenkonstrukte, die die Aufgaben eines Benutzers innerhalb einer Anwendung darstellen. Sie ermöglichen es, eine Momentaufnahme einer Aufgabe zu speichern, die zu einem späteren Zeitpunkt fortgesetzt werden kann. Die Windows-Zeitachse präsentiert Windows-Benutzern eine scrollbare Liste all ihrer jüngsten Aktivitäten, dargestellt als Karten mit Text und Grafiken. Weitere Informationen zu Benutzeraktivitäten im Allgemeinen finden Sie unter "Benutzeraktivitäten fortsetzen" auch auf allen Geräten. Empfehlungen zum Erstellen oder Aktualisieren von Aktivitäten finden Sie im Leitfaden zu bewährten Methoden für Benutzeraktivitäten .

Mit dem Project Rome SDK kann Ihre Android-App nicht nur Benutzeraktivitäten für die Verwendung in Windows-Features wie Zeitachse veröffentlichen, sondern auch als Endpunkt fungieren und Aktivitäten wieder an den Benutzer lesen, genauso wie die Zeitachse auf Windows-Geräten. Auf diese Weise können geräteübergreifende Apps ihre Plattformen überschreiten und Erlebnisse bieten, die den Nutzern folgen und nicht den Geräten.

Links zu den Referenzdokumenten, die für diese Szenarien relevant sind, finden Sie auf der API-Referenzseite .

In den folgenden Schritten wird auf Code aus der Project Rome Android-Beispiel-App verwiesen.

Für alle Features mit verbundenen Geräten benötigen Sie eine Android-App-Entwicklungs-IDE und ein Android-Gerät mit einer der unterstützten Architekturen (armeabi-v7a, arm64-v8a, x86 oder x86_64) oder einem Emulator. Auf dem System muss Android (4.4.2) oder höher ausgeführt werden.

Vorläufige Einrichtung der Plattform für verbundene Geräte und Benachrichtigungen

Bevor Sie remotekonnektivität implementieren, müssen Sie einige Schritte ausführen, um Ihrer Android-App die Möglichkeit zu geben, eine Verbindung mit Remotegeräten herzustellen sowie Benachrichtigungen zu senden und zu empfangen.

Registrieren Ihrer App

Die Authentifizierung von Microsoft-Konten (MSA) oder Azure Active Directory (AAD) ist für fast alle Features des Project Rome SDK erforderlich (die Ausnahme ist die Naheliegende Freigabe-APIs). Wenn Sie noch keine MSA besitzen und eins verwenden möchten, registrieren Sie sich bei account.microsoft.com.

Hinweis

Azure Active Directory (AAD)-Konten werden mit den Device Relay-APIs nicht unterstützt.

Mit Ihrer gewählten Authentifizierungsmethode müssen Sie Ihre App bei Microsoft registrieren, indem Sie die Anweisungen im Anwendungsregistrierungsportal befolgen. Wenn Sie nicht über ein Microsoft-Entwicklerkonto verfügen, müssen Sie ein Konto erstellen.

Wenn Sie eine App mit einem MSA registrieren, sollten Sie eine Client-ID-Zeichenfolge erhalten. Speichern Sie dies für später. Dadurch kann Ihre App auf die Ressourcen der Plattform für verbundene Geräte von Microsoft zugreifen. Wenn Sie AAD verwenden, finden Sie Anweisungen zum Abrufen der Client-ID-Zeichenfolge unter Azure Active Directory-Authentifizierungsbibliotheken .

Hinzufügen des SDK

Fügen Sie die folgenden Repository-Referenzen in die build.gradle-Datei am Stamm Ihres Projekts ein.

allprojects {
    repositories {
        jcenter()
    }
}

Fügen Sie dann die folgende Abhängigkeit in die build.gradle-Datei ein, die sich in Ihrem Projektordner befindet.

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

Fügen Sie in der AndroidManifest.xml-Datei Ihres Projekts folgende Berechtigungen innerhalb des <manifest>-Elements hinzu (sofern sie nicht bereits vorhanden sind). Dadurch erhält Ihre App die Berechtigung zum Herstellen einer Verbindung mit dem Internet und zum Aktivieren der Bluetooth-Erkennung auf Ihrem Gerät.

Beachten Sie, dass die Bluetooth-bezogenen Berechtigungen nur für die Verwendung der Bluetooth-Erkennung erforderlich sind. Sie sind für die anderen Features auf der Plattform für verbundene Geräte nicht erforderlich. Des Weiteren ist ACCESS_COARSE_LOCATION nur auf Android-SDKs ab 21 und höher erforderlich. Auf Android SDKs 23 und höher muss der Entwickler auch den Benutzer auffordern, standortzugriff zur Laufzeit zu gewähren.

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

Wechseln Sie als Nächstes zu der Aktivitätsklasse(n), in der Sie die Funktion "Verbundene Geräte" live nutzen möchten. Importieren Sie die folgenden Pakete.

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

Einrichten von Authentifizierung und Kontoverwaltung

Die Plattform für verbundene Geräte erfordert ein gültiges OAuth-Token, das im Registrierungsprozess verwendet werden muss. Sie können Ihre bevorzugte Methode zum Generieren und Verwalten der OAuth-Token verwenden. Um Entwicklern jedoch den Einstieg in die Plattform zu erleichtern, haben wir einen Authentifizierungsanbieter als Teil der Android-Beispiel-App aufgenommen, die Aktualisierungstoken generiert und verwaltet.

Wenn Sie die ConnectedDevicesAccountManager-Schnittstelle selbst implementieren möchten, beachten Sie die folgenden Informationen:

Wenn Sie ein MSA verwenden, müssen Sie die folgenden Bereiche in Ihre Anmeldeanforderung einschließen: "wl.offline_access", , , "ccs.ReadWrite", , "dds.read", "dds.register", "wns.connect", , "asimovrome.telemetry"und "https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp".

Wenn Sie ein AAD-Konto verwenden, müssen Sie die folgenden Zielgruppen anfordern: "https://cdpcs.access.microsoft.com", , , "https://cs.dds.microsoft.com", "https://wns.windows.com/"und "https://activity.microsoft.com".

Hinweis

Azure Active Directory (AAD)-Konten werden mit den Device Relay-APIs nicht unterstützt.

Ob Sie die bereitgestellte ConnectedDevicesAccountManager-Implementierung verwenden oder nicht, wenn Sie AAD verwenden, müssen Sie die folgenden Berechtigungen in der Registrierung Ihrer App im Azure-Portal angeben (portal.azure.com > Azure Active Directory > App-Registrierungen):

Microsoft-Aktivitätsfeeddienst
- Bereitstellen und Ändern von Benutzerbenachrichtigungen für diese App
- Lesen und Schreiben der App-Aktivität in den Aktivitätsfeed der Benutzer
Windows-Benachrichtigungsdienst
- Verbinden Ihres Geräts mit dem Windows-Benachrichtigungsdienst
Microsoft Device Directory Service
- Anzeigen Ihrer Geräteliste
- Werden Sie Ihrer Liste der Geräte und Apps hinzugefügt.
Microsoft Command Service
- Kommunikation mit Benutzergeräten
- Benutzergeräte lesen

Registrieren der App für Pushbenachrichtigungen

Registrieren Sie Ihre Anwendung bei Google für die Unterstützung von Firebase Cloud Messaging . Notieren Sie sich unbedingt die Absender-ID und den Serverschlüssel, den Sie erhalten; Sie benötigen sie später.

Nach der Registrierung müssen Sie pushbenachrichtigungsfunktionen der Plattform für verbundene Geräte in Ihrer App zuordnen.

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

Registrieren Ihrer App im Microsoft Windows Dev Center für geräteübergreifende Oberflächen

Von Bedeutung

Dieser Schritt ist nur erforderlich, wenn Sie Project Rome-Features verwenden möchten, um auf Daten von Nicht-Windows-Geräten zuzugreifen oder Anforderungen an Nicht-Windows-Geräte zu stellen. Wenn Sie nur auf Windows-Geräte abzielen, müssen Sie diesen Schritt nicht ausführen.

Wechseln Sie zum Dev Center-Dashboard, navigieren Sie im linken Navigationsbereich zu geräteübergreifenden Erfahrungen, und wählen Sie die Konfiguration einer neuen geräteübergreifenden App aus, die wie unten dargestellt wird. Dev Center-Dashboard – Geräteübergreifende Erfahrungen

Der Dev Center-Onboardingprozess erfordert die folgenden Schritte:

Wählen Sie unterstützte Plattformen aus – wählen Sie die Plattformen aus, auf denen Ihre App über eine Anwesenheit verfügt und für geräteübergreifende Erfahrungen aktiviert ist. Bei der Graph-Benachrichtigungsintegration können Sie unter Windows, Android und/oder iOS auswählen.
Bereitstellen von App-IDs – Stellen Sie App-IDs für jede Plattform bereit, auf der Ihre App über eine Anwesenheit verfügt. Bei Android-Apps ist dies der Paketname, den Sie Ihrer App zugewiesen haben, wenn Sie das Projekt erstellt haben. Der Paketname befindet sich in Ihrer Firebase-Konsole unter "Projektübersicht "> Allgemein". Sie können unterschiedliche IDs (bis zu zehn) pro Plattform hinzufügen– dies ist der Fall, wenn Sie über mehrere Versionen derselben App oder sogar über verschiedene Apps verfügen, die dieselben Benachrichtigungen empfangen möchten, die von Ihrem App-Server gesendet werden, die auf denselben Benutzer ausgerichtet sind.
Geben Sie die App-IDs aus den MSA- und/oder AAD-App-Registrierungen an oder wählen Sie sie aus. Diese Client-IDs, die MSA- oder AAD-App-Registrierung entsprechen, wurden in den vorherigen MSA/AAD-App-Registrierungsschritten von oben abgerufen.
Graph-Benachrichtigungen und andere Fähigkeiten der Connected Devices-Plattform nutzen jeweils die nativen Benachrichtigungsplattformen auf den großen Plattformen, um Benachrichtigungen an die App-Client-Endpunkte zu senden, nämlich WNS (für Windows UWP), FCM (für Android) und APNS (für iOS). Geben Sie Ihre Anmeldeinformationen für diese Benachrichtigungsplattformen an, damit Graph-Benachrichtigungen die Benachrichtigungen für Ihren App-Server bereitstellen können, wenn Sie benutzerorientierte Benachrichtigungen veröffentlichen. Für Android ist die Aktivierung des Cloud Messaging-Diensts eine Voraussetzung für die Verwendung von Microsoft Graph-Benachrichtigungen. Beachten Sie außerdem, dass die erforderliche Absender-ID der Firebase Cloud Messaging Sender ID entspricht, und der API-Schlüssel entspricht dem Legacy-Serverschlüssel. Beide finden Sie in der Firebase Console - Project –>> Einstellungen, auf der Registerkarte "Cloud Messaging", wie im Screenshot gezeigt.
Der letzte Schritt besteht darin, Ihre geräteübergreifende App-Domäne zu überprüfen, die als Überprüfungsprozess dient, um zu beweisen, dass Ihre App über den Besitz dieser Domäne verfügt, die wie eine geräteübergreifende App-Identität für die app fungiert, die Sie registriert haben.

Verwenden der Plattform

Erstellen der Plattform

Um zu beginnen, instanziieren Sie einfach die Plattform.

ConnectedDevicesPlatform sPlatform = new ConnectedDevicesPlatform(context);

Die Plattform erfordert einen authentifizierten Benutzer für den Zugriff auf die Plattform. Sie müssen ConnectedDevicesAccountManager-Ereignisse abonnieren, um sicherzustellen, dass ein gültiges Konto verwendet wird.

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

    // Get access token
}

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

    // Refresh and renew existing access token
}

Ebenso verwendet die Plattform Benachrichtigungen, um Befehle zwischen Geräten bereitzustellen. Daher müssen Sie die ConnectedDevicesNotificationRegistrationManager-Ereignisse abonnieren, um sicherzustellen, dass die Cloudregistrierungszustände für das verwendete Konto gültig sind. Überprüfen des Zustands mithilfe von ConnectedDevicesNotificationRegistrationState

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

}

Starten der Plattform

Nachdem die Plattform initialisiert ist und Ereignishandler vorhanden sind, können Sie mit der Ermittlung von Remotesystemgeräten beginnen.

ConnectedDevicesPlatform sPlatform.start();

Abrufen von Benutzerkonten, die der App bekannt sind

Es ist wichtig sicherzustellen, dass die Liste der Benutzerkonten, die der App bekannt sind, ordnungsgemäß mit dem ConnectedDevicesAccountManager synchronisiert werden.

Verwenden Sie ConnectedDevicesAccountManager.addAccountAsync , um ein neues Benutzerkonto hinzuzufügen.

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

Um ein ungültiges Konto zu entfernen, können Sie ConnectedDevicesAccountManager.removeAccountAsync verwenden

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

Initialisieren eines Benutzeraktivitätskanals

Um Benutzeraktivitätsfeatures in Ihrer App zu implementieren, müssen Sie zuerst den Benutzeraktivitätsfeed initialisieren, indem Sie einen UserActivityChannel erstellen. Sie sollten dies wie der oben beschriebene Plattforminitialisierungsschritt behandeln: Es sollte überprüft und möglicherweise erneut ausgeführt werden, wenn die App in den Vordergrund kommt (aber nicht vor der Plattforminitialisierung).

Außerdem benötigen Sie Ihre plattformübergreifende App-ID, die über die Microsoft Developer Dashboard-Registrierung abgerufen wurde. Die folgenden Methoden initialisieren einen 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;
}

An diesem Punkt sollten Sie über einen UserActivityChannel-Verweis in mActivityChannel verfügen.

Erstellen und Veröffentlichen einer Benutzeraktivität

Legen Sie als Nächstes die ID-, DisplayText- und ActivationURI-Daten für eine neue UserActivity fest. Die ID sollte eine eindeutige Zeichenfolge sein. Der DisplayText wird auf anderen Geräten angezeigt, wenn er die Aktivität (z. B. in der Windows-Zeitachse) anzeigt. Daher sollte es sich um eine präzise Beschreibung der Aktivität handeln. Die Aktivierungs-URI bestimmt, welche Aktion ausgeführt wird, wenn die UserActivity aktiviert wird (z. B. wenn sie in der Zeitachse ausgewählt ist). Der folgende Code füllt Beispieldaten für diese Felder aus.

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

Stellen Sie als Nächstes eine Methode bereit, mit der eine neue UserActivity-Instanz erstellt wird.

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

Sobald Sie die UserActivity-Instanz haben, füllen Sie sie mit den oben definierten Daten auf.

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

Veröffentlichen Sie schließlich die Aktivität in der 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");
        }
    }
});

Tipp

Zusätzlich zu den oben genannten Eigenschaften gibt es viele weitere Features, die konfiguriert werden können. Einen vollständigen Einblick in die verschiedenen Möglichkeiten, wie eine UserActivity angepasst werden kann, finden Sie unter den Klassen UserActivity, UserActivityVisualElements und UserActivityAttribution . Detaillierte Empfehlungen zum Entwerfen von Benutzeraktivitäten finden Sie im Leitfaden zu bewährten Methoden für Benutzeraktivitäten.

Aktualisieren einer vorhandenen Benutzeraktivität

Wenn Sie über eine vorhandene Aktivität verfügen und ihre Informationen aktualisieren möchten (im Falle eines neuen Engagements, einer geänderten Seite usw.), können Sie dies mithilfe einer UserActivitySession tun.

private UserActivitySession mActivitySession;

// ...

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

Nachdem Sie eine Sitzung erstellt haben, kann Ihre App alle gewünschten Änderungen an den Eigenschaften der UserActivity vornehmen. Wenn Sie mit dem Vornehmen von Änderungen fertig sind, schließen Sie die Sitzung.

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

Eine UserActivitySession kann als Eine Möglichkeit zum Erstellen eines UserActivitySessionHistoryItem (im nächsten Abschnitt behandelt) betrachtet werden. Anstatt jedes Mal, wenn ein Benutzer zu einer neuen Seite wechselt, eine neue Benutzeraktivität zu erstellen, können Sie einfach eine neue Sitzung für jede Seite erstellen. Dies wird zu einer intuitiveren und organisierteren Aktivitätsleseerfahrung führen.

Benutzeraktivitäten lesen

Ihre App kann Benutzeraktivitäten lesen und dem Benutzer genauso wie das Windows-Zeitachsenfeature präsentieren. Verwenden Sie zum Einrichten des Lesens von Benutzeraktivitäten dieselbe UserActivityChannel-Instanz aus früheren Versionen. Diese Instanz kann UserActivitySessionHistoryItem-Instanzen verfügbar machen, die das Engagement eines Benutzers in einer bestimmten Aktivität während eines bestimmten Zeitraums darstellen.

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

Jetzt sollte Ihre App über eine aufgefüllte Liste der UserActivitySessionHistoryItems verfügen. Jede dieser Elemente kann die zugrunde liegende UserActivity bereitstellen (details hierzu finden Sie unter UserActivitySessionHistoryItem ), die Sie dann dem Benutzer anzeigen können.