Data Plan Agent API

Motivation

Wie in der Übersicht erwähnt, muss der Betreiber je nach den Anwendungsfällen, die er unterstützen möchte, eine Kombination aus der Google Mobile Data Plan Sharing API und der Data Plan Agent API implementieren. In diesem Dokument wird die Data Plan Agent API beschrieben, die Google verwendet, um die Mobilfunkverträge des Nutzers zu identifizieren, Informationen zu diesen Verträgen abzurufen und Datenvolumen zu kaufen.

Authentifizierung

Bevor GTAF anrufen kann, muss die DPA GTAF authentifizieren. Im Rahmen des Onboarding-Prozesses für Betreiber prüfen wir die Gültigkeit des DPA-SSL-Zertifikats. Derzeit ist die Verwendung von OAuth2 für die gegenseitige Authentifizierung ERFORDERLICH.

API-Beschreibung

GTAF verwendet den Benutzerschlüssel, der einen Abonnenten des Betreibers identifiziert, wenn die DPA des Betreibers abgefragt wird. Wenn GTAF die DPA im Namen von Anwendungen abfragt, die Zugriff auf die MSISDN haben, DARF GTAF die MSISDN verwenden. Auf einer übergeordneten Ebene umfasst die vorgeschlagene Data Plan Agent API die folgenden Komponenten:

1. Mechanismus zum Abfragen des Status des Nutzerdatentarifs.
2. Mechanismus zum Abfragen der DPA nach Datenabo-Angeboten für den Nutzer.
3. Mechanismus zum Ändern des Datentarifs des Nutzers (z.B. zum Kauf eines neuen Tarifs).
4. Mechanismus, um zu prüfen, ob ein Nutzer berechtigt ist, ein bestimmtes Datenvolumen zu kaufen.
5. Mechanismus für GTAF zur Registrierung von MSISDNs bei der DPA.
6. Mechanismus für GTAF, um zu prüfen, ob sich die DPA in einem fehlerfreien Zustand befindet.

Im Rest dieses Dokuments werden die einzelnen API-Komponenten näher erläutert. Sofern nicht ausdrücklich anders angegeben, MUSS die gesamte Kommunikation über HTTPS (mit einem gültigen DPA-SSL-Zertifikat) erfolgen. Je nach den tatsächlich unterstützten Funktionen kann ein Betreiber alle oder nur einen Teil dieser API-Komponenten implementieren.

Status des Datentarifs abfragen

GTAF-DPA-Interaktion

Abbildung 4. Anrufablauf zum Anfordern und Empfangen von Informationen zum Nutzerdatentarif.

Abbildung 4 zeigt den Anrufablauf, wenn ein Client den Status des Datentarifs des Nutzers und andere Informationen zum Datentarif abfragt. Dieser Anrufablauf wird für API-Aufrufe verwendet, die vom Client auf dem UE ausgelöst werden.

1. Der Client fordert den Status des Datentarifs und/oder andere Informationen an, indem er eine private Google-API aufruft. Der Client fügt den Nutzer-Schlüssel in die Anfrage an GTAF ein.
2. GTAF verwendet den Nutzerschlüssel und eine Client-ID, um die DPA des Betreibers abzufragen. Die unterstützten Client-IDs sind mobiledataplan und youtube. Wenn die DPA einen Aufruf mit einem dieser Client-IDs empfängt, MUSS sie mit Planinformationen antworten, die vom Client verwendet werden können.
3. GTAF gibt die angeforderten Informationen an den Client zurück und die Planinformationen werden von GTAF bis zum Ablaufdatum, das im DPA angegeben ist, im Cache gespeichert.

Schritt 1 und Schritt 3 in Abbildung 4 sind private Google APIs und werden daher nicht weiter beschrieben. Schritt 2 ist eine öffentliche API, die im Folgenden beschrieben wird. Der DPA MUSS den Cache-Control: no-cache-HTTP-Header berücksichtigen, wenn diese API-Aufrufe von GTAF bereitgestellt werden.

Status des Plans

GTAF sendet die folgende HTTP-Anfrage, um den Planstatus abzurufen:

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

Der Client, in dessen Namen GTAF die Datenschutzbehörde kontaktiert, wird anhand von CLIENT_ID identifiziert. Je nach Vereinbarung zwischen dem Google-Client und dem Mobilfunkanbieter kann die Antwort auf GTAF angepasst werden. Das Format der Antwort ist ein JSON-Objekt, das einen PlanStatus darstellt.

{
  "plans": [{
    "planName": "ACME1",
    "planId": "1",
    "planCategory": "PREPAID",
    "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
    "planModules": [{
      "moduleName": "Giga Plan", // req.
      "trafficCategories": ["GENERIC"],
      "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
      "overUsagePolicy": "BLOCKED",
      "maxRateKbps": "1500",
      "description": "1GB for a month", // req.
      "coarseBalanceLevel": "HIGH_QUOTA"
    }]
  }],
  "languageCode": "en-US", // req.
  "expireTime": "2018-06-14T08:41:27-07:00", // req.
  "updateTime": "2018-06-07T07:41:22-07:00", // req.
  "title": "Prepaid Plan"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

Die Anfrage MUSS einen Accept-Language-Header enthalten, der die Sprache angibt, in der die für Menschen lesbaren Strings (z.B. Planbeschreibungen) sein sollen.

Bei Postpaid-Tarifen MUSS expirationTime das Datum der Tarifwiederholung sein, d. h. das Datum, an dem das Datenvolumen aktualisiert bzw. neu geladen wird.

Jedes Tarifmodul kann mehrere Traffic-Kategorien für Tarifmodule (PMTCs)) enthalten, um den Fall zu modellieren, in dem ein Tarifmodul von mehreren Apps gemeinsam genutzt wird (z.B. 500 MB für Spiele und Musik Die folgenden PMTCs sind vordefiniert: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Es wird erwartet, dass Betreiber sich an die einzelnen Google-Teams wenden, um die für die verschiedenen Google-Anwendungen relevanten Traffic-Kategorien und ihre Semantik zu vereinbaren.

Planangebote abfragen

GTAF sendet die folgende HTTP-Anfrage, um Tarifangebote vom Mobilfunkanbieter zu erhalten:

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

Der Client, in dessen Namen GTAF die Datenschutzbehörde kontaktiert, wird anhand von CLIENT_ID identifiziert. Je nach Vereinbarung zwischen dem Google-Client und dem Mobilfunkanbieter kann die Antwort auf GTAF angepasst werden. Der optionale Kontextparameter gibt den Anwendungskontext an, in dem die Anfrage gestellt wird. Normalerweise ist dies ein String, den die Anwendung über GTAF an den Betreiber übergibt.

Der Antworttext enthält eine Instanz von PlanOffer.

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850"
      }
    ],
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

Die Reihenfolge der Tarife im offers-Array KANN die Reihenfolge bestimmen, in der Tarife Nutzern präsentiert werden. Wenn die Anwendung aufgrund von Einschränkungen der Benutzeroberfläche oder anderer Einschränkungen nur x Tarife präsentieren kann und die Antwort y > x Tarife enthält, DÜRFEN nur die ersten x Tarife präsentiert werden. GTAF gibt nur bis zu 10 Tarife weiter, wenn die Anwendung, die Angebote abfragt, die Benutzeroberfläche für mobile Datentarife ist, die Teil der Google Play-Dienste ist. So soll eine gute Nutzererfahrung für Nutzer von Google Play-Diensten gewährleistet werden.

Die Strings in offerInfo sollen es dem Nutzer ermöglichen, mehr über das Angebot zu erfahren. Außerdem bieten sie eine Möglichkeit, den Erhalt weiterer Angebote in Anwendungen zu deaktivieren. Der Grund für diese Felder ist, dass einige Mobilfunkanbieter für In-App-Käufe keine Einwilligung der Endnutzer benötigen, sondern einen Mechanismus, mit dem Nutzer die Funktion deaktivieren können. Der Betreiber MUSS einen Mechanismus haben, um eine Kaufanfrage für jedes Angebot zu erfüllen, das dem Nutzer gemacht wird. Das Verfahren, über das dem Nutzer Käufe in Rechnung gestellt werden, kann GTAF über die Option formOfPayment in der Antwort mitgeteilt werden.

Die Anfrage MUSS einen Accept-Language-Header enthalten, der die Sprache angibt, in der die für Menschen lesbaren Strings (z.B. Planbeschreibungen) sein sollen.

Datenerhebung

Die Purchase Plan API definiert, wie GTAF Pläne über die DPA erwerben kann. Die GTAF initiiert die Transaktion zum Kauf eines Datentarifs für die DPA. Die Anfrage MUSS eine eindeutige Transaktions-ID (transactionId) enthalten, um Anfragen nachzuverfolgen und die doppelte Ausführung von Transaktionen zu vermeiden. Der DPA MUSS mit einer Antwort über Erfolg/Fehler reagieren.

Transaktionsanfrage

Wenn GTAF eine Anfrage von einem Client erhält, wird eine POST-Anfrage an die DPA gesendet. Die URL der Anfrage lautet:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

Dabei ist userKey entweder ein CPID oder ein MSISDN. Der Text der Anfrage ist eine Instanz von TransactionRequest, die die folgenden Felder enthält:

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

Transaktionsantwort

Der DPA MUSS im Fehlerfall die häufigen Fehlerursachen zurückgeben. Außerdem stehen die folgenden Fehlercodes für fehlgeschlagene Transaktionen:

• Die DPA gibt den Fehlercode „400 BAD REQUEST“ zurück, der GTAF angibt, dass die gekaufte Tarif-ID ungültig ist.
• Die DPA gibt den Fehlercode 402 PAYMENT REQUIRED zurück, der GTAF anzeigt, dass der Nutzer nicht genügend Guthaben hat, um den Kauf abzuschließen.
• Die DPA gibt den Fehlercode 409 CONFLICT zurück, der GTAF darüber informiert, dass das zu kaufende Abo nicht mit dem aktuellen Produktmix des Nutzers kompatibel ist. Wenn die Richtlinie für Betreiberdatentarife beispielsweise das Mischen von Postpaid- und Prepaid-Tarifen nicht zulässt, führt der Versuch, einen Prepaid-Tarif für einen Postpaid-Nutzer zu kaufen, zu einem 409 CONFLICT-Fehler.
• Die DPA gibt den Fehlercode 403 FORBIDDEN zurück, der GTAF darüber informiert, dass die aktuelle Transaktion ein Duplikat einer zuvor ausgegebenen Transaktion ist. Die DPA SOLLTE die folgenden Fehlerursachen als Antwort zurückgeben:
  • Wenn die vorherige Transaktion fehlgeschlagen ist, wird die Fehlerursache angegeben.
  • Wenn die vorherige Transaktion erfolgreich war, DUPLICATE_TRANSACTION.
  • Wenn sich die vorherige Transaktion noch in der Warteschlange befindet, wird REQUEST_QUEUED zurückgegeben.

Das DPA MUSS nur für eine erfolgreich ausgeführte Transaktion oder eine in die Warteschlange gestellte Transaktion eine 200-OK-Antwort generieren. Bei einer in die Warteschlange eingereihten Transaktion füllt der DPA nur den Transaktionsstatus aus und lässt andere Felder in der Antwort leer. Der DPA MUSS GTAF mit einer Antwort zurückrufen, sobald eine in die Warteschlange gestellte Transaktion verarbeitet wurde. Der Antworttext ist eine Instanz von TransactionResponse, die die folgenden Details enthält:

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

Wenn planActivationTime fehlt, MUSS GTAF davon ausgehen, dass der Plan aktiviert wurde.

Einwilligung

GTAF KANN die folgende Anfrage stellen, um die Einstellung zur Nutzereinwilligung an den Mobilfunkanbieter weiterzugeben.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

Dabei ist userKey entweder ein CPID oder ein MSISDN. Der Text der Anfrage ist eine Instanz von SetConsentStatusRequest.

Wenn der Vorgang erfolgreich ist, sollte der Antworttext leer sein.

Voraussetzungen

GTAF kann die folgende Anfrage zur Berechtigung stellen, um zu prüfen, ob ein Nutzer berechtigt ist, einen Tarif zu kaufen.

GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}

planId ist die eindeutige Kennzeichnung für den Tarif, mit der der Tarif im Namen des Nutzers gekauft werden kann (siehe Data Purchase). Wenn planId nicht angegeben ist, MUSS die DPA alle Pläne zurückgeben, die von diesem Nutzer gekauft werden können.

Der DPA MUSS im Fehlerfall die häufigen Fehlerursachen zurückgeben. Außerdem MUSS die DPA in den folgenden Fehlerfällen einen Fehler zurückgeben:

• Die DPA gibt den Fehlercode 400 BAD REQUEST zurück, der GTAF darauf hinweist, dass planId ungültig ist.
• Die DPA gibt den Fehlercode 409 CONFLICT zurück, der angibt, dass planId nicht mit dem Datentarif des Nutzers kompatibel ist.

Andernfalls MUSS der DPA eine 200-OK-Antwort zurückgeben. Das Format einer erfolgreichen EligibilityResponse ist:

{
  "eligiblePlans":
  [
   {
    "planId": string,   // Plan identifier. Can be used to
                        // refer to the plan during
                        // offers, etc. (req.)
   }
  ]
}

Wenn die Anfrage ein planId enthält, enthält die Antwort nur diesen Plan. Andernfalls enthält die Liste alle Tarife, die der Nutzer kaufen kann. Wenn planId leer ist und die DPA die Rückgabe der Liste der infrage kommenden Tarife nicht unterstützt, MUSS ein 400 BAD REQUEST-Fehler zurückgegeben werden.

MSISDN-Registrierungsendpunkt

Wenn Anwendungen mit Zugriff auf die MSISDN bereitgestellt werden sollen, registriert GTAF die MSISDN bei der Datenschutzbehörde. GTAF registriert MSISDNs nur, wenn es Anwendungen gibt, die über die Google Mobile Data Plan Sharing API bereitgestellt werden und bei denen der DPA Informationen über Google-APIs an GTAF sendet. Um die MSISDN zu registrieren, sendet GTAF eine POST-Anfrage an die DPA:

POST DPA_URL/register

Der Hauptteil der Anfrage ist eine Instanz von RegistrationRequest.

{
  "msisdn": "<msisdn_string>"
}

Wenn die Registrierung der MSISDN erfolgreich ist, MUSS die DPA eine 200 OK-Antwort mit RegistrationResponse zurückgeben. Das Format des JSON ist:

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

Die DPA SOLLTE dann bis zum Ablauf von expirationTime Updates zum Datentarif des Nutzers an GTAF senden.

Wenn ein Fehler auftritt, sollte eine ErrorResponse zurückgegeben werden:

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

Die vollständige Liste der möglichen cause-Werte und HTTP-Statuscodes für verschiedene Fehlerbedingungen finden Sie hier. Insbesondere wenn eine MSISDN-Registrierungsanfrage für einen Nutzer eingeht, der Roaming verwendet oder der nicht zugestimmt hat, dass seine Tarifinformationen an Google weitergegeben werden, MUSS die DPA den HTTP-Statuscode 403 zurückgeben.

Monitoring API

In einigen Anwendungsfällen muss GTAF die DPA überwachen und DPA-Fehler erkennen. Für diese Anwendungsfälle haben wir eine Monitoring API definiert.

API-Definition

Die Monitoring API sollte über einen HTTP-GET-Request unter der folgenden URL verfügbar sein:

DPA_URL/dpaStatus

Wenn die Vereinbarung zum Datenschutz und alle zugehörigen Back-Ends ordnungsgemäß funktionieren, sollte die DPA auf diese Anfrage mit dem HTTP-Statuscode 200 und einem Antworttext mit einer Instanz von DpaStatus antworten.

{
    "status": enum(DpaStatusEnum),
    "message": "<optional human-readable status description>"
}

Wenn die DPA oder eines ihrer Back-Ends nicht ordnungsgemäß funktioniert, sollte sie mit dem HTTP-Statuscode 500 und einem Antworttext mit einer Instanz von DpaStatus antworten.

DPA-Verhalten

Wenn ein Fehler erkannt wird, muss die DPA für alle dpaStatus-Abfragen den Status „UNAVAILABLE“ zurückgeben. Außerdem muss das Senden von Informationen zum Datentarif mit langen Cache-Zeiträumen eingestellt werden. Die Übermittlung von Antworten mit langen Cache-Zeiträumen kann auf zwei Arten beendet werden:

1. Legen Sie kurze Cache-Ablaufzeiten fest.
2. Senden Sie keine Informationen zum Datentarif mehr.

GTAF-Verhalten

GTAF fragt den dpaStatus regelmäßig ab. Wenn ein DPA-Fehler erkannt wird (basierend auf der Antwort „UNAVAILABLE“), wird der Cache für den Betreiber geleert.

Fehlerfälle

Im Fehlerfall wird erwartet, dass die DPA einen HTTP-Statuscode zurückgibt, der einem der folgenden entspricht:

• Der Nutzer befindet sich derzeit im Roaming und die DPA-Abfrage ist für ihn deaktiviert. Die DPA gibt einen 403-Fehler zurück.
• Die DPA gibt den Fehlercode 404 NOT_FOUND zurück, der GTAF darüber informiert, dass der Benutzerschlüssel ungültig ist (d.h. kein vorhandener Benutzerschlüssel).
• Die DPA gibt den Fehlercode „410 GONE“ zurück, der GTAF anzeigt, dass der Client einen neuen Nutzer-Schlüssel abrufen sollte, wenn key_type = CPID und die CPID abgelaufen ist.
• Die DPA gibt den Fehlercode 501 NOT_IMPLEMENTED zurück, der angibt, dass dieser Aufruf nicht unterstützt wird.
• Der Dienst steht vorübergehend nicht zur Verfügung. Die DPA gibt „503 SERVICE UNAVAILABLE“ (503 DIENST NICHT VERFÜGBAR) mit dem Retry-After-Header zurück, der angibt, wann ein neuer Versuch unternommen werden kann.
• Die DPA gibt für alle anderen nicht angegebenen Fehler den Fehlercode „500 INTERNAL SERVER ERROR“ zurück.
• Der DPA gibt den Fehler „429 TOO_MANY_REQUESTS“ mit dem Header „Retry-After“ zurück, der angibt, dass GTAF zu viele Anfragen an den DPA sendet.
• Die DPA gibt den Fehler „409 CONFLICT“ zurück, was darauf hinweist, dass die Anfrage aufgrund eines Konflikts mit dem aktuellen Status der DPA nicht abgeschlossen werden kann.

In allen Fehlerfällen MUSS der Text der HTTP-Antwort ein JSON-Objekt mit weiteren Informationen zum Fehler enthalten. Der Text der Fehlerantwort MUSS eine Instanz von ErrorResponse enthalten.

{
  "error": string,
  "cause": enum(ErrorCause)
}

Die derzeit definierten cause-Werte sind in der API-Referenz zu ErrorCause aufgeführt.

Andernfalls gibt die DPA „200 OK“ zurück. Die cause-Werte werden für alle Antworten verwendet.

Internationalisierung

GTAF-Anfragen an die DPA enthalten einen Accept-Language-Header, der die Sprache angibt, in der die für Menschen lesbaren Strings (z.B. Planbeschreibungen) sein sollen. Außerdem enthalten DPA-Antworten (PlanStatus, PlanOffers) das erforderliche Feld „languageCode“, dessen Wert der BCP-47-Sprachcode ist (z.B. „en-US“) der Antwort.

Wenn die DPA die vom Nutzer angeforderte Sprache nicht unterstützt, kann sie eine Standardsprache verwenden und ihre Wahl über das Feld „languageCode“ angeben.