Ziel
Wie in der Übersicht erwähnt, muss der DPA 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, mit der Google die mobilen Datentarife des Nutzers identifiziert, Informationen zu diesen Plänen abruft und Datenpläne kauft.
Authentifizierung
Bevor GTAF anrufen kann, muss die DPA GTAF authentifizieren. Im Rahmen der Einrichtung des Operators 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 Datenplan-Agent-Authentifizierung.
Internationalization
GTAF-Anfragen an den DPA enthalten einen "Accept-Language"-Header, der die Sprache angibt, in der die für Menschen lesbaren Strings (z.B. Planbeschreibungen) enthalten sein sollen. Außerdem enthalten DPA-Antworten (PlanStatus, PlanOffers) ein Pflichtfeld für languageCode, dessen Wert der BCP-47-Sprachcode ist (z.B. &ens-US der Antwort.
Wenn der Datenschutzbeauftragte die vom Nutzer angeforderte Sprache nicht unterstützt, kann er eine Standardsprache und das Feld „languageCode“ verwenden, um seine Auswahl anzugeben.
API-Beschreibung
GTAF verwendet einen Nutzerschlüssel, mit dem ein Abonnent für den Operator des DPAs des Operators identifiziert wird. Wenn GTAF den DPA im Namen von Anwendungen abfragt, die Zugriff auf MSISDN haben, kann GTAF MSISDN verwenden. Grundsätzlich umfasst die vorgeschlagene Data Plan Agent API die folgenden Komponenten:
- Mechanismus zum Abfragen des Status von Nutzerdatentarifen.
- Mechanismus zum Abfragen der Datentarif-Angebote des Nutzers in der DPA.
- Mechanismus zum Ändern des Datentarifs des Nutzers (z. B. Erwerb eines neuen Tarifs)
- Mechanismus zum Teilen der CPIDs, der zum Senden von Benachrichtigungen an Nutzer verwendet werden kann.
- Ein Mechanismus, über den die Nutzer entscheiden können, ob sie sich für unseren Dienst registrieren.
Der Rest dieses Dokuments wird jede dieser API-Komponenten ausführlich erläutern. Sofern nicht anders angegeben, MUSS die gesamte Kommunikation über HTTPS erfolgen (mit einem gültigen DPA-SSL-Zertifikat). Je nach den tatsächlich unterstützten Funktionen kann ein Operator alle oder einen Teil dieser API-Komponenten implementieren.
GTAF-DPA-Interaktion
Abbildung 4. Anrufablauf zum Anfordern und Empfangen von Informationen zum Nutzerdatentarif.
Abbildung 4 veranschaulicht den Aufrufverlauf, der mit einem Client verknüpft ist, der den Datentarifstatus des Nutzers und andere Datentarifinformationen abfragt. Dieser Aufrufablauf wird für API-Aufrufe freigegeben, die vom Client in der UE ausgelöst werden.
- Der Client fordert über eine private Google API den Status des Datentarifs und/oder andere Informationen an. Der Client schließt den Nutzerschlüssel in die Anfrage an GTAF ein.
- GTAF verwendet den Nutzerschlüssel und eine Client-ID, um den DPA des Operators abzufragen. Die unterstützten Client-IDs sind mobiledataplan und youtube. Wenn die DPA einen Aufruf mit einer dieser Clientkennungen erhält, MUSS sie mit Tarifinformationen antworten, die vom Client verwendet werden können.
- GTAF gibt die angeforderten Informationen an den Client zurück und die Tarifinformationen werden von GTAF bis zu dem vom DPA angegebenen Ablauf im Cache gespeichert.
Die Schritte 1 und 3 in Abbildung 4 sind private Google APIs und werden daher nicht weiter beschrieben. Schritt 2 ist eine nachfolgend beschriebene öffentliche API. Der DPA MUSS den Cache-Control: no-cache-HTTP-Header berücksichtigen, wenn er diese API-Aufrufe von GTAF bereitstellt.
Status des Datentarifs abfragen
Der GTAF sendet die folgende HTTP-Anfrage, um den Tarifstatus zu erhalten:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Der Client, in dessen Namen der GTAF die DPA kontaktiert, wird mithilfe von CLIENT_ID identifiziert. Abhängig von der Vereinbarung zwischen dem Google-Client und dem Betreiber kann die Datenschutzaufsichtsbehörde die Antwort an GTAF anpassen. Im Erfolgsfall muss der DPA HTTP 200 OK mit einem Antworttext zurückgeben, der PlanStatus darstellt. Informationen zur erwarteten Antwort auf Fehler finden Sie unter Fehlerfälle.
{
"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 Wiederholungsdatum des Plans sein, d.h. wenn das Datenguthaben aktualisiert/neu geladen wird.
Jedes Planmodul kann mehrere Traffic-Kategorie-Module (Plan Module) enthalten (PMTCs), um den Fall zu modellieren, in dem ein Planmodul von mehreren Anwendungen 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 einzelne Google-Teams kontaktieren, um sich auf die Gruppe von Traffic-Kategorien und ihre Semantik zu einigen, die für verschiedene Google-Anwendungen relevant sind.
Angebote für Tarife abfragen
Die GTAF sendet die folgende HTTP-Anfrage, um Tarifangebote vom Operator abzurufen:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Der Client, in dessen Namen der GTAF die DPA kontaktiert, wird mithilfe von CLIENT_ID identifiziert. Abhängig von der Vereinbarung zwischen dem Google-Client und dem Betreiber kann die Datenschutzaufsichtsbehörde die Antwort an GTAF anpassen. Der optionale Kontextparameter gibt den Anwendungskontext für die Anfrage an. In der Regel ist dies ein String, den die Anwendung über GTAF an den Operator weitergibt.
Im Erfolgsfall muss der DPA HTTP 200 OK mit einem Antworttext zurückgeben, der ein PlanOffer darstellt. Informationen zur erwarteten Antwort auf Fehler 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 Datentarife im Array offers KANN die Reihenfolge bestimmen, in der Datentarife den Nutzern angezeigt werden. Wenn die Anwendung aufgrund der UI oder aufgrund von anderen Einschränkungen nur x Pläne anzeigen kann und die Antwort y > x-Pläne enthält, WERDEN nur die ersten x Pläne angezeigt. GTAF teilt nur bis zu 50 Pläne, wenn die Anwendung, die Angebote abfragt, ein Mobile Data Plan-Modul ist, das Teil der Google Play-Dienste ist. Damit soll eine gute Nutzererfahrung für die Nutzer der Google Play-Dienste gewährleistet werden.
Die Upsell-Angebote haben „filterTags“ als optionalen Parameter, d. h. ein Array von Tags, die mit jedem Plan verknüpft sind. Alle „filterTags“ müssen mit einem Tag übereinstimmen, das ein Objekt in „Filter“ ist. Filter ist ein Objekt der ersten Ebene, das Semikolon<tag, displaytext=""> enthält. Filter ist eine konsolidierte Liste von Filtern, die auf der UI gerendert werden. Der Nutzer kann nach dem Text filtern. Das Tag, das dem displayText entspricht, wird zum Filtern der Angebote verwendet.</tag,>
Der Operator MUSS einen Mechanismus haben, um eine Kaufanfrage für ein dem Nutzer erweitertes Angebot auszuführen. Der Mechanismus, über den dem Nutzer ein Kauf in Rechnung gestellt wird, kann über die Option formOfPayment in der Antwort mit GTAF kommuniziert werden.
Datenkauf
Mit der Purchase Plan API wird festgelegt, wie GTAF Pläne über die Datenverarbeitungsplattform erwerben kann. GTAF initiiert die Transaktion, um einen Datentarif an die DPA zu kaufen. Die Anfrage MUSS eine eindeutige Transaktions-ID (transactionId) enthalten, um Anfragen zu verfolgen und eine doppelte Transaktionsausführung zu vermeiden. Der DPA MUSS mit einer Erfolgs-/Fehlerantwort antworten.
Transaktionsanfrage
Sobald er eine Anfrage von einem Client erhält, sendet GTAF eine POST-Anfrage an den DPA. Die URL der Anfrage lautet:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Dabei ist userKey entweder CPID oder MSISDN. Der Text der Anfrage ist eine Instanz von TransactionRequest mit den folgenden Feldern:
{
"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 SHALL generiert eine Antwort mit 200 OK nur für eine erfolgreich ausgeführte Transaktion oder eine Transaktion in der Warteschlange. Informationen zur erwarteten Antwort auf Fehler finden Sie unter Fehlerfälle. Bei einer Warteschlange in der Warteschlange 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 Transaktion in der Warteschlange verarbeitet wurde. Der Antworttext ist eine Instanz von TransactionResponse mit folgenden Details:
{
"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 das planActivationTime fehlt, geht GTAF SHALL davon aus, dass der Plan aktiviert wurde.
CPID registrieren
Wenn ein Client, der Benachrichtigungen unterstützt, eine neue CPID vom CPID-Endpunkt erhält, registriert er die CPID bei GTAF, wenn die Client-Bedingungen GTAF dies erlauben. Wenn der Client die CPID erfolgreich bei GTAF registriert, registriert GTAF die CPID mit dem folgenden API-Aufruf bei der DPA:
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. Sie enthält die Zeit, nach der die CPID nicht zum Senden von Benachrichtigungen verwendet werden kann, und sieht so aus:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Diese API ist nur für Betreiber relevant, die das Mobile Data Plan-Modul in den Google Play-Diensten unterstützen möchten. Damit die Benachrichtigungen zuverlässig an den Nutzer gesendet werden können, DJ kann die zuletzt registrierte CPID für jeden Nutzer gespeichert werden. Informationen zum Verwenden der registrierten CPID zum Senden von Benachrichtigungen finden Sie unter CPID auswählen.
Die Datenschutzaufsichtsbehörde generiert eine Antwort vom Typ 200 OK, wenn die Datenverarbeitungsstelle die CPID erfolgreich mit dem Nutzer verknüpft und sie dauerhaft speichert. Informationen zur erwarteten Antwort auf Fehler finden Sie unter Fehlerfälle.
Einwilligung
Der GTAF kann die folgende Anfrage senden, um die Einstellung für die Nutzereinwilligung an den Mobilfunkanbieter zu übergeben.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Dabei ist userKey entweder CPID oder MSISDN. Der Anfragetext ist eine Instanz von SetConsentStatusRequest. Wenn der Vorgang erfolgreich war, sollte der Antworttext leer sein.
Jeder Aufruf von GTAF an die DPA folgt den Nutzungsbedingungen des Google-Clients, der den Aufruf durchführt. Abhängig davon, welche Anwendungen der DPA unterstützt, muss der Betreiber entscheiden, ob der DPA diese API implementiert. Wenn die DPA die Einwilligungs-API implementiert, MUSS der aktuelle Einwilligungsstatus für jeden Nutzer gespeichert werden. Informationen zum Verwenden der Informationen zum Einwilligungsstatus finden Sie unter CPID auswählen.
Im Erfolgsfall muss der DPA HTTP 200 OK mit einem leeren Antworttext zurückgeben. Informationen zur erwarteten Antwort auf Fehler finden Sie unter Fehlerfälle.