On-Demand-Auslieferung konfigurieren

Mit Funktionsmodulen können Sie bestimmte Funktionen und Ressourcen vom Basismodul Ihrer App trennen und in Ihr App-Bundle aufnehmen. Mit der Play-Funktionsbereitstellung können Nutzer diese Komponenten beispielsweise später bei Bedarf herunterladen und installieren, nachdem sie bereits das Basis-APK Ihrer App installiert haben.

Angenommen, Sie haben eine Messaging-App, die Funktionen zum Aufnehmen und Senden von Bildern enthält, aber nur ein kleiner Prozentsatz der Nutzer sendet Bildernachrichten. Es kann sinnvoll sein, Bildnachrichten als herunterladbares Funktionsmodul einzubinden. So ist der anfängliche App-Download für alle Nutzer kleiner und nur Nutzer, die Bildernachrichten senden, müssen diese zusätzliche Komponente herunterladen.

Diese Art der Modularisierung erfordert mehr Aufwand und möglicherweise eine Umstrukturierung des vorhandenen Codes Ihrer App. Überlegen Sie daher sorgfältig, welche Funktionen Ihrer App am meisten davon profitieren würden, wenn sie Nutzern auf Anfrage zur Verfügung gestellt werden. Weitere Informationen zu optimalen Anwendungsfällen und Richtlinien für On-Demand-Funktionen finden Sie unter UX-Best Practices für die On-Demand-Auslieferung.

Wenn Sie App-Funktionen nach und nach modularisieren möchten, ohne erweiterte Bereitstellungsoptionen wie die On-Demand-Bereitstellung zu aktivieren, konfigurieren Sie stattdessen die Bereitstellung zur Installationszeit.

Auf dieser Seite erfahren Sie, wie Sie Ihrem App-Projekt ein Funktionsmodul hinzufügen und für die On-Demand-Auslieferung konfigurieren. Bevor Sie beginnen, müssen Sie Android Studio 3.5 oder höher und das Android Gradle-Plug-in 3.5.0 oder höher verwenden.

Neues Modul für die Bereitstellung auf Abruf konfigurieren

Am einfachsten erstellen Sie ein neues Funktionsmodul mit Android Studio 3.5 oder höher. Da Funktionsmodule inhärent vom Basis-App-Modul abhängig sind, können Sie sie nur zu bereits vorhandenen App-Projekten hinzufügen.

So fügen Sie Ihrem App-Projekt mit Android Studio ein Funktionsmodul hinzu:

1. Öffnen Sie Ihr App-Projekt in der IDE, falls Sie dies noch nicht getan haben.
2. Wählen Sie in der Menüleiste Datei > Neu > Neues Modul aus.
3. Wählen Sie im Dialogfeld Neues Modul erstellen die Option Dynamic Feature Module aus und klicken Sie auf Weiter.
4. Führen Sie im Abschnitt Neues Modul konfigurieren die folgenden Schritte aus:
   1. Wählen Sie im Drop-down-Menü das Basis-Anwendungsmodul für Ihr App-Projekt aus.
   2. Geben Sie einen Modulnamen an. Anhand dieses Namens identifiziert die IDE das Modul als Gradle-Unterprojekt in der Gradle-Konfigurationsdatei. Wenn Sie Ihr App-Bundle erstellen, verwendet Gradle das letzte Element des Namens des Unterprojekts, um das <manifest split>-Attribut in das Manifest des Funktionsmoduls einzufügen.
   3. Geben Sie den Paketnamen des Moduls an. Standardmäßig schlägt Android Studio einen Paketnamen vor, der den Namen des Stammpakets des Basismoduls mit dem Modulnamen kombiniert, den Sie im vorherigen Schritt angegeben haben.
   4. Wählen Sie die Mindest-API-Ebene aus, die das Modul unterstützen soll. Dieser Wert sollte mit dem des Basismoduls übereinstimmen.
5. Klicken Sie auf Weiter.

6. Führen Sie im Bereich Downloadoptionen für Module folgende Schritte aus:

   1. Geben Sie den Modultitel mit bis zu 50 Zeichen an. Die Plattform verwendet diesen Titel, um das Modul für Nutzer zu identifizieren, wenn sie beispielsweise bestätigen, dass sie das Modul herunterladen möchten. Aus diesem Grund muss das Basismodul Ihrer App den Modultitel als Stringressource enthalten, die Sie übersetzen können. Wenn Sie das Modul mit Android Studio erstellen, fügt die IDE dem Basismodul die Stringressource hinzu und fügt den folgenden Eintrag in das Manifest des Funktionsmoduls ein:

      <dist:module
          ...
          dist:title="@string/feature_title">
      </dist:module>
      

      Hinweis: Wenn Sie die Ressourcenkomprimierung aktivieren, z. B. für Ihre Release-Builds, entfernt der Komprimierungstool möglicherweise die Stringressource „Modultitel“, wenn der Code in Ihrem Basismodul nicht darauf verweist. Damit die Stringressource in der Build-Ausgabe verbleibt, nehmen Sie sie in eine benutzerdefinierte Datei zum Beibehalten von Ressourcen auf.

   2. Wählen Sie im Drop-down-Menü unter Einschluss bei der Installation die Option Modul bei der Installation nicht einschließen aus. Android Studio fügt das Folgende in das Manifest des Moduls ein, um Ihre Auswahl widerzuspiegeln:

      <dist:module ... >
        <dist:delivery>
            <dist:on-demand/>
        </dist:delivery>
      </dist:module>
      

   3. Klicken Sie das Kästchen neben Zusammenführen an, wenn dieses Modul auf Geräten mit Android 4.4 (API-Level 20) und niedriger verfügbar sein und in Multi-APKs enthalten sein soll. Sie können also das On-Demand-Verhalten für dieses Modul aktivieren und die Zusammenführung deaktivieren, um es auf Geräten zu entfernen, die das Herunterladen und Installieren von unterteilten APKs nicht unterstützen. Android Studio fügt das Folgende in das Manifest des Moduls ein, um Ihre Auswahl widerzuspiegeln:

      <dist:module ...>
          <dist:fusing dist:include="true | false" />
      </dist:module>
      

7. Klicken Sie auf Fertig.

Nachdem Android Studio das Modul erstellt hat, können Sie den Inhalt im Bereich Project (Projekt) prüfen. Wählen Sie dazu in der Menüleiste View > Tool Windows > Project (Ansicht > Toolfenster > Projekt) aus. Der Standardcode, die Ressourcen und die Organisation sollten denen des Standard-App-Moduls ähneln.

Als Nächstes müssen Sie die On-Demand-Installationsfunktion mit der Play Feature Delivery-Bibliothek implementieren.

Play Feature Delivery-Bibliothek in Ihr Projekt aufnehmen

Bevor Sie beginnen können, müssen Sie Ihrem Projekt zuerst die Play Feature Delivery Library hinzufügen.

On-Demand-Modul anfordern

Wenn Ihre App ein Funktionsmodul verwenden muss, kann sie dies über die Klasse SplitInstallManager tun, während sie sich im Vordergrund befindet. Bei einer Anfrage muss Ihre App den Namen des Moduls angeben, wie er durch das split-Element im Manifest des Zielmoduls definiert ist. Wenn Sie mit Android Studio ein Funktionsmodul erstellen, verwendet das Build-System den von Ihnen angegebenen Modulnamen, um diese Eigenschaft zur Kompilierungszeit in das Manifest des Moduls einzufügen. Weitere Informationen finden Sie unter Manifeste für Funktionsmodule.

Angenommen, eine App hat ein On-Demand-Modul, mit dem über die Kamera des Geräts Bilder aufgenommen und Nachrichten gesendet werden können. Dieses On-Demand-Modul gibt in seinem Manifest split="pictureMessages" an. Im folgenden Beispiel wird über SplitInstallManager das pictureMessages-Modul (zusammen mit einem zusätzlichen Modul für einige Angebotsfilter) angefordert:

Kotlin

// Creates an instance of SplitInstallManager.
val splitInstallManager = SplitInstallManagerFactory.create(context)

// Creates a request to install a module.
val request =
    SplitInstallRequest
        .newBuilder()
        // You can download multiple on demand modules per
        // request by invoking the following method for each
        // module you want to install.
        .addModule("pictureMessages")
        .addModule("promotionalFilters")
        .build()

splitInstallManager
    // Submits the request to install the module through the
    // asynchronous startInstall() task. Your app needs to be
    // in the foreground to submit the request.
    .startInstall(request)
    // You should also be able to gracefully handle
    // request state changes and errors. To learn more, go to
    // the section about how to Monitor the request state.
    .addOnSuccessListener { sessionId -> ... }
    .addOnFailureListener { exception ->  ... }

Java

// Creates an instance of SplitInstallManager.
SplitInstallManager splitInstallManager =
    SplitInstallManagerFactory.create(context);

// Creates a request to install a module.
SplitInstallRequest request =
    SplitInstallRequest
        .newBuilder()
        // You can download multiple on demand modules per
        // request by invoking the following method for each
        // module you want to install.
        .addModule("pictureMessages")
        .addModule("promotionalFilters")
        .build();

splitInstallManager
    // Submits the request to install the module through the
    // asynchronous startInstall() task. Your app needs to be
    // in the foreground to submit the request.
    .startInstall(request)
    // You should also be able to gracefully handle
    // request state changes and errors. To learn more, go to
    // the section about how to Monitor the request state.
    .addOnSuccessListener(sessionId -> { ... })
    .addOnFailureListener(exception -> { ... });

Wenn Ihre App ein Modul anfordert, das nicht bei der Installation ausgeliefert wurde, wird die Aufforderung zum Download durch die Play Feature Delivery Library an die Plattform weitergeleitet. Das bedeutet, dass die Anfrage zum Herunterladen des Moduls an die Plattform gesendet wird, aber nicht überwacht wird, ob die Installation erfolgreich war. Wenn Sie den User Flow nach der Installation fortsetzen oder Fehler ordnungsgemäß verarbeiten möchten, müssen Sie den Anfragestatus beobachten.

Hinweis:Sie können auch ein Funktionsmodul anfordern, das bereits auf dem Gerät installiert ist. Die API betrachtet die Anfrage sofort als abgeschlossen, wenn sie erkennt, dass das Modul bereits installiert ist. Außerdem wird ein Modul nach der Installation automatisch von Google Play aktualisiert. Wenn Sie also eine neue Version Ihres App-Bundles hochladen, aktualisiert die Plattform alle installierten APKs, die zu Ihrer App gehören. Weitere Informationen finden Sie unter App-Updates verwalten.

Damit Ihre App auf den Code und die Ressourcen des Moduls zugreifen kann, muss SplitCompat aktiviert sein. Für Android Instant Apps ist SplitCompat nicht erforderlich.

Installation von On-Demand-Modulen verschieben

Wenn ein On-Demand-Modul nicht sofort mit deiner App heruntergeladen und installiert werden soll, kannst du die Installation auf einen Zeitpunkt verschieben, an dem die App im Hintergrund ausgeführt wird. Dies eignet sich besonders gut für im Voraus geladene Werbematerialien, die bei einem späteren App-Start ausgeliefert werden.

Sie können ein Modul mit der Methode deferredInstall() angeben, um es später herunterzuladen, wie unten gezeigt. Im Gegensatz zu SplitInstallManager.startInstall() muss Ihre App nicht im Vordergrund sein, um eine Anfrage für eine verzögerte Installation zu starten.

Kotlin

// Requests an on demand module to be downloaded when the app enters
// the background. You can specify more than one module at a time.
splitInstallManager.deferredInstall(listOf("promotionalFilters"))

Java

// Requests an on demand module to be downloaded when the app enters
// the background. You can specify more than one module at a time.
splitInstallManager.deferredInstall(Arrays.asList("promotionalFilters"));

Anfragen für verzögerte Installationen werden auf Best-Effort-Basis ausgeführt und Sie können den Fortschritt nicht verfolgen. Bevor Sie also versuchen, auf ein Modul zuzugreifen, das Sie für die verzögerte Installation angegeben haben, sollten Sie prüfen, ob das Modul installiert wurde. Wenn das Modul sofort verfügbar sein muss, verwenden Sie stattdessen SplitInstallManager.startInstall(), um es anzufordern, wie im vorherigen Abschnitt gezeigt.

Status der Anfrage prüfen

Wenn Sie eine Fortschrittsanzeige aktualisieren, nach der Installation einen Intent auslösen oder einen Fehler bei einer Anfrage ordnungsgemäß verarbeiten möchten, müssen Sie auf Statusaktualisierungen von der asynchronen SplitInstallManager.startInstall()-Aufgabe warten. Bevor Sie Updates für Ihre Installationsanfrage erhalten können, müssen Sie einen Listener registrieren und die Sitzungs-ID für die Anfrage abrufen, wie unten gezeigt.

Kotlin

// Initializes a variable to later track the session ID for a given request.
var mySessionId = 0

// Creates a listener for request status updates.
val listener = SplitInstallStateUpdatedListener { state ->
    if (state.sessionId() == mySessionId) {
      // Read the status of the request to handle the state update.
    }
}

// Registers the listener.
splitInstallManager.registerListener(listener)

...

splitInstallManager
    .startInstall(request)
    // When the platform accepts your request to download
    // an on demand module, it binds it to the following session ID.
    // You use this ID to track further status updates for the request.
    .addOnSuccessListener { sessionId -> mySessionId = sessionId }
    // You should also add the following listener to handle any errors
    // processing the request.
    .addOnFailureListener { exception ->
        // Handle request errors.
    }

// When your app no longer requires further updates, unregister the listener.
splitInstallManager.unregisterListener(listener)

Java

// Initializes a variable to later track the session ID for a given request.
int mySessionId = 0;

// Creates a listener for request status updates.
SplitInstallStateUpdatedListener listener = state -> {
    if (state.sessionId() == mySessionId) {
      // Read the status of the request to handle the state update.
    }
};

// Registers the listener.
splitInstallManager.registerListener(listener);

...

splitInstallManager
    .startInstall(request)
    // When the platform accepts your request to download
    // an on demand module, it binds it to the following session ID.
    // You use this ID to track further status updates for the request.
    .addOnSuccessListener(sessionId -> { mySessionId = sessionId; })
    // You should also add the following listener to handle any errors
    // processing the request.
    .addOnFailureListener(exception -> {
        // Handle request errors.
    });

// When your app no longer requires further updates, unregister the listener.
splitInstallManager.unregisterListener(listener);

Anforderungsfehler behandeln

Beachten Sie, dass die On-Demand-Installation von Funktionsmodulen manchmal fehlschlagen kann, genau wie die App-Installation nicht immer erfolgreich ist. Die Installation kann aus verschiedenen Gründen fehlschlagen, z. B. aufgrund von wenig Speicherplatz auf dem Gerät, fehlender Netzwerkverbindung oder weil der Nutzer nicht im Google Play Store angemeldet ist. In unseren UX-Richtlinien für die On-Demand-Auslieferung finden Sie Vorschläge, wie Sie diese Situationen aus der Perspektive der Nutzer reibungslos bewältigen können.

Codeseitig sollten Sie Fehler beim Herunterladen oder Installieren eines Moduls mit addOnFailureListener() wie unten beschrieben behandeln:

Kotlin

splitInstallManager
    .startInstall(request)
    .addOnFailureListener { exception ->
        when ((exception as SplitInstallException).errorCode) {
            SplitInstallErrorCode.NETWORK_ERROR -> {
                // Display a message that requests the user to establish a
                // network connection.
            }
            SplitInstallErrorCode.ACTIVE_SESSIONS_LIMIT_EXCEEDED -> checkForActiveDownloads()
            ...
        }
    }

fun checkForActiveDownloads() {
    splitInstallManager
        // Returns a SplitInstallSessionState object for each active session as a List.
        .sessionStates
        .addOnCompleteListener { task ->
            if (task.isSuccessful) {
                // Check for active sessions.
                for (state in task.result) {
                    if (state.status() == SplitInstallSessionStatus.DOWNLOADING) {
                        // Cancel the request, or request a deferred installation.
                    }
                }
            }
        }
}

Java

splitInstallManager
    .startInstall(request)
    .addOnFailureListener(exception -> {
        switch (((SplitInstallException) exception).getErrorCode()) {
            case SplitInstallErrorCode.NETWORK_ERROR:
                // Display a message that requests the user to establish a
                // network connection.
                break;
            case SplitInstallErrorCode.ACTIVE_SESSIONS_LIMIT_EXCEEDED:
                checkForActiveDownloads();
            ...
    });

void checkForActiveDownloads() {
    splitInstallManager
        // Returns a SplitInstallSessionState object for each active session as a List.
        .getSessionStates()
        .addOnCompleteListener( task -> {
            if (task.isSuccessful()) {
                // Check for active sessions.
                for (SplitInstallSessionState state : task.getResult()) {
                    if (state.status() == SplitInstallSessionStatus.DOWNLOADING) {
                        // Cancel the request, or request a deferred installation.
                    }
                }
            }
        });
}

In der folgenden Tabelle werden die Fehlerstatus beschrieben, die Ihre App möglicherweise verarbeiten muss:

Fehlercode	Beschreibung	Vorgeschlagene Maßnahme
ACTIVE_SESSIONS_LIMIT_EXCEEDED	Die Anfrage wird abgelehnt, da mindestens eine Anfrage gerade heruntergeladen wird.	Prüfen Sie, ob noch Anfragen heruntergeladen werden, wie im Beispiel oben dargestellt.
MODULE_UNAVAILABLE	Google Play kann das angeforderte Modul anhand der aktuell installierten Version der App, des Geräts und des Google Play-Kontos des Nutzers nicht finden.	Wenn der Nutzer keinen Zugriff auf das Modul hat, benachrichtige ihn.
INVALID_REQUEST	Google Play hat die Anfrage erhalten, sie ist jedoch ungültig.	Prüfen Sie, ob die im Antrag enthaltenen Informationen vollständig und korrekt sind.
SESSION_NOT_FOUND	Es wurde keine Sitzung mit der angegebenen Sitzungs-ID gefunden.	Wenn Sie den Status einer Anfrage anhand der Sitzungs-ID überwachen möchten, achten Sie darauf, dass die Sitzungs-ID korrekt ist.
API_NOT_AVAILABLE	Die Play Feature Delivery Library wird auf dem aktuellen Gerät nicht unterstützt. Das Gerät kann also keine Funktionen auf Abruf herunterladen und installieren.	Für Geräte mit Android 4.4 (API-Level 20) oder niedriger sollten Sie Funktionsmodule bei der Installation mithilfe der Manifest-Eigenschaft dist:fusing angeben. Weitere Informationen finden Sie im Artikel zum Manifest des Funktionsmoduls.
NETWORK_ERROR	Die Anfrage ist aufgrund eines Netzwerkfehlers fehlgeschlagen.	Bitten Sie den Nutzer, entweder eine Netzwerkverbindung herzustellen oder zu einem anderen Netzwerk zu wechseln.
ACCESS_DENIED	Die App kann die Anfrage aufgrund unzureichender Berechtigungen nicht registrieren.	Das passiert in der Regel, wenn die App im Hintergrund ausgeführt wird. Wiederholen Sie die Anfrage, wenn die App wieder im Vordergrund ist.
INCOMPATIBLE_WITH_EXISTING_SESSION	Die Anfrage enthält ein oder mehrere Module, die bereits angefordert, aber noch nicht installiert wurden.	Erstellen Sie entweder eine neue Anfrage, die keine bereits von Ihrer App angeforderten Module enthält, oder warten Sie, bis die Installation aller derzeit angeforderten Module abgeschlossen ist, bevor Sie die Anfrage noch einmal versuchen. Hinweis: Wenn Sie ein bereits installiertes Modul anfordern, wird kein Fehler ausgegeben.
SERVICE_DIED	Der für die Bearbeitung der Anfrage zuständige Dienst ist nicht mehr verfügbar.	Wiederholen Sie die Anfrage. Deine SplitInstallStateUpdatedListener erhält eine SplitInstallSessionState mit diesem Fehlercode, dem Status FAILED und der Sitzungs-ID -1.
INSUFFICIENT_STORAGE	Auf dem Gerät ist nicht genügend freier Speicherplatz vorhanden, um das Funktionsmodul zu installieren.	Informieren Sie den Nutzer, dass er nicht genügend Speicherplatz hat, um diese Funktion zu installieren.
SPLITCOMPAT_VERIFICATION_ERROR, SPLITCOMPAT_EMULATION_ERROR, SPLITCOMPAT_COPY_ERROR	SplitCompat konnte das Funktionsmodul nicht laden.	Diese Fehler sollten sich nach dem nächsten App-Neustart automatisch beheben.
PLAY_STORE_NOT_FOUND	Die Play Store App ist nicht auf dem Gerät installiert.	Informieren Sie den Nutzer, dass die Play Store App zum Herunterladen dieser Funktion erforderlich ist.
APP_NOT_OWNED	Die App wurde nicht von Google Play installiert und die Funktion kann nicht heruntergeladen werden. Dieser Fehler kann nur bei verzögerten Installationen auftreten.	Wenn der Nutzer die App bei Google Play erwerben soll, verwenden Sie startInstall(), um die erforderliche Nutzerbestätigung abzurufen.
INTERNAL_ERROR	Im Play Store ist ein interner Fehler aufgetreten.	Wiederholen Sie die Anfrage.

Wenn ein Nutzer den Download eines On-Demand-Moduls anfordert und ein Fehler auftritt, können Sie ein Dialogfeld mit zwei Optionen anzeigen: Noch einmal versuchen (die Anfrage wird noch einmal versucht) und Abbrechen (die Anfrage wird abgebrochen). Für zusätzlichen Support sollten Sie auch einen Hilfe-Link angeben, über den Nutzer zur Google Play-Hilfe weitergeleitet werden.

Hinweis :Wenn Sie beim Testen Ihrer App onError(-2) sehen, haben Sie Ihre App möglicherweise noch nicht bei Google Play hochgeladen. Wenn Sie die On-Demand-Funktionen Ihrer App testen möchten, müssen Sie entweder Ihre App über eine URL freigeben oder einen offenen, geschlossenen oder internen Test einrichten.

Statusaktualisierungen verarbeiten

Nachdem du einen Listener registriert und die Sitzungs-ID für deine Anfrage aufgezeichnet hast, verwende StateUpdatedListener.onStateUpdate(), um Statusänderungen zu verarbeiten, wie unten gezeigt.

Kotlin

override fun onStateUpdate(state : SplitInstallSessionState) {
    if (state.status() == SplitInstallSessionStatus.FAILED
        && state.errorCode() == SplitInstallErrorCode.SERVICE_DIED) {
       // Retry the request.
       return
    }
    if (state.sessionId() == mySessionId) {
        when (state.status()) {
            SplitInstallSessionStatus.DOWNLOADING -> {
              val totalBytes = state.totalBytesToDownload()
              val progress = state.bytesDownloaded()
              // Update progress bar.
            }
            SplitInstallSessionStatus.INSTALLED -> {

              // After a module is installed, you can start accessing its content or
              // fire an intent to start an activity in the installed module.
              // For other use cases, see access code and resources from installed modules.

              // If the request is an on demand module for an Android Instant App
              // running on Android 8.0 (API level 26) or higher, you need to
              // update the app context using the SplitInstallHelper API.
            }
        }
    }
}

Java

@Override
public void onStateUpdate(SplitInstallSessionState state) {
    if (state.status() == SplitInstallSessionStatus.FAILED
        && state.errorCode() == SplitInstallErrorCode.SERVICE_DIES) {
       // Retry the request.
       return;
    }
    if (state.sessionId() == mySessionId) {
        switch (state.status()) {
            case SplitInstallSessionStatus.DOWNLOADING:
              int totalBytes = state.totalBytesToDownload();
              int progress = state.bytesDownloaded();
              // Update progress bar.
              break;

            case SplitInstallSessionStatus.INSTALLED:

              // After a module is installed, you can start accessing its content or
              // fire an intent to start an activity in the installed module.
              // For other use cases, see access code and resources from installed modules.

              // If the request is an on demand module for an Android Instant App
              // running on Android 8.0 (API level 26) or higher, you need to
              // update the app context using the SplitInstallHelper API.
        }
    }
}

Die möglichen Status für Ihre Installationsanfrage sind in der folgenden Tabelle beschrieben.

Anfragestatus	Beschreibung	Vorgeschlagene Maßnahme
AUSSTEHEND	Der Antrag wurde akzeptiert und der Download sollte bald beginnen.	Initialisieren Sie UI-Komponenten wie eine Fortschrittsanzeige, um den Nutzern Feedback zum Download zu geben.
REQUIRES_USER_CONFIRMATION	Für den Download ist eine Nutzerbestätigung erforderlich. In den meisten Fällen tritt dieser Status auf, wenn die App nicht über Google Play installiert wurde.	Bitten Sie den Nutzer, den Download der Funktion über Google Play zu bestätigen. Weitere Informationen finden Sie im Abschnitt zur Nutzerbestätigung.
Downloads	Der Download läuft.	Wenn du einen Fortschrittsbalken für den Download bereitstellst, verwende die Methoden SplitInstallSessionState.bytesDownloaded() und SplitInstallSessionState.totalBytesToDownload(), um die Benutzeroberfläche zu aktualisieren (siehe Codebeispiel über dieser Tabelle).
HERUNTERGELADEN	Das Gerät hat das Modul heruntergeladen, die Installation hat aber noch nicht begonnen.	Apps sollten SplitCompat aktivieren, um Zugriff auf heruntergeladene Module zu erhalten und diesen Status zu vermeiden. Dies ist erforderlich, um auf den Code und die Ressourcen des Funktionsmoduls zuzugreifen.
Installation...	Auf dem Gerät wird derzeit das Modul installiert.	Aktualisieren Sie die Fortschrittsanzeige. Dieser Zustand ist in der Regel kurz.
INSTALLIERT	Das Modul ist auf dem Gerät installiert.	Zugriffscode und Ressource im Modul, um mit der User Journey fortzufahren. Wenn das Modul für eine Android-Instant-App bestimmt ist, die auf Android 8.0 (API-Level 26) oder höher ausgeführt wird, müssen Sie splitInstallHelper verwenden, um App-Komponenten mit dem neuen Modul zu aktualisieren.
FEHLER	Die Anfrage ist fehlgeschlagen, bevor das Modul auf dem Gerät installiert wurde.	Bitten Sie den Nutzer, den Vorgang noch einmal zu versuchen oder abzubrechen.
KÜNDIGUNG	Auf dem Gerät wird die Anfrage gerade abgebrochen.	Weitere Informationen finden Sie im Abschnitt Installationsanfrage stornieren.
GESTRICHEN	Der Antrag wurde abgebrochen.

Nutzerbestätigung einholen

In einigen Fällen ist bei Google Play eine Nutzerbestätigung erforderlich, bevor ein Downloadanfrage ausgeführt wird. Das ist beispielsweise der Fall, wenn Ihre App nicht von Google Play installiert wurde oder Sie einen großen Download über mobile Daten versuchen. In solchen Fällen wird der Status der Anfrage als REQUIRES_USER_CONFIRMATION angezeigt und Ihre App muss die Nutzerbestätigung einholen, bevor das Gerät die Module in der Anfrage herunterladen und installieren kann. Um eine Bestätigung zu erhalten, sollte Ihre App den Nutzer folgendermaßen auffordern:

Kotlin

override fun onSessionStateUpdate(state: SplitInstallSessionState) {
    if (state.status() == SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION) {
        // Displays a confirmation for the user to confirm the request.
        splitInstallManager.startConfirmationDialogForResult(
          state,
          // an activity result launcher registered via registerForActivityResult
          activityResultLauncher)
    }
    ...
 }

Java

@Override void onSessionStateUpdate(SplitInstallSessionState state) {
    if (state.status() == SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION) {
        // Displays a confirmation for the user to confirm the request.
        splitInstallManager.startConfirmationDialogForResult(
          state,
          // an activity result launcher registered via registerForActivityResult
          activityResultLauncher);
    }
    ...
 }

Sie können einen Launcher für Aktivitätsergebnisse mit dem integrierten Vertrag ActivityResultContracts.StartIntentSenderForResult registrieren. Weitere Informationen finden Sie unter Aktivitätsergebnis-APIs.

Der Status der Anfrage wird je nach Nutzerantwort aktualisiert:

• Wenn der Nutzer die Bestätigung akzeptiert, ändert sich der Antragsstatus zu PENDING und der Download wird fortgesetzt.
• Wenn der Nutzer die Bestätigung ablehnt, ändert sich der Antragsstatus in CANCELED.
• Wenn der Nutzer keine Auswahl trifft, bevor das Dialogfeld geschlossen wird, bleibt der Anfragestatus REQUIRES_USER_CONFIRMATION. Ihre App kann den Nutzer noch einmal auffordern, die Anfrage abzuschließen.

Wenn Sie einen Callback mit der Antwort des Nutzers erhalten möchten, können Sie den ActivityResultCallback wie unten gezeigt überschreiben.

Kotlin

registerForActivityResult(StartIntentSenderForResult()) { result: ActivityResult -> {
        // Handle the user's decision. For example, if the user selects "Cancel",
        // you may want to disable certain functionality that depends on the module.
    }
}

Java

registerForActivityResult(
    new ActivityResultContracts.StartIntentSenderForResult(),
    new ActivityResultCallback<ActivityResult>() {
        @Override
        public void onActivityResult(ActivityResult result) {
            // Handle the user's decision. For example, if the user selects "Cancel",
            // you may want to disable certain functionality that depends on the module.
        }
    });

Installationsanfrage stornieren

Wenn Ihre App eine Anfrage vor der Installation abbrechen muss, kann sie die Methode cancelInstall() mit der Sitzungs-ID der Anfrage aufrufen, wie unten gezeigt.

Kotlin

splitInstallManager
    // Cancels the request for the given session ID.
    .cancelInstall(mySessionId)

Java

splitInstallManager
    // Cancels the request for the given session ID.
    .cancelInstall(mySessionId);

Auf Module zugreifen

Damit nach dem Download auf Code und Ressourcen eines heruntergeladenen Moduls zugegriffen werden kann, muss die SplitCompat Library sowohl für Ihre App als auch für jede Aktivität in den Funktionsmodulen, die Ihre App herunterlädt, aktiviert sein.

Beachten Sie jedoch, dass nach dem Herunterladen eines Moduls für einige Zeit (in einigen Fällen Tage) folgende Einschränkungen für den Zugriff auf den Inhalt des Moduls gelten:

• Die Plattform kann keine neuen Manifesteinträge anwenden, die durch das Modul eingeführt wurden.
• Die Plattform kann nicht auf die Ressourcen des Moduls für System-UI-Komponenten wie Benachrichtigungen zugreifen. Wenn Sie solche Ressourcen sofort verwenden müssen, sollten Sie sie in das Basismodul Ihrer App aufnehmen.

SplitCompat aktivieren

Damit Ihre App auf Code und Ressourcen aus einem heruntergeladenen Modul zugreifen kann, müssen Sie SplitCompat mit einer der in den folgenden Abschnitten beschriebenen Methoden aktivieren.

Nachdem Sie SplitCompat für Ihre App aktiviert haben, müssen Sie SplitCompat auch für jede Aktivität in den Funktionsmodulen aktivieren, auf die Ihre App zugreifen soll.

SplitCompatApplication im Manifest deklarieren

Die einfachste Möglichkeit, SplitCompat zu aktivieren, besteht darin, SplitCompatApplication als Application-Unterklasse im Manifest Ihrer App zu deklarieren, wie unten dargestellt:

<application
    ...
    android:name="com.google.android.play.core.splitcompat.SplitCompatApplication">
</application>

Nachdem die App auf einem Gerät installiert wurde, können Sie automatisch auf Code und Ressourcen aus heruntergeladenen Funktionsmodulen zugreifen.

SplitCompat zur Laufzeit aufrufen

Sie können SplitCompat auch bei bestimmten Aktivitäten oder Diensten zur Laufzeit aktivieren. Die Aktivierung von SplitCompat auf diese Weise ist erforderlich, um Aktivitäten zu starten, die in Funktionsmodulen enthalten sind. Überschreiben Sie dazu attachBaseContext wie unten gezeigt.

Wenn Sie eine benutzerdefinierte Application-Klasse haben, erweitern Sie sie stattdessen mit SplitCompatApplication, um SplitCompat für Ihre App zu aktivieren, wie unten gezeigt:

Kotlin

class MyApplication : SplitCompatApplication() {
    ...
}

Java

public class MyApplication extends SplitCompatApplication {
    ...
}

SplitCompatApplication überschreibt einfach ContextWrapper.attachBaseContext(), um SplitCompat.install(Context applicationContext) einzubeziehen. Wenn Sie nicht möchten, dass Ihre Application-Klasse SplitCompatApplication erweitert, können Sie die attachBaseContext()-Methode manuell überschreiben. Gehen Sie dazu so vor:

Kotlin

override fun attachBaseContext(base: Context) {
    super.attachBaseContext(base)
    // Emulates installation of future on demand modules using SplitCompat.
    SplitCompat.install(this)
}

Java

@Override
protected void attachBaseContext(Context base) {
    super.attachBaseContext(base);
    // Emulates installation of future on demand modules using SplitCompat.
    SplitCompat.install(this);
}

Wenn Ihr On-Demand-Modul sowohl mit Instant Apps als auch mit installierten Apps kompatibel ist, können Sie SplitCompat bedingt aufrufen. Gehen Sie dazu so vor:

Kotlin

override fun attachBaseContext(base: Context) {
    super.attachBaseContext(base)
    if (!InstantApps.isInstantApp(this)) {
        SplitCompat.install(this)
    }
}

Java

@Override
protected void attachBaseContext(Context base) {
    super.attachBaseContext(base);
    if (!InstantApps.isInstantApp(this)) {
        SplitCompat.install(this);
    }
}

SplitCompat für Modulaktivitäten aktivieren

Nachdem Sie SplitCompat für Ihre Basis-App aktiviert haben, müssen Sie SplitCompat für jede Aktivität aktivieren, die Ihre App in einem Funktionsmodul herunterlädt. Verwenden Sie dazu die Methode SplitCompat.installActivity():

Kotlin

override fun attachBaseContext(base: Context) {
    super.attachBaseContext(base)
    // Emulates installation of on demand modules using SplitCompat.
    SplitCompat.installActivity(this)
}

Java

@Override
protected void attachBaseContext(Context base) {
    super.attachBaseContext(base);
    // Emulates installation of on demand modules using SplitCompat.
    SplitCompat.installActivity(this);
}

Auf in Funktionsmodulen definierte Komponenten zugreifen

Aktivität starten, die in einem Funktionsmodul definiert ist

Nachdem Sie SplitCompat aktiviert haben, können Sie Aktivitäten, die in Funktionsmodulen definiert sind, mit startActivity() starten.

Kotlin

startActivity(Intent()
  .setClassName("com.package", "com.package.module.MyActivity")
  .setFlags(...))

Java

startActivity(new Intent()
  .setClassName("com.package", "com.package.module.MyActivity")
  .setFlags(...));

Der erste Parameter für setClassName ist der Paketname der App und der zweite Parameter ist der vollständige Klassenname der Aktivität.

Wenn Sie eine Aktivität in einem Feature-Modul haben, das Sie auf Anfrage heruntergeladen haben, müssen Sie SplitCompat in der Aktivität aktivieren.

In einem Funktionsmodul definierten Dienst starten

Nachdem Sie SplitCompat aktiviert haben, können Sie Dienste, die in Funktionsmodulen definiert sind, über startService() starten.

Kotlin

startService(Intent()
  .setClassName("com.package", "com.package.module.MyService")
  .setFlags(...))

Java

startService(new Intent()
  .setClassName("com.package", "com.package.module.MyService")
  .setFlags(...));

In einem Feature-Modul definierte Komponente exportieren

Exportierte Android-Komponenten sollten nicht in optionale Module aufgenommen werden.

Das Build-System führt Manifesteinträge für alle Module in das Basismodul zusammen. Wenn ein optionales Modul eine exportierte Komponente enthält, ist es bereits vor der Installation des Moduls zugänglich und kann bei Aufruf über eine andere App aufgrund fehlenden Codes zu einem Absturz führen.

Das ist bei internen Komponenten kein Problem, da nur die App darauf zugreift. Die App kann also prüfen, ob das Modul installiert ist, bevor sie auf die Komponente zugreift.

Wenn Sie eine exportierte Komponente benötigen und der Inhalt in einem optionalen Modul enthalten sein soll, sollten Sie ein Proxy-Muster implementieren. Dazu fügen Sie der Basis eine Proxy-exportierte Komponente hinzu. Beim Zugriff kann die Proxy-Komponente prüfen, ob das Modul mit den Inhalten vorhanden ist. Wenn das Modul vorhanden ist, kann die Proxykomponente die interne Komponente über eine Intent aus dem Modul starten und den Intent aus der aufrufenden App weiterleiten. Wenn das Modul nicht vorhanden ist, kann die Komponente das Modul herunterladen oder eine entsprechende Fehlermeldung an die aufrufende App zurückgeben.

Auf Code und Ressourcen aus installierten Modulen zugreifen

Wenn Sie SplitCompat für den Basis-Anwendungskontext und die Aktivitäten in Ihrem Funktionsmodul aktivieren, können Sie den Code und die Ressourcen aus einem Funktionsmodul verwenden, als wären sie Teil des Basis-APKs, sobald das optionale Modul installiert ist.

Zugriffscode aus einem anderen Modul

Auf Basiscode aus einem Modul zugreifen

Code in Ihrem Basismodul kann direkt von anderen Modulen verwendet werden. Sie müssen nichts Besonderes tun. Importieren Sie einfach die benötigten Klassen und verwenden Sie sie.

Auf Modulcode aus einem anderen Modul zugreifen

Auf ein Objekt oder eine Klasse in einem Modul kann nicht direkt aus einem anderen Modul statisch zugegriffen werden. Es ist aber möglich, indirekt über Reflection darauf zuzugreifen.

Sie sollten jedoch darauf achten, wie oft dies geschieht, da die Reflexion Leistungskosten verursacht. Verwenden Sie für komplexe Anwendungsfälle Dependency Injection-Frameworks wie Dagger 2, um pro Anwendungslebensdauer einen einzigen Reflection-Aufruf zu gewährleisten.

Um die Interaktionen mit dem Objekt nach der Instanziierung zu vereinfachen, wird empfohlen, eine Schnittstelle im Basismodul und ihre Implementierung im Feature-Modul zu definieren. Beispiel:

Kotlin

// In the base module
interface MyInterface {
  fun hello(): String
}

// In the feature module
object MyInterfaceImpl : MyInterface {
  override fun hello() = "Hello"
}

// In the base module, where we want to access the feature module code
val stringFromModule = (Class.forName("com.package.module.MyInterfaceImpl")
    .kotlin.objectInstance as MyInterface).hello();

Java

// In the base module
public interface MyInterface {
  String hello();
}

// In the feature module
public class MyInterfaceImpl implements MyInterface {
  @Override
  public String hello() {
    return "Hello";
  }
}

// In the base module, where we want to access the feature module code
String stringFromModule =
   ((MyInterface) Class.forName("com.package.module.MyInterfaceImpl").getConstructor().newInstance()).hello();

Auf Ressourcen und Assets aus einem anderen Modul zugreifen

Nachdem ein Modul installiert wurde, können Sie auf die Ressourcen und Assets innerhalb des Moduls auf standardmäßige Weise zugreifen. Es gibt jedoch zwei Ausnahmen:

• Wenn Sie von einem anderen Modul auf eine Ressource zugreifen, hat das Modul keinen Zugriff auf die Ressourcen-ID. Sie können jedoch weiterhin per Name auf die Ressource zugreifen. Das Paket, auf das verwiesen werden soll, ist das Paket des Moduls, in dem die Ressource definiert ist.
• Wenn Sie von einem anderen installierten Modul Ihrer App auf Assets oder Ressourcen zugreifen möchten, die in einem neu installierten Modul vorhanden sind, müssen Sie dies über den Anwendungskontext tun. Der Kontext der Komponente, die auf die Ressourcen zuzugreifen versucht, wird noch nicht aktualisiert. Alternativ können Sie diese Komponente neu erstellen (z. B. durch Aufrufen von Activity.recreate()) oder SplitCompat nach der Installation des Funktionsmoduls neu installieren.

Nativen Code mit der On-Demand-Auslieferung in einer App laden

Wir empfehlen, ReLinker zu verwenden, um alle nativen Bibliotheken zu laden, wenn Sie die On-Demand-Auslieferung von Funktionsmodulen verwenden. Mit ReLinker wird ein Problem beim Laden nativer Bibliotheken nach der Installation eines Funktionsmoduls behoben. Weitere Informationen zu ReLinker finden Sie in den Tipps zur Android JNI.

Nativen Code aus einem optionalen Modul laden

Nachdem eine Teilung installiert wurde, empfehlen wir, den nativen Code über ReLinker zu laden. Für Instant-Apps sollten Sie diese spezielle Methode verwenden.

Wenn Sie System.loadLibrary() zum Laden Ihres nativen Codes verwenden und Ihre native Bibliothek von einer anderen Bibliothek im Modul abhängt, müssen Sie diese andere Bibliothek zuerst manuell laden. Wenn Sie ReLinker verwenden, ist der entsprechende Vorgang Relinker.recursively().loadLibrary().

Wenn Sie dlopen() in nativem Code verwenden, um eine in einem optionalen Modul definierte Bibliothek zu laden, funktioniert das nicht mit relativen Bibliothekspfaden. Die beste Lösung besteht darin, den absoluten Pfad der Bibliothek über ClassLoader.findLibrary() aus dem Java-Code abzurufen und dann in Ihrem dlopen()-Aufruf zu verwenden. Führen Sie dies aus, bevor Sie den nativen Code eingeben, oder verwenden Sie einen JNI-Aufruf von Ihrem nativen Code in Java.

Auf installierte Android Instant Apps zugreifen

Wenn ein Android Instant App-Modul als INSTALLED gemeldet wird, können Sie über einen aktualisierten App-Kontext auf den Code und die Ressourcen zugreifen. Ein Kontext, der von Ihrer App vor der Installation eines Moduls erstellt wird (z. B. einer, der bereits in einer Variablen gespeichert ist), enthält nicht den Inhalt des neuen Moduls. Ein neuer Kontext funktioniert jedoch – dieser kann beispielsweise mit createPackageContext abgerufen werden.

Kotlin

// Generate a new context as soon as a request for a new module
// reports as INSTALLED.
override fun onStateUpdate(state: SplitInstallSessionState ) {
    if (state.sessionId() == mySessionId) {
        when (state.status()) {
            ...
            SplitInstallSessionStatus.INSTALLED -> {
                val newContext = context.createPackageContext(context.packageName, 0)
                // If you use AssetManager to access your app’s raw asset files, you’ll need
                // to generate a new AssetManager instance from the updated context.
                val am = newContext.assets
            }
        }
    }
}

Java

// Generate a new context as soon as a request for a new module
// reports as INSTALLED.
@Override
public void onStateUpdate(SplitInstallSessionState state) {
    if (state.sessionId() == mySessionId) {
        switch (state.status()) {
            ...
            case SplitInstallSessionStatus.INSTALLED:
                Context newContext = context.createPackageContext(context.getPackageName(), 0);
                // If you use AssetManager to access your app’s raw asset files, you’ll need
                // to generate a new AssetManager instance from the updated context.
                AssetManager am = newContext.getAssets();
        }
    }
}

Android Instant Apps unter Android 8.0 und höher

Wenn Sie ein On-Demand-Modul für eine Android Instant App unter Android 8.0 (API-Level 26) und höher anfordern und eine Installationsanfrage den Status INSTALLED zurückgibt, müssen Sie die App mit dem Kontext des neuen Moduls aktualisieren, indem Sie SplitInstallHelper.updateAppInfo(Context context) aufrufen. Andernfalls kennt die App den Code und die Ressourcen des Moduls noch nicht. Nachdem du die Metadaten der App aktualisiert hast, solltest du den Inhalt des Moduls während des nächsten Hauptthread-Ereignisses laden, indem du eine neue Handler aufrufst, wie unten gezeigt:

Kotlin

override fun onStateUpdate(state: SplitInstallSessionState ) {
    if (state.sessionId() == mySessionId) {
        when (state.status()) {
            ...
            SplitInstallSessionStatus.INSTALLED -> {
                // You need to perform the following only for Android Instant Apps
                // running on Android 8.0 (API level 26) and higher.
                if (BuildCompat.isAtLeastO()) {
                    // Updates the app’s context with the code and resources of the
                    // installed module.
                    SplitInstallHelper.updateAppInfo(context)
                    Handler().post {
                        // Loads contents from the module using AssetManager
                        val am = context.assets
                        ...
                    }
                }
            }
        }
    }
}

Java

@Override
public void onStateUpdate(SplitInstallSessionState state) {
    if (state.sessionId() == mySessionId) {
        switch (state.status()) {
            ...
            case SplitInstallSessionStatus.INSTALLED:
            // You need to perform the following only for Android Instant Apps
            // running on Android 8.0 (API level 26) and higher.
            if (BuildCompat.isAtLeastO()) {
                // Updates the app’s context with the code and resources of the
                // installed module.
                SplitInstallHelper.updateAppInfo(context);
                new Handler().post(new Runnable() {
                    @Override public void run() {
                        // Loads contents from the module using AssetManager
                        AssetManager am = context.getAssets();
                        ...
                    }
                });
            }
        }
    }
}

C/C++-Bibliotheken laden

Wenn Sie C/C++-Bibliotheken aus einem Modul laden möchten, das das Gerät bereits in einer Instant App heruntergeladen hat, verwenden Sie SplitInstallHelper.loadLibrary(Context context, String libName), wie unten gezeigt:

Kotlin

override fun onStateUpdate(state: SplitInstallSessionState) {
    if (state.sessionId() == mySessionId) {
        when (state.status()) {
            SplitInstallSessionStatus.INSTALLED -> {
                // Updates the app’s context as soon as a module is installed.
                val newContext = context.createPackageContext(context.packageName, 0)
                // To load C/C++ libraries from an installed module, use the following API
                // instead of System.load().
                SplitInstallHelper.loadLibrary(newContext, “my-cpp-lib”)
                ...
            }
        }
    }
}

Java

public void onStateUpdate(SplitInstallSessionState state) {
    if (state.sessionId() == mySessionId) {
        switch (state.status()) {
            case SplitInstallSessionStatus.INSTALLED:
                // Updates the app’s context as soon as a module is installed.
                Context newContext = context.createPackageContext(context.getPackageName(), 0);
                // To load C/C++ libraries from an installed module, use the following API
                // instead of System.load().
                SplitInstallHelper.loadLibrary(newContext, “my-cpp-lib”);
                ...
        }
    }
}

Bekannte Einschränkungen

• Android WebView kann nicht in einer Aktivität verwendet werden, die auf Ressourcen oder Assets aus einem optionalen Modul zugreift. Das liegt an einer Inkompatibilität zwischen WebView und SplitCompat bei Android API-Level 28 und niedriger.
• Sie können keine Android-ApplicationInfo-Objekte, ihren Inhalt oder Objekte, die sie enthalten, in Ihrer App im Cache speichern. Sie sollten diese Objekte immer bei Bedarf aus einem App-Kontext abrufen. Wenn Sie solche Objekte im Cache speichern, kann die App beim Installieren eines Funktionsmoduls abstürzen.

Installierte Module verwalten

Wenn Sie prüfen möchten, welche Funktionsmodule derzeit auf dem Gerät installiert sind, können Sie SplitInstallManager.getInstalledModules() aufrufen. Daraufhin wird eine Set<String> mit den Namen der installierten Module zurückgegeben, wie unten dargestellt.

Hinweis: Wenn Sie eine Android-Instant-App entwickeln, gilt dieser Abschnitt nicht für Sie.

Kotlin

val installedModules: Set<String> = splitInstallManager.installedModules

Java

Set<String> installedModules = splitInstallManager.getInstalledModules();

Module deinstallieren

Sie können das Gerät auffordern, Module zu deinstallieren, indem Sie SplitInstallManager.deferredUninstall(List<String> moduleNames) aufrufen, wie unten gezeigt.

Kotlin

// Specifies two feature modules for deferred uninstall.
splitInstallManager.deferredUninstall(listOf("pictureMessages", "promotionalFilters"))

Java

// Specifies two feature modules for deferred uninstall.
splitInstallManager.deferredUninstall(Arrays.asList("pictureMessages", "promotionalFilters"));

Die Deinstallation von Modulen erfolgt nicht sofort. Das Gerät deinstalliert sie bei Bedarf im Hintergrund, um Speicherplatz zu sparen. Sie können prüfen, ob das Gerät ein Modul gelöscht hat, indem Sie SplitInstallManager.getInstalledModules() aufrufen und das Ergebnis wie im vorherigen Abschnitt beschrieben prüfen.

Zusätzliche Sprachressourcen herunterladen

Bei App-Bundles wird auf den Geräten nur der Code und die Ressourcen heruntergeladen, die zum Ausführen Ihrer App erforderlich sind. Bei Sprachressourcen werden also nur die Sprachressourcen Ihrer App auf das Gerät des Nutzers heruntergeladen, die der oder den in den Geräteeinstellungen aktuell ausgewählten Sprachen entsprechen.

Wenn Ihre App auf zusätzliche Sprachressourcen zugreifen soll, z. B. um eine In-App-Sprachauswahl zu implementieren, können Sie diese über die Play Feature Delivery Library auf Abruf herunterladen. Der Vorgang ähnelt dem Herunterladen eines Funktionsmoduls, wie unten dargestellt.

Kotlin

// Captures the user’s preferred language and persists it
// through the app’s SharedPreferences.
sharedPrefs.edit().putString(LANGUAGE_SELECTION, "fr").apply()
...

// Creates a request to download and install additional language resources.
val request = SplitInstallRequest.newBuilder()
        // Uses the addLanguage() method to include French language resources in the request.
        // Note that country codes are ignored. That is, if your app
        // includes resources for “fr-FR” and “fr-CA”, resources for both
        // country codes are downloaded when requesting resources for "fr".
        .addLanguage(Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)))
        .build()

// Submits the request to install the additional language resources.
splitInstallManager.startInstall(request)

Java

// Captures the user’s preferred language and persists it
// through the app’s SharedPreferences.
sharedPrefs.edit().putString(LANGUAGE_SELECTION, "fr").apply();
...

// Creates a request to download and install additional language resources.
SplitInstallRequest request =
    SplitInstallRequest.newBuilder()
        // Uses the addLanguage() method to include French language resources in the request.
        // Note that country codes are ignored. That is, if your app
        // includes resources for “fr-FR” and “fr-CA”, resources for both
        // country codes are downloaded when requesting resources for "fr".
        .addLanguage(Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)))
        .build();

// Submits the request to install the additional language resources.
splitInstallManager.startInstall(request);

Die Anfrage wird so behandelt, als wäre es eine Anfrage für ein Funktionsmodul. Sie können also wie gewohnt den Status der Anfrage beobachten.

Wenn die zusätzlichen Sprachressourcen für Ihre App nicht sofort erforderlich sind, können Sie die Installation wie unten gezeigt auf einen Zeitpunkt verschieben, an dem die App im Hintergrund ausgeführt wird.

Kotlin

splitInstallManager.deferredLanguageInstall(
    Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)))

Java

splitInstallManager.deferredLanguageInstall(
    Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)));

Auf heruntergeladene Sprachressourcen zugreifen

Damit Ihre App auf heruntergeladene Sprachressourcen zugreifen kann, muss sie die Methode SplitCompat.installActivity() in der Methode attachBaseContext() jeder Aktivität ausführen, für die Zugriff auf diese Ressourcen erforderlich ist, wie unten dargestellt.

Kotlin

override fun attachBaseContext(base: Context) {
  super.attachBaseContext(base)
  SplitCompat.installActivity(this)
}

Java

@Override
protected void attachBaseContext(Context base) {
  super.attachBaseContext(base);
  SplitCompat.installActivity(this);
}

Aktualisieren Sie für jede Aktivität, für die Sie Sprachressourcen verwenden möchten, die von Ihrer App heruntergeladen wurden, den Basiskontext und legen Sie über Configuration eine neue Sprache fest:

Kotlin

override fun attachBaseContext(base: Context) {
  val configuration = Configuration()
  configuration.setLocale(Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)))
  val context = base.createConfigurationContext(configuration)
  super.attachBaseContext(context)
  SplitCompat.install(this)
}

Java

@Override
protected void attachBaseContext(Context base) {
  Configuration configuration = new Configuration();
  configuration.setLocale(Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)));
  Context context = base.createConfigurationContext(configuration);
  super.attachBaseContext(context);
  SplitCompat.install(this);
}

Damit diese Änderungen wirksam werden, müssen Sie Ihre Aktivitäten neu erstellen, nachdem die neue Sprache installiert und einsatzbereit ist. Sie können die Methode Activity#recreate() verwenden.

Kotlin

when (state.status()) {
  SplitInstallSessionStatus.INSTALLED -> {
      // Recreates the activity to load resources for the new language
      // preference.
      activity.recreate()
  }
  ...
}

Java

switch (state.status()) {
  case SplitInstallSessionStatus.INSTALLED:
      // Recreates the activity to load resources for the new language
      // preference.
      activity.recreate();
  ...
}

Zusätzliche Sprachressourcen deinstallieren

Ähnlich wie bei Funktionsmodulen können Sie zusätzliche Ressourcen jederzeit deinstallieren. Bevor Sie eine Deinstallation beantragen, sollten Sie zuerst ermitteln, welche Sprachen derzeit installiert sind. Gehen Sie dazu so vor:

Kotlin

val installedLanguages: Set<String> = splitInstallManager.installedLanguages

Java

Set<String> installedLanguages = splitInstallManager.getInstalledLanguages();

Sie können dann mit der deferredLanguageUninstall()-Methode festlegen, welche Sprachen Sie deinstallieren möchten (siehe unten).

Kotlin

splitInstallManager.deferredLanguageUninstall(
    Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)))

Java

splitInstallManager.deferredLanguageUninstall(
    Locale.forLanguageTag(sharedPrefs.getString(LANGUAGE_SELECTION)));

Modulinstallationen lokal testen

Mit der Play Feature Delivery Library können Sie die folgenden Funktionen Ihrer App lokal testen, ohne eine Verbindung zum Play Store herzustellen:

• Modulinstallationen anfordern und überwachen
• Installationsfehler behandeln
• Verwenden Sie SplitCompat, um auf Module zuzugreifen.

Auf dieser Seite wird beschrieben, wie Sie die gesplitteten APKs Ihrer App auf Ihrem Testgerät bereitstellen, damit diese APKs automatisch von der Play Feature Delivery zum Simulieren des Anforderns, Herunterladens und Installierens von Modulen aus dem Play Store verwendet werden.

Sie müssen zwar keine Änderungen an der Logik Ihrer App vornehmen, aber die folgenden Anforderungen erfüllen:

• Laden Sie die aktuelle Version von bundletool herunter und installieren Sie sie. Sie benötigen bundletool, um aus dem Bundle Ihrer App eine neue Reihe von installierbaren APKs zu erstellen.

Hinweis: Die Play Feature Delivery Library unterstützt derzeit keine Moduldeinstallationen oder verzögerten Installationen. Wenn Sie diese Funktion testen möchten, können Sie die interne App-Freigabe verwenden.

Mehrere APKs erstellen

Erstellen Sie die Split-APKs Ihrer App, falls noch nicht geschehen:

1. Erstellen Sie ein App-Bundle für Ihre App mit einer der folgenden Methoden:
   • Verwenden Sie Android Studio und das Android-Plug-in für Gradle, um ein Android App-Bundle zu erstellen und zu signieren.
   • App-Bundle über die Befehlszeile erstellen

2. Verwenden Sie bundletool, um mit dem folgenden Befehl eine Reihe von APKs für alle Gerätekonfigurationen zu generieren:

   bundletool build-apks --local-testing
     --bundle my_app.aab
     --output my_app.apks
   

Das Flag --local-testing enthält Metadaten in den Manifesten Ihrer APKs, die die Play Feature Delivery Library darüber informieren, dass die lokal aufgeteilten APKs verwendet werden sollen, um die Installation von Funktionsmodulen zu testen, ohne eine Verbindung zum Play Store herzustellen.

App auf dem Gerät bereitstellen

Nachdem Sie mit dem Flag --local-testing eine Reihe von APKs erstellt haben, können Sie mit bundletool die Basisversion Ihrer App installieren und zusätzliche APKs in den lokalen Speicher Ihres Geräts übertragen. Sie können beide Aktionen mit dem folgenden Befehl ausführen:

bundletool install-apks --apks my_app.apks

Wenn Sie jetzt Ihre App starten und den Nutzerfluss zum Herunterladen und Installieren eines Funktionsmoduls abschließen, verwendet die Play Feature Delivery Library die APKs, die bundletoolauf den lokalen Speicher des Geräts übertragen wurden.

Netzwerkfehler simulieren

Um Modulinstallationen aus dem Play Store zu simulieren, verwendet die Play Feature Delivery Library eine Alternative zur SplitInstallManager, die FakeSplitInstallManager, um das Modul anzufordern. Wenn Sie bundletool mit dem Flag --local-testing verwenden, um eine Reihe von APKs zu erstellen und auf Ihrem Testgerät bereitzustellen, enthält es Metadaten, die die Play Feature Delivery Library anweisen, die API-Aufrufe Ihrer App automatisch auf FakeSplitInstallManager umzustellen, anstatt SplitInstallManager aufzurufen.

FakeSplitInstallManager enthält ein boolesches Flag, das Sie aktivieren können, um bei der nächsten Installationsanfrage Ihrer App einen Netzwerkfehler zu simulieren. Wenn Sie in Ihren Tests auf FakeSplitInstallManager zugreifen möchten, können Sie eine Instanz davon mit FakeSplitInstallManagerFactory abrufen, wie unten gezeigt:

Kotlin

// Creates an instance of FakeSplitInstallManager with the app's context.
val fakeSplitInstallManager = FakeSplitInstallManagerFactory.create(context)
// Tells Play Feature Delivery Library to force the next module request to
// result in a network error.
fakeSplitInstallManager.setShouldNetworkError(true)

Java

// Creates an instance of FakeSplitInstallManager with the app's context.
FakeSplitInstallManager fakeSplitInstallManager =
    FakeSplitInstallManagerFactory.create(context);
// Tells Play Feature Delivery Library to force the next module request to
// result in a network error.
fakeSplitInstallManager.setShouldNetworkError(true);