Android-Builds

Baue Android-Apps und reiche sie über die dedizierte Infrastruktur von Capgo beim Google Play Store ein.

Was du lernen wirst

• Du lernst, wie du deine App über Capgo Native Build hochlädst
• Du lernst, wie du die Credentials für Capgo Native Build konfigurierst

Voraussetzungen

• Du brauchst ein aktives Google Developer-Konto
• Du musst Android Studio installiert haben
• Deine App muss sich erfolgreich mit Android Studio bauen lassen

Hinweis

Ich verwende für das Tutorial die folgende App: https://github.com/Cap-go/capgo-native-build-tutorial-app

Empfohlen: automatisiertes Onboarding

Du musst nichts davon manuell erledigen. Das Onboarding von Capgo erstellt und konfiguriert deine Android-Signierdaten (Keystore + Google Play Service Account) für dich – das ist der empfohlene Weg:

bunx @capgo/cli@latest build init --platform android

Die folgende manuelle Anleitung richtet sich nur an diejenigen, die ihre Credentials lieber selbst einrichten oder genau verstehen wollen, was Capgo unter der Haube macht.

Der erste manuelle Build

Bevor wir anfangen, die App mit Capgo zu bauen, sollten wir sie zunächst einrichten und einen ersten Android-Build manuell durchführen. Ein manueller Build hat einige Vorteile:

• Du bereitest die Credentials für den späteren Capgo Build vor
• Du erstellst einen Eintrag in der Play Store Console

Die App manuell mit Android Studio bauen

Bevor wir die App mit Capgo bauen können, müssen wir sie manuell in Android Studio bauen.

1. Android Studio öffnen

   Ausführen bunx cap open android um das Android-Studio-Projekt zu öffnen.

2. Klicken Sie auf Build -> Generate Signed App Bundles / APKs

3. Wähle Android App Bundle und klicken Sie auf Next

Einen Keystore erstellen

Aktuell fehlt die Keystore-Datei. Diese Datei wird verwendet, um deine App zu signieren, damit Google weiß, dass du die App erstellt hast. Um sie zu generieren, verwenden wir die GUI-Methode, die Android Studio bereitstellt. Es gibt auch eine Möglichkeit, dies über die Kommandozeile zu tun, aber das behandeln wir in diesem Tutorial nicht.

1. Klicken Sie auf Create new

2. Pfad zum Keystore angeben

   Achtung

   Dies MUSS GESPEICHERT WERDEN - wird später verwendet

3. Key-Store-Passwort festlegen

   Hinweis

   Ich empfehle, für Key Store und Key Alias dasselbe Passwort zu verwenden.

   Achtung

   Dies MUSS GESPEICHERT WERDEN - wird später verwendet

4. Fülle den Rest des Formulars aus

   1. Lasse den Key Alias unverändert (key0)
   2. Trage die Zertifikatsdetails ein. Ich habe sie mit Fake-Daten ausgefüllt, du solltest aber deine eigenen Daten eintragen.

   

5. Klicken Sie auf OK

Manuellen Build abschließen

1. Stelle sicher, dass alle Details für den Keystore korrekt ausgefüllt sind, und klicke auf Next

2. Wähle die release Build-Variante aus und klicke auf Create

3. Nach dem erfolgreichen Build erscheint dieser Bildschirm

   1. Dieses Popup zeigt an, dass der Build erfolgreich war.
   2. Klicke auf die locate Schaltfläche – dadurch öffnet sich der Datei-Explorer, und du solltest den Build dort sehen.

4. Stelle sicher, dass du den Build im Datei-Explorer sehen kannst

App in der Play Store Console erstellen

1. Gehe zu die Google Play Console

2. Wähle das richtige Developer-Konto aus

3. Klicken Sie auf Create app

4. App-Name und Sprache auswählen

5. App-Kategorie auswählen und ob die App kostenpflichtig oder kostenlos ist

6. Akzeptiere die Geschäftsbedingungen

   Achtung

   Stelle sicher, dass du die Geschäftsbedingungen gelesen hast, bevor du sie akzeptierst.

7. Klicken Sie auf Create

Interne Testgruppe erstellen

Nachdem du die App erstellt hast, kannst du eine interne Testgruppe anlegen. Da ich die App nicht für alle im Play Store veröffentlichen werde, muss ich eine interne Testgruppe erstellen.

Hinweis

Internes Testing ist immer noch der schnellste Weg, um deinen über Play verteilten Build vor einem echten Launch einem Smoke-Test zu unterziehen.

Wenn dein Developer-Account ein persönliches Konto ist, das nach dem 13. November 2023 erstellt wurde, ersetzt internes Testing es nicht die Closed-Testing-Anforderung für den Produktionszugriff nicht. Du brauchst weiterhin einen geschlossenen Test mit mindestens 12 angemeldeten Testnutzern an 14 aufeinanderfolgenden Tagen vor der Produktion.

1. Gehe zu internal testing Klicken Sie auf Test and release -> Testing -> Internal testing

   

2. Klicken Sie auf Testers

3. Klicken Sie auf Create email list

4. E-Mail-Liste benennen

5. E-Mail-Adressen der Tester hinzufügen

6. Drücken Enter und klicken Sie auf Save

7. Klicken Sie auf Create group

8. Stellen Sie sicher, dass die neue Liste ausgewählt ist, und klicken Sie auf Save

App in die interne Testgruppe hochladen

Da du die interne Testgruppe erstellt hast, kannst du die App jetzt an die interne Testgruppe hochladen.

1. Gehe zu Test and release -> Testing -> Internal testing

2. Klicke auf die Releases Button

3. Klicken Sie auf Create new release

4. Klicken Sie auf Upload

5. AAB-Datei auswählen

   Achtung

   Stelle sicher, dass du die AAB-Datei auswählst, die du manuell mit Android Studio gebaut hast. Wenn diese Datei nicht denselben Keystore verwendet wie der für den Capgo-Build, wird der Capgo Native Build fehlschlagen.

6. Warten, bis die AAB-Datei hochgeladen ist

7. Klicken Sie auf Next

8. Fehler beheben

   Persönlich sehe ich an dieser Stelle diesen Fehler

   

   Das liegt daran, dass ich meine Telefonnummer noch nicht verifiziert habe. Ich werde das erledigen und mit dem Tutorial fortfahren.

9. Klicken Sie auf Save and publish Damit wird die App für die interne Testgruppe veröffentlicht.

10. Veröffentlichung bestätigen

11. Stelle sicher, dass die App veröffentlicht ist

12. Deinen temporären App-Namen abrufen

Einladung zur internen Testgruppe annehmen

Nachdem du die App in die interne Testgruppe hochgeladen hast, kannst du nun die Einladung zur internen Testgruppe annehmen.

1. Gehe zu Test and release -> Testing -> Internal testing

2. Klicken Sie auf Testers

3. Klicken Sie auf Copy link

4. Sende den Link an dein Handy, öffne ihn im Browser und klicke auf Accept

5. Bestätige, dass die Einladung angenommen wurde, und klicke auf „Im Play Store herunterladen“

6. App installieren

   1. Falls du die App bereits über Android Studio installiert hast, klicke auf den uninstall Button
   2. Klicke auf die install Button
   3. Öffne die App und bestätige, dass sie erfolgreich heruntergeladen wurde

   Achtung

   Falls die App im Play Store nicht erscheint, stelle sicher, dass du das richtige Konto im Play Store ausgewählt hast.

Konfiguration von Capgo Native Build (Android)

Jetzt kannst du mit dem Setup von Capgo Native Build beginnen. Glückwunsch 🎉!

Voraussetzung	Flagge	Beschreibung	Erforderlich
Keystore-Datei	--keystore <path>	Pfad zu deiner .jks/.keystore Datei zum Signieren der APK/AAB.	Ja
Keystore-Alias	--keystore-alias <alias>	Alias-Name des Schlüssels im Keystore.	Ja
Keystore-Key-Passwort	--keystore-key-password <password>	Passwort für den Key. Wenn die Passwörter für Key und Store identisch sind, reicht ein einzelnes Passwort.	Siehe Hinweis unten
Keystore-Store-Passwort	--keystore-store-password <password>	Passwort für das Keystore. Wenn Key- und Store-Passwort identisch sind, reicht ein einzelnes Passwort.	Siehe Hinweis unten
Google Play Service Account	--play-config <path>	JSON-Servicekonto-Datei für Play-Store-Uploads.	Ja

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

Hinweis

Wenn das Key- und das Store-Passwort identisch sind, nur eines davon angeben --keystore-key-password oder --keystore-store-password.

Keystore, Keystore-Passwort, Key-Passwort des Keystores, Keystore-Alias

If you have followed the manuellen Build-Anweisungenbefolgt hast, sollte der Keystore bereits generiert sein. Wenn du die Anweisungen nicht befolgt hast, befolge sie bitte, um den Keystore zu generieren.

Google Play Service Account

Die Erstellung des Google Play Service Accounts ist ein manueller und komplexer Prozess. Er ist jedoch erforderlich, um Ihre App auf Google Play hochzuladen. Bitte beachten Sie Folgendes:

• Du DU MUSST der Inhaber des Developer Accounts sein. Andernfalls kannst du den Service Account nicht einrichten.
• Du musst ein neues Google Cloud Project erstellen (getrennt von deinem Google Play Account)

Lass uns anfangen.

1. Gehe zu Google Cloud Console

2. Klicke auf die Projektauswahl

3. Falls du bereits ein Projekt hast, wähle es aus. Andernfalls erstelle ein neues Projekt:

   Hinweis

   Die folgenden Screenshots sind nur beispielhaft – wähle einen Namen, der zu deinem Projekt passt.

   1. Klicken Sie auf New project
   2. Gib deinem Projekt einen Namen und klicke auf Create
   3. Stelle sicher, dass du im richtigen Projekt bist

4. Klicke auf die Suchleiste und suche nach service accounts und klicke darauf

5. Klicken Sie auf Create service account

6. Fülle das Formular für das Service Account aus und klicke auf Done

   1. Ich empfehle, den Namen wie folgt zu setzen: Capgo Native Build Service Account
   2. Für die Service Account ID empfehle ich, sie wie folgt zu setzen: capgo-native-build-service-acc
   3. Bei der Beschreibung müssen Sie nichts eintragen, aber ich empfehle, sie wie folgt auszufüllen: Allows Capgo Native Build to build and submit the app to the Play Store

   

7. Klicke auf das neu erstellte Service Account. Das neue Service Account sollte jetzt in der Liste stehen. Klicke darauf.

   Hinweis

   Kopiere auch diese E-Mail-Adresse, du brauchst sie später.

8. Klicke auf die Keys Tab

9. Klicken Sie auf Add Key und Create new key

10. Klicken Sie auf JSON und Create

    Achtung

    Klicken Sie auf Create wird ein neuer Key erstellt und die JSON-Datei auf deinen lokalen Rechner heruntergeladen.

    Speichere die JSON-Datei an einem sicheren Ort. Sie wird WIRD später benötigt.

11. JSON-Datei herunterladen Die JSON-Datei sollte automatisch heruntergeladen worden sein. Du kannst auch auf close klicken, um das Fenster zu schließen.

Play Store API-Zugriff für den Service Account gewähren

Der neu erstellte Service-Account hat noch keinen Zugriff auf den Play Store API. Um diesen zu gewähren, gehe zur Play Store Console.

1. Gehe zu die Google Play Console
2. Wähle das richtige Developer-Konto aus
3. Klicken Sie auf Users and permissions
4. Klicken Sie auf Invite new users
5. Kopiere die E-Mail-Adresse des Service-Accounts
6. Gehe zu Account permissions und erteile die minimal erforderlichen Berechtigungen:
   • Unter App permissions, erteile Zugriff auf deine App.
   • Unter Releases, aktivieren Create, edit, and roll out releases.
   • Falls dein Workflow Play App Signing nutzt, aktiviere die entsprechende Signing-Berechtigung.
   • Falls du unsicher bist, nutze Admin nur während des Setups und reduziere die Berechtigungen danach.
7. Klicken Sie auf Invite user
8. Einladung bestätigen
9. Bestätigen, dass der Nutzer eingeladen wurde

Credentials speichern

Du bist nun bereit, die Anmeldedaten zu speichern und deinen ersten Build auszuführen. Du kannst die Anmeldedaten mit dem folgenden Befehl speichern:

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

CI/CD-Setup (GitHub Actions)

Falls du bereits abgeschlossen hast Keystore, Keystore-Passwort, Key-Passwort des Keystores, Keystore-Alias und Google Play Service Account, du hast bereits alles für CI/CD bereit. Dieser Abschnitt erklärt nur, wie du diese Werte als GitHub Actions Secrets und Umgebungsvariablen übergibst.

1) Credential-Dateien in einzeiliges Base64 konvertieren

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | tr -d '\n' > keystore_base64.txt

# Google Play service account JSON
base64 -i ./play-store-service-account.json | tr -d '\n' > play_config_base64.txt

Tipp

GitHub Secrets sollten einzeilige Werte sein. tr -d '\n' entfernt Zeilenumbrüche aus der base64-Ausgabe.

2) Repository-Secrets erstellen

Unter GitHub > Repository > Settings > Secrets and variables > Actions, hinzufügen:

Name des Secrets	Wert
CAPGO_TOKEN	Dein Capgo API Token
APP_ID	Deine Capgo App-ID (Beispiel: com.example.app)
ANDROID_KEYSTORE_FILE	Inhalt von keystore_base64.txt
KEYSTORE_KEY_ALIAS	Keystore-Alias von Keystore, Keystore-Passwort, Key-Passwort des Keystores, Keystore-Alias
KEYSTORE_KEY_PASSWORD	Keystore-Key-Passwort
KEYSTORE_STORE_PASSWORD	Keystore-Store-Passwort
PLAY_CONFIG_JSON	Inhalt von play_config_base64.txt

Hinweis

Wenn Key- und Store-Passwort identisch sind, kannst du auch nur eines angeben KEYSTORE_KEY_PASSWORD oder KEYSTORE_STORE_PASSWORD.

3) Nutze Umgebungsvariablen in deinem GitHub Actions Workflow

.github/workflows/android-build.yml

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build request ${{ secrets.APP_ID }} --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

Tipp

Mit diesem Setup übergibt die CI Credentials ausschließlich über Umgebungsvariablen. Du musst Signing-Files nicht committen oder als Workflow-Artifacts hochladen.

Build ausführen

Glückwunsch 🎉! Du bist jetzt bereit für deinen ersten Build.

Führe aus:

bunx @capgo/cli@latest build request com.example.app --platform android

Und damit startet der Build-Prozess 🍾🥂

Play-Release zur Überprüfung einreichen

Standardmäßig werden Android-Release-Builds zu Google Play hochgeladen und können inaktiv bleiben, bis du den Release in der Play Console abschließt. Wenn dein CI-Release den Play-Release automatisch einreichen soll, übergib --submit-to-store-review mit einem Release-Build:

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --android-track production \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales"

Achtung

Unter Android, --submit-to-store-review standardmäßig auf den Produktion Track mit release_status: completed wenn du keinen Track setzt. Der kann für 100 % der Nutzer live gehen. Übergib --android-track internal (oder alpha / beta) — oder setze PLAY_STORE_TRACK in der CI — um das fertige Release auf einem Non-Production-Track zu halten. Nutze --android-release-status / PLAY_STORE_RELEASE_STATUS wenn du einen anderen Status als completed.

Dies erfordert dieselbe Einrichtung des Google Play Service-Accounts wie der normale Upload-Pfad (PLAY_CONFIG_JSON in der CI oder lokal gespeicherte Android-Credentials). --store-release-name wird als Google Play version_name. --store-release-notes ist der Fallback-Changelog für Play, und jedes --store-release-notes-locale "locale=notes" schreibt einen lokalisierten Play-Changelog für diese Locale. Capgo sendet das Play-Release als completed es sei denn, du überschreibst es --android-release-status; wenn Managed Publishing in der Play Console aktiviert ist, kann Google nach der Genehmigung trotzdem auf deine manuelle Veröffentlichung warten.

Weiter mit Android Builds

Wenn du es nutzt Android-Builds um CI/CD-Automatisierung zu planen, verbinde es mit Capgo CI/CD für den Produkt-Workflow in Capgo CI/CD, Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds, Capgo Integrationen für den Produkt-Workflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in der CI/CD-Integration und GitHub Actions-Integration für die Implementierungsdetails in der GitHub Actions-Integration.