Leitfaden zur Back-End-Integration für die Monetarisierung außerhalb von Google Play Billing

Die Google Play Developer API bietet jetzt zusätzliche Funktionen zum Melden von Transaktionen aus einem System für die alternative Abrechnung oder externe Angebote. In diesem Leitfaden wird beschrieben, wie Sie Transaktionen mit alternativer Abrechnung oder externen Angeboten melden.

Es gibt einige Komponenten, die für die Verarbeitung von In-App-Käufen über Ihr Backend erforderlich sein können. Wenn Sie sie erstellen möchten, müssen Sie Ihre Backend-Integration wie unter Google Play Developer API konfigurieren beschrieben einrichten. Für alle Entwickler-Backendfunktionen, die nicht speziell für APIs zur alternativen Abrechnung oder externen Angeboten gelten, gelten die Anweisungen in der Dokumentation zum Google Play-Abrechnungssystem.

Neue externe Transaktionen an Google Play melden

Integrieren Sie Externaltransactions APIs, um Transaktionen zu melden, die außerhalb des Abrechnungssystems von Google Play in unterstützten Ländern stattfinden, einschließlich Transaktionen mit einem Wert von 0 $, die aus Käufen von kostenlosen Testzeiträumen resultieren. Transaktionen über Systeme zur alternativen Abrechnung oder externe Angebotssysteme dürfen nur für berechtigte Nutzerländer gestartet und gemeldet werden, wie im Rahmen der Programme zur alternativen Abrechnung oder externen Angebote zulässig ist. Andernfalls wird der API-Aufruf abgelehnt. Das gilt für alle Transaktionen, einschließlich Neukäufe, Verlängerungen, Aufstockungen, Upgrades und Downgrades.

Berichte zu externen Transaktionen

Sie sollten die Externaltransactions API anrufen, um eine externe Transaktion zu melden, nachdem die Zahlung über das alternative Abrechnungssystem oder das System für externe Angebote autorisiert wurde. Das gilt für alle Transaktionen, einschließlich der Erstaktivierung, Verlängerungen, Erstattungen usw. Alle Transaktionen müssen innerhalb von 24 Stunden nach dem Transaktionsereignis gemeldet werden.

Jede externe Transaktion wird mit einer externen Transaktions-ID erfasst. Bei wiederkehrenden Käufen (z. B. automatisch verlängerbaren Abos) müssen Sie die externe Transaktions-ID, die mit der ersten Transaktion im wiederkehrenden Kauf verknüpft ist, als Parameter für alle nachfolgenden Transaktionen senden, einschließlich Erstattungen. Dadurch werden die Transaktionen für diesen Kauf erfasst. Du sendest eine neue externe Transaktions-ID für Käufe, wenn sich das Produkt ändert (z. B. ein Upgrade oder Downgrade) oder wenn die wiederkehrende Transaktion storniert oder abgelaufen ist und dasselbe Produkt später noch einmal gekauft wird. Diese externe Transaktions-ID darf keine personenidentifizierbaren Informationen, urheberrechtlich geschützten oder vertraulichen Informationen enthalten.

Neuen Kauf melden

Jedes Mal, wenn ein neuer Kauf im alternativen Abrechnungssystem oder im System für externe Angebote erfolgreich ist, ist ein Aufruf der Externaltransactions API erforderlich. Für diese neuen Käufe müssen Sie einen eindeutigen externalTransactionId angeben, der mit dem Kauf in Ihrem Backend verknüpft ist, als Abfrageparameter. Diese externalTransactionId kann nicht innerhalb der Paket-ID derselben App wiederverwendet werden.

Die externalTransactionToken, die die App über die UserChoiceBillingListener-, AlternativeBillingOnlyReportingDetailsListener- oder ExternalOfferReportingDetailsListener-Callbacks erhält, ist auch als Teil des Anfragetexts für einmalige Käufe und Ersttransaktionen bei wiederkehrenden Käufen (z. B. Abos) erforderlich. In beiden Fällen wird dies als ursprüngliche Transaktion bezeichnet. Nach der ersten Transaktion ist die externalTransactionToken nicht mehr erforderlich. Melden Sie nachfolgende Transaktionen (z. B. Aboverlängerungen), indem Sie eine neue eindeutige externalTransactionId angeben. Weitere Informationen zum Melden nachfolgender Transaktionen finden Sie unter Nachfolgende Transaktionen für einen Kauf melden.

Beispiel:

  1. Ein Entwickler konfiguriert und aktiviert die alternative Abrechnung in seiner App.
  2. Nutzer 1 befindet sich in Südkorea, einem unterstützten Land, und versucht, product1 für 12.634, 10 KRW pro Monat mit einem einmonatigen kostenlosen Testzeitraum zu kaufen.
  3. Die App startet den Kaufvorgang mit dem ProductDetails für product1 und dem Angebot, das der Nutzer ausgewählt hat.
  4. Nutzer 1 wählt das alternative Abrechnungssystem des Entwicklers aus.
  5. Die UserChoiceBillingListener erhält den Wert my_token als externalTransactionToken.
  6. Der Entwickler sendet dann die relevanten Informationen an sein Backend (externalTransactionToken-Wert und gekaufte Produkte). Anschließend startet er den Kaufvorgang für product1 im alternativen Abrechnungssystem. Dieser Transaktion wird auf Entwicklerseite eine eindeutige Transaktions-ID zugewiesen, die für die Meldung an Google Play verwendet wird: 123-456-789. Die Transaktions-ID ist erforderlich, auch wenn der Nutzer ein kostenloses Probeabo nutzt.
  7. Nachdem die Transaktion für den Kauf im alternativen Abrechnungssystem erfolgt ist, meldet der Entwickler die Transaktion mit der folgenden Anfrage an Google Play. Sie wird anfangs als Transaktion ohne Wert erfasst, da der Nutzer einen kostenlosen Monat erhält.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Wenn Sie Transaktionen mit einem Nutzer aus Indien ausführen, bei dem die Steuer je nach Verwaltungsbezirk (z. B. Bundesstaat oder Provinz) variiert, geben Sie diesen Bezirk unter userTaxAddress an. Eine Liste der entsprechenden Verwaltungsgebiete finden Sie in der vordefinierten Liste von Strings im API-Referenzhandbuch.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

Nachfolgende Transaktionen für einen Kauf melden

In einigen Fällen ist demselben externen Kauf mehr als eine Nutzerzahlung zugeordnet (z. B. Aboverlängerungen oder Aufstockungen von Prepaid-Tarifen). Du kannst diese nachfolgenden Transaktionen mit derselben API in Externaltransactions melden. Wie im Hilfeartikel Neuen Kauf melden beschrieben, ist die externalTransactionToken für nachfolgende Transaktionen nicht erforderlich. Stattdessen wird für jede Verlängerungs- oder Aufladetransaktion eine neue eindeutige externalTransactionId als Abfrageparameter gesendet. Die ID der ursprünglichen Transaktion ist im Feld initialExternalTransactionId enthalten.

Im vorherigen Beispiel:

  1. Die erste Verlängerung von Nutzer 1 erfolgt über das alternative Abrechnungssystem. Die ursprüngliche Transaktions-ID lautete 123-456-789.
  2. Der Entwickler meldet die Transaktionswiederholung im URL-Suchparameter als externe Transaktions-ID für diese neue Transaktion und verweist im Feld initialExternalTransactionId auf die externe Transaktions-ID der ursprünglichen Transaktion.

Beispielanfrage:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Upgrade oder Downgrade melden

Wenn der Nutzer ein Abo im alternativen Abrechnungssystem hat, verwenden Sie denselben Endpunkt und dieselbe Funktion in der Externaltransactions API, um ein Upgrade oder Downgrade zu melden. Senden Sie dazu den externalTransactionToken, der der App für die Transaktion zum Upgrade oder Downgrade zur Verfügung gestellt wurde. Das funktioniert ähnlich wie beim Melden eines neuen Kaufs.

Von der manuellen Berichterstellung für Transaktionen der alternativen Abrechnung migrieren

Wenn Sie aktive Abos migrieren möchten, die abgeschlossen wurden, während Sie eine alternative Abrechnung ohne automatisiertes Melden angeboten haben, erstellen Sie eine neue Transaktion kostenlos mit dem Feld migratedTransactionProgram, anstatt initialExternalTransactionId oder externalTransactionToken anzugeben. Lege für jedes aktive Abo den Zeitpunkt fest, zu dem sich der Nutzer ursprünglich dafür registriert hat.transactionTime Melde anschließend jede nachfolgende Transaktion für diese Abos wie gewohnt über die APIs und gib dabei die initialExternalTransactionId an, die du oben zum Erstellen der Verlängerungstransaktionen verwendet hast. Nach der Migration müssen Sie die nachfolgenden Transaktionen für das Abo nicht mehr manuell melden, sofern sie über die auf dieser Seite beschriebenen automatisierten Methoden gemeldet werden.

Beachten Sie bei der Migration von Abos die geltenden Kontingentlimits, damit die Migration nicht zu einem Kontingentausfall führt. Wenn viele Abos migriert werden müssen, verteilen Sie die Migration auf mehrere Tage oder fordern Sie eine Kontingenterhöhung an.

Das Feld migratedTransactionProgram kann nur bei der Migration von manuellen Berichten verwendet werden. Sie wird eingestellt, sobald manuelle Berichte nicht mehr unterstützt werden.

Beispielanfrage:

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Google Play-Partnerprogramme melden

Entwickler, die an Partnerprogrammen wie dem Play Media Experience Program teilnehmen, müssen die transaction_program_code angeben, wenn sie externe Transaktionen melden. Wenn Sie ein berechtigter Entwickler sind, wenden Sie sich an Ihren Business Development Manager, um weitere Informationen zum Festlegen dieses Felds zu erhalten.

Erstattungen für Käufe bei Google Play melden

Integrieren Sie die Externaltransactions API, um Transaktionen zu melden, die Nutzern außerhalb des Abrechnungssystems von Google Play erstattet wurden. Damit Google Play richtig erkennen kann, welche Transaktion erstattet wurde, sollten Sie die entsprechende externalTransactionId für die zuvor gemeldete Transaktion als Teil der URL-Parameter angeben.

Geben Sie bei Erstattungen von Abokäufen die externalTransactionId der jeweiligen wiederkehrenden Zahlung des erstatteten Abos an.

Beispiel: Angenommen, für ein Abo sind die folgenden Transaktionen vorhanden:

  • Eine erste Transaktion mit der externen Transaktions-ID ABC.1234-5678-9012-34567
  • Die erste wiederkehrende Transaktion mit der externen Transaktions-ID ABC.1234-5678-9012-34567..0
  • Die zweite wiederkehrende Transaktion mit der externen Transaktions-ID ABC.1234-5678-9012-34567..1

Wenn Sie eine Erstattung aller Transaktionen für das Abo beantragen möchten, müssen Sie drei separate Erstattungsanträge stellen: einen für die erste Transaktion und zwei für die nachfolgenden Transaktionen.

Bei dieser Methode sind sowohl volle Erstattungen (d. h. der Betrag entspricht dem Betrag, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat) als auch teilweise Erstattungen (d. h. der Betrag ist niedriger als der Betrag, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat) zulässig. Bei teilweisen Erstattungen müssen Sie den erstatteten Betrag vor Steuern angeben.

API-Kontingente

Für die Externaltransactions API gelten wie für alle anderen Endpunkte in der Google Play Developer API tägliche API-Kontingente.

Außerdem gilt für die Externaltransactions API ein Limit von 1.200 Anfragen pro Minute für Aufrufe von Externaltransactions.createexternaltransaction oder Externaltransactions.refundexternaltransaction. Aufrufe von Externaltransactions.getexternaltransaction werden nicht auf das Limit von 1.200 QPM angerechnet.