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. Weitere Informationen dazu, wie sich GTAF beim DPA authentifiziert, finden Sie unter Data Plan Agent Authentication.
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.
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:
- Mechanismus zum Abfragen des Status des Nutzerdatentarifs.
- Mechanismus zum Abfragen der DPA nach Datenabo-Angeboten für den Nutzer.
- Mechanismus zum Ändern des Datentarifs des Nutzers (z.B. zum Kauf eines neuen Tarifs).
- Mechanismus zum Teilen der CPIDs, die zum Senden von Benachrichtigungen an Nutzer verwendet werden können.
- Mechanismus zum Teilen der Nutzerauswahl, ob sie sich für unseren Dienst registrieren möchten.
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.
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.
- 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.
- 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.
- 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 Datentarifs abfragen
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 Betreiber kann die DPA die Antwort auf GTAF anpassen. Im Erfolgsfall MUSS die DPA HTTP 200 OK mit einem Antworttext zurückgeben, der einen PlanStatus darstellt. Unter Fehlerfälle finden Sie die erwartete Antwort im Fehlerfall.
{
"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
}
}
}
}
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 Betreiber kann die DPA die Antwort auf GTAF anpassen. 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.
Bei Erfolg MUSS die DPA HTTP 200 OK mit einem Antworttext zurückgeben, der ein PlanOffer darstellt. Informationen zur erwarteten Antwort im Fehlerfall finden Sie unter Fehlerfälle.
{
"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",
"filterTags": ["repurchase", "all"]
}
],
"filters" : [
{
"tag": "repurchase",
"displayText": "REPURCHASE PLANS"
},
{
"tag": "all",
"displayText": "ALL PLANS"
}
]
"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 50 Tarife zurück, wenn die Anwendung, die Angebote abfragt, das Modul „Mobile Data Plan“ ist, das Teil von Google Play-Diensten ist. So soll eine gute Nutzererfahrung für Nutzer von Google Play-Diensten gewährleistet werden.
Die Upselling-Angebote haben „filterTags“ als optionalen Parameter. Dabei handelt es sich um ein Array von Tags, die an die einzelnen Tarife angehängt sind. Alle diese „filterTags“ müssen mit dem Tag übereinstimmen, das ein Objekt im Filter ist. Filter ist ein Objekt der ersten Ebene, das das Tupel<tag, displaytext=""> enthält. Filter ist eine konsolidierte Liste von Filtern, die in der Benutzeroberfläche gerendert werden. Nutzer konnten filtern, indem sie auf den DisplayText geklickt haben. Das Tag, das dem displayText entspricht, wird zum Filtern der Angebote verwendet.</tag,>
Der Betreiber MUSS ein Verfahren zur Erfüllung einer Kaufanfrage für jedes Angebot haben, das dem Nutzer unterbreitet wird. Der Mechanismus, über den dem Nutzer ein Kauf in Rechnung gestellt wird, kann mit GTAF über die Option formOfPayment in der Antwort kommuniziert werden.
Datenerhebung
Die Purchase Plan API definiert, wie GTAF Pläne über die DPA erwerben kann. GTAF leitet die Transaktion zum Kauf eines Datentarifs für die DPA ein. 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
Das DPA MUSS nur für eine erfolgreich ausgeführte Transaktion oder eine in die Warteschlange gestellte Transaktion eine 200-OK-Antwort generieren. Unter Fehlerfälle finden Sie Informationen zur erwarteten Antwort im Fehlerfall. 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.
CPID registrieren
Wenn ein Client, der Benachrichtigungen unterstützt, einen neuen CPID vom CPID-Endpunkt erhält, registriert er den CPID bei GTAF, sofern die Clientbedingungen dies zulassen. Wenn der Client den CPID erfolgreich bei GTAF registriert, registriert GTAF den CPID bei der DPA mit dem folgenden API-Aufruf:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Dabei ist userKey die CPID und die einzige unterstützte CLIENT_ID ist mobiledataplan. Der Text der Anfrage ist eine Instanz von RegisterCpidRequest und enthält die Zeit, nach der die CPID nicht mehr zum Senden von Benachrichtigungen verwendet werden kann. Er sieht so aus:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Diese API ist nur für Mobilfunkanbieter relevant, die das Modul „Mobile Data Plan“ in Google Play-Diensten unterstützen möchten. Damit Benachrichtigungen zuverlässig an den Nutzer gesendet werden können, darf der DPA die zuletzt registrierte CPID für jeden Nutzer speichern. Weitere Informationen zur Verwendung der registrierten CPID zum Senden von Benachrichtigungen finden Sie unter CPID auswählen.
Die DPA muss eine 200-OK-Antwort generieren, wenn sie die CPID erfolgreich dem Nutzer zuordnet und dauerhaft speichert. Informationen zur erwarteten Antwort im Fehlerfall finden Sie unter Fehlerfälle.
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. Bei Erfolg sollte der Antworttext leer sein.
Jeder Aufruf von GTAF an die DPA erfolgt gemäß den Nutzungsbedingungen des Google-Clients, der den Aufruf ausführt. Je nachdem, welche Anwendungen die DPA unterstützen soll, liegt es am Betreiber, zu entscheiden, ob die DPA diese API implementiert. Wenn sich die DPA für die Implementierung der Consent API entscheidet, MUSS sie den aktuellen Einwilligungsstatus für jeden Nutzer speichern. Hinweise zur Verwendung von CPID
Im Erfolgsfall MUSS die DPA HTTP 200 OK mit einem leeren Antworttext zurückgeben. Informationen zur erwarteten Antwort im Fehlerfall finden Sie unter Fehlerfälle.