API агента плана данных, API агента плана данных

Мотивация

Как упоминалось в обзоре , в зависимости от вариантов использования, которые оператор хочет поддерживать, DPA должен реализовать комбинацию API совместного использования планов мобильных данных Google и API агента плана данных. В этом документе описывается 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 агента плана данных включает следующие компоненты:

1. Механизм запроса статуса пользовательского тарифного плана.
2. Механизм запроса к DPA предложений тарифного плана для пользователя.
3. Механизм внесения изменений в тарифный план пользователя (например, покупка нового плана).
4. Механизм обмена CPID, которые можно использовать для отправки уведомлений пользователям.
5. Механизм обмена пользователями вариантами подписки на наш сервис.

Остальная часть этого документа подробно описывает каждый из этих компонентов API. Если явно не указано иное, все коммуникации ДОЛЖНЫ осуществляться по протоколу HTTPS (с действительным сертификатом SSL DPA). В зависимости от фактических поддерживаемых функций оператор МОЖЕТ реализовать все или часть этих компонентов API.

Взаимодействие GTAF-DPA

Рис. 4. Поток вызовов для запроса и получения информации о тарифном плане пользователя.

На рис. 4 показан поток вызовов, связанный с запросом клиента о статусе плана данных пользователя и другой информации о плане данных. Этот поток вызовов используется совместно для вызовов API, инициированных клиентом в UE.

1. Клиент запрашивает статус тарифного плана и/или другую информацию, вызывая частный API Google. Клиент включает ключ пользователя в запрос к GTAF.
2. GTAF использует ключ пользователя и идентификатор клиента для запроса DPA оператора. Поддерживаемые идентификаторы клиентов: mobiledataplan и youtube . Когда DPA получает вызов с одним из этих идентификаторов клиента, он ДОЛЖЕН ответить информацией о плане, которую может использовать клиент.
3. 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. Необязательный параметр контекста предоставляет контекст приложения, в котором сделан запрос. Обычно это строка, которую приложение передает оператору через 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 планов, если приложение, запрашивающее предложения, является модулем Mobile Data Plan, который является частью сервисов 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, он регистрирует 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 актуален только для операторов, желающих поддерживать модуль Mobile Data Plan в сервисах 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 с пустым телом ответа. Пожалуйста, смотрите Случаи ошибок для ожидаемого ответа в случае ошибок.