Мотивация
Как упоминалось в обзоре , в зависимости от вариантов использования, которые оператор желает поддерживать, DPA должен реализовать комбинацию API Google Mobile Data Plan Sharing и API Data Plan Agent. В этом документе описывается API Data Plan Agent, который Google будет использовать для идентификации тарифных планов пользователя, получения информации об этих тарифных планах и покупки тарифных планов.
Аутентификация
Прежде чем GTAF сможет совершить вызов, DPA должен аутентифицировать GTAF. В рамках процесса подключения оператора мы проверим действительность SSL-сертификата DPA. В настоящее время для взаимной аутентификации ТРЕБУЕТСЯ использование OAuth2. Подробную информацию об аутентификации GTAF в DPA см. в разделе «Аутентификация агента тарифного плана» .
Интернационализация
Запросы GTAF к DPA включают заголовок Accept-Language, указывающий язык, на котором должны быть представлены удобочитаемые строки (например, описания планов). Кроме того, ответы DPA (PlanStatus, PlanOffers) включают обязательное поле languageCode, значением которого является код языка BCP-47 (например, «en-US») ответа.
Если DPA не поддерживает запрошенный пользователем язык, он может использовать язык по умолчанию и указать свой выбор в поле languageCode.
Описание API
GTAF использует ключ пользователя , который идентифицирует абонента оператора, при запросе к DPA оператора. Когда GTAF запрашивает DPA от имени приложений, имеющих доступ к MSISDN, GTAF МОЖЕТ использовать MSISDN. На высоком уровне предлагаемый API Data Plan Agent включает следующие компоненты:
- Механизм запроса статуса тарифного плана пользователя.
- Механизм запроса у DPA предложений тарифных планов для пользователя.
- Механизм внесения изменений в тарифный план пользователя (например, приобретение нового тарифного плана).
- Механизм обмена CPID, который можно использовать для отправки уведомлений пользователям.
- Механизм предоставления пользователям возможности выбора относительно подписки на нашу услугу.
Далее в документе подробно рассматривается каждый из этих компонентов API. Если явно не указано иное, весь обмен данными ДОЛЖЕН осуществляться по протоколу HTTPS (с действительным SSL-сертификатом DPA). В зависимости от поддерживаемых функций оператор МОЖЕТ реализовать все или часть этих компонентов API.
Взаимодействие GTAF-DPA
Рисунок 4. Поток вызовов для запроса и получения информации о тарифном плане пользователя.
На рисунке 4 показана схема вызова, связанная с запросом клиентом статуса тарифного плана пользователя и другой информации о нём. Эта схема вызова используется для вызовов API, инициированных клиентом на UE.
- Клиент запрашивает статус тарифного плана и/или другую информацию, обращаясь к закрытому API Google. Клиент включает ключ пользователя в запрос к GTAF.
- GTAF использует ключ пользователя и идентификатор клиента для запроса к DPA оператора. Поддерживаются идентификаторы клиентов: mobiledataplan и youtube . При получении вызова с одним из этих идентификаторов клиента DPA ОБЯЗАН предоставить информацию о тарифном плане, которую может использовать клиент.
- GTAF возвращает запрошенную информацию клиенту, а информация о плане кэшируется GTAF до истечения срока действия, указанного DPA.
Шаги 1 и 3 на рисунке 4 представляют собой частные API Google и поэтому далее не описываются. Шаг 2 представляет собой открытый API, описанный далее. DPA ДОЛЖЕН учитывать HTTP-заголовок Cache-Control: no-cache при обслуживании этих вызовов API из GTAF.
Запрос статуса тарифного плана
GTAF отправляет следующий HTTP-запрос для получения статуса плана:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Клиент, от имени которого GTAF обращается к DPA, идентифицируется с помощью CLIENT_ID . В зависимости от соглашения между клиентом Google и оператором, DPA может настроить ответ GTAF. В случае успешного обращения DPA ДОЛЖЕН вернуть HTTP-код 200 OK с телом ответа, представляющим 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"
}]
}],
"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
}
}
}
}
Для постоплатных планов expirationTime ДОЛЖЕН быть датой повторения плана (т. е. датой обновления/пополнения баланса данных).
Каждый модуль плана может содержать несколько категорий трафика модуля плана ( PMTCs) что позволяет моделировать ситуацию, когда модуль плана используется несколькими приложениями (например, 500 МБ для игр и музыки). Предопределены следующие категории PMTC: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Ожидается, что операторы свяжутся с отдельными командами Google для согласования набора категорий трафика и их семантики, релевантных для различных приложений Google.
Запрос предложений плана
GTAF отправляет следующий HTTP-запрос для получения предложений тарифных планов от оператора:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Клиент, от имени которого GTAF обращается к DPA, идентифицируется с помощью CLIENT_ID . В зависимости от соглашения между клиентом Google и оператором, DPA может настроить ответ GTAF. Необязательный параметр context указывает контекст приложения, в котором выполнен запрос. Обычно это строка, которую приложение передаёт оператору через GTAF.
В случае успеха DPA ДОЛЖЕН вернуть HTTP-код 200 OK с телом ответа, представляющим собой 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",
"filterTags": ["repurchase", "all"]
}
],
"filters" : [
{
"tag": "repurchase",
"displayText": "REPURCHASE PLANS"
},
{
"tag": "all",
"displayText": "ALL PLANS"
}
]
"expireTime": "2019-03-04T00:06:07Z" // req.
}
Порядок тарифных планов в массиве offers МОЖЕТ определять порядок их отображения пользователям. Кроме того, если приложение может отображать только x тарифных планов из-за ограничений пользовательского интерфейса или других ограничений, а ответ содержит y > x тарифных планов, то ДОЛЖНЫ быть отображены только первые x тарифных планов. GTAF предоставляет доступ только к 50 тарифным планам, если приложение, запрашивающее предложения, является модулем тарифного плана мобильной связи, входящим в состав Сервисов Google Play. Это необходимо для обеспечения комфортного использования Сервисов Google Play.
Предложения допродажи имеют необязательный параметр filterTags, представляющий собой массив тегов, привязанных к каждому плану. Все эти filterTags должны соответствовать тегу, который является объектом внутри Filter. Filter — это объект первого уровня, содержащий кортеж.Filter — это объединенный список фильтров, отображаемых в пользовательском интерфейсе. Пользователь может фильтровать, нажимая на DisplayText. Тег, соответствующий displayText, используется для фильтрации предложений.
Обратите внимание, что оператор ДОЛЖЕН иметь механизм для выполнения запроса на покупку по любому предложению, предоставленному пользователю. Механизм, посредством которого с пользователя будет взиматься плата за покупку, можно сообщить GTAF с помощью параметра formOfPayment в ответе.
Покупка данных
API плана покупки определяет, как GTAF может приобретать тарифные планы через DPA. GTAF инициирует транзакцию для покупки одного тарифного плана в DPA. Запрос ДОЛЖЕН включать уникальный идентификатор транзакции (transactionId) для отслеживания запросов и предотвращения дублирования транзакций. DPA ДОЛЖЕН ответить об успешном/неуспешном выполнении.
Запрос транзакции
Получив запрос от клиента, GTAF отправляет POST-запрос к DPA. URL-адрес запроса:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
где userKey — это либо CPID , либо MSISDN . Тело запроса представляет собой экземпляр TransactionRequest , включающий следующие поля:
{
"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.
}
Ответ на транзакцию
DPA ДОЛЖЕН генерировать ответ 200-OK только для успешно выполненной транзакции или транзакции, поставленной в очередь. Ожидаемый ответ в случае ошибок см. в разделе «Случаи ошибок». В случае транзакции, поставленной в очередь, DPA должен заполнить только статус транзакции, оставив остальные поля в ответе пустыми. DPA ДОЛЖЕН отправить ответ в GTAF после обработки транзакции, поставленной в очередь. Тело ответа представляет собой экземпляр TransactionResponse , содержащий следующую информацию:
{
"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.
}
}
Если planActivationTime отсутствует, GTAF ДОЛЖЕН предположить, что план активирован.
Зарегистрировать CPID
Когда клиент, поддерживающий уведомления, получает новый CPID от конечной точки CPID, он регистрирует его в GTAF, если условия использования клиента разрешают GTAF это сделать. Если клиент успешно регистрирует CPID в GTAF, GTAF регистрирует CPID в DPA, используя следующий вызов API:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
где userKey — это CPID, а единственный поддерживаемый CLIENT_ID — mobiledataplan . Тело запроса представляет собой экземпляр RegisterCpidRequest и содержит время, после которого CPID нельзя использовать для отправки уведомлений, и выглядит следующим образом:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Этот API актуален только для операторов, желающих поддерживать модуль «Мобильный тарифный план» в сервисах Google Play. Для надёжной отправки уведомлений пользователю DPA МОЖЕТ хранить последний зарегистрированный CPID для каждого пользователя. Инструкции по использованию зарегистрированного CPID для отправки уведомлений см. в разделе «Выбор CPID» .
DPA сгенерирует ответ 200-OK, если DPA успешно свяжет CPID с пользователем и сохранит его. Ожидаемый ответ в случае возникновения ошибок см. в разделе « Случаи ошибок».
Согласие
GTAF МОЖЕТ отправить следующий запрос на передачу предпочтения согласия пользователя оператору.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
где userKey — это либо CPID , либо MSISDN . Тело запроса представляет собой экземпляр SetConsentStatusRequest . В случае успеха тело ответа должно быть пустым.
Каждый вызов из GTAF в DPA выполняется в соответствии с условиями обслуживания клиента Google, выполняющего вызов. В зависимости от приложений, которые DPA планирует поддерживать, оператор решает, реализует ли DPA этот API. Если DPA решит реализовать API согласия, DPA ОБЯЗАН хранить последний статус согласия для каждого пользователя. Инструкции по использованию информации о статусе согласия см. в разделе «Выбор CPID» .
В случае успеха DPA ДОЛЖЕН вернуть HTTP 200 OK с пустым телом ответа. См. раздел «Случаи ошибок» для получения информации об ожидаемом ответе в случае возникновения ошибок.