Motivation
Mit der Google Mobile Data Plan Sharing API kann ein Mobilfunkanbieter Informationen zum Datentarif eines Nutzers (identifiziert durch den Nutzerschlüssel) an GTAF senden. Auf dieser Seite wird der Mechanismus beschrieben, über den diese Updates an GTAF und damit an Google-Anwendungen weitergeleitet werden können. Über die API kann der DPA derzeit den Status des Datenvolumens an GTAF senden, damit er von einem Google-Client verwendet werden kann.
Authentifizierung
Alle Anfragen an die Data Plan Sharing API an GTAF müssen mit dem Google Cloud OAuth2-Server authentifiziert werden. Die Anfragen müssen als Dienstkonto authentifiziert werden, das im ISP-Portal für die ASN, die das DPA repräsentiert, auf die Whitelist gesetzt wurde. Google Cloud OAuth 2.0 für Dienstkonten enthält eine Dokumentation zur Verwendung von OAuth mit Google Cloud-Dienstkonten.
Änderungen am Datentarif
Derzeit ermöglicht die Google Mobile Data Plan Sharing API einem Mobilfunkanbieter, Updates zum Datentarif eines Nutzers zu teilen:
- Status des Datentarifs:Erfasst den aktuellen Status des Datentarifs eines Nutzers. Wenn einem Nutzer beispielsweise die Daten ausgehen, kann ein Mobilfunkanbieter ein Update des Datenvolumenstatus an GTAF senden, das dann von GTAF verwendet werden kann, um dem Nutzer eine Benachrichtigung zum Datenvolumenstatus zu senden.
API-Beschreibung
Abbildung 3. GTAF-DPA-Interaktion, wenn DPA den Datenplanstatus mit GTAF teilt.
Anwendungen können Informationen zum Tarifstatus, die mit GTAF geteilt werden, auf zwei Arten empfangen:
- Das UE ruft GTAF für Informationen zum Datentarifstatus auf:
- Der Betreiber verwendet die Data Plan Sharing API, um den Datenvolumenstatus eines Nutzers an GTAF zu senden. GTAF speichert den Planstatus und den zugehörigen Nutzer-Key bis zum Ablaufdatum, das vom Betreiber angegeben wird.
- Eine auf dem UE ausgeführte Google-Anwendung fordert den Status des Datentarifs über eine interne Google-API an. Die Anwendung enthält den Nutzer-Key in ihrer Anfrage.
- Wenn die Anwendung den Status des zwischengespeicherten Datenvolumens verwenden kann, verwendet GTAF den Nutzerschlüssel, um den Status des Datenvolumens des Nutzers zu ermitteln. GTAF gibt diesen Status dann an die Anwendung zurück.
- GTAF überträgt Informationen zum Status des Datentarifs an das UE:
- Der vom Mobilfunkanbieter empfangene Datenvolumenstatus wird direkt an das UE gesendet. Insbesondere wird der übertragene Tarifstatus verwendet, um den On-Device-Cache des Moduls „Tarif für mobile Daten“ in den Google Play-Diensten zu aktualisieren.
Status des Datenfreigabeplans
Die DPA verwendet einen HTTPS-POST, um einen vorhandenen Planeintrag für den Status eines Nutzers zu erstellen und zu aktualisieren, der von einem Client verwendet werden soll. Derzeit unterstützt GTAF mobiledataplan und youtube als gültige Client-IDs. Hier ist ein Beispiel für eine Anfrage für einen Betreiber mit der ASN 12345 und dem Nutzerschlüssel abcdef, der Tarifinformationen für den YouTube-Client mit GTAF teilt:
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus
Der Anfragetext ist eine Instanz von PlanStatus.
{
"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"
}]
}],
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 569
}
}
},
"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"
}
Bei einer erfolgreichen Anfrage gibt GTAF den HTTP-Antwortcode 200 und den übertragenen planStatus-Eintrag mit einem Benachrichtigungseintrag zurück, falls eine Benachrichtigung an den Nutzer gesendet wurde. Wenn GTAF ein Problem mit der Anfrage erkennt, wird ein HTTP-Statuscode im Bereich von 400 bis 499 zurückgegeben. Wenn GTAF eine Anfrage aufgrund eines GTAF-Fehlers nicht abschließen kann, gibt GTAF einen HTTP-Code im Bereich 500–599 zurück. Anfragen, die eine Antwort im Bereich von 500 bis 599 erhalten, gelten als wiederholbar. Anfragen, die eine Antwort im Bereich von 400 bis 499 erhalten, sind in der Regel nicht wiederholbar. Unter Error Cases werden die Fehlerantworten von GTAF ausführlich erläutert.
Planstatus-Push für Standardclient
GTAF unterstützt den folgenden Aufruf, bei dem der Tarifstatus vom Mobilfunkanbieter übertragen wird, ohne den Client anzugeben, für den er verwendet werden kann. In diesem Fall gehen wir davon aus, dass der Planstatus für den mobiledataplan-Client vorgesehen ist und der Mobilfunkanbieter eine Benachrichtigung an den Nutzer senden möchte. Der Anfragetext ist eine Instanz von PlanStatus.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Internationalisierung
Zur Unterstützung der Internationalisierung muss die DPA die bevorzugte Sprache des Nutzers kennen, auch ohne direkte Anfrage von GTAF. Zur Behebung dieses Problems KANN die Anfrage an den CPID-Endpunkt einen Accept-Language-Header enthalten, je nachdem, ob der Client auf die Sprachpräferenzen des Nutzers zugreifen kann. Wenn der Header enthalten ist, müssen lesbare Strings in Updates, die der DPA über die MDP API sendet, die in der CPID-Anfrage angegebenen Einstellungen verwenden.
Die DPA KANN die Spracheinstellungen des Nutzers aktualisieren, wenn sie eine Anfrage von GTAF mit einem Accept-Language-Header erhält, und die aktualisierten Nutzereinstellungen verwenden, um den Sprachcode in zukünftigen Anfragen an GTAF zu bestimmen.
In der Vereinbarung zur Datenverarbeitung MUSS die Sprache für die für Nutzer sichtbaren Strings mit languageCode angegeben werden. GTAF verwendet diese Informationen, um den Titel und den Text von Benachrichtigungen zu erstellen, die dem Nutzer angezeigt werden.