Установление CPID

GTAF использует ключ пользователя для идентификации абонента при взаимодействии с DPA. Приложения, имеющие доступ к MSISDN пользователя, могут использовать его в качестве user_key. С другой стороны, приложениям, не имеющим доступа к MSISDN, необходимо установить идентификатор тарифного плана (CPID) без необходимости определения MSISDN пользователя. Далее мы опишем механизм установки CPID.

Поток вызовов CPID

Рисунок 2: Поток вызовов для установления CPID.

  1. Приложение Google в UE использует внутренний API Google для получения URL конечной точки CPID из GTAF. Оператор идентифицируется по публичному IP-адресу клиента и коду MCC+MNC активной SIM-карты. В случае MVNO Google использует SPN и GID1 для определения MVNO.
  2. Клиент отправляет HTTP-запрос GET к конечной точке CPID. Оператор МОЖЕТ поддерживать отправку запроса по HTTPS.
  3. Оператор МОЖЕТ использовать функцию глубокой проверки пакетов для идентификации запроса и добавления номера телефона пользователя в запрос в качестве HTTP-заголовка.
  4. Конечная точка CPID получает запрос, создает CPID и возвращает CPID в UE со временем жизни (TTL), указывающим, как долго UE может использовать этот CPID.

Оператор МОЖЕТ также использовать IP-адреса вместо доменных имён в URL конечной точки CPID, если это предпочтительнее. IP-адреса МОГУТ находиться в частном адресном пространстве, но они должны быть доступны клиентам Google в сети оператора.

Оператор ОБЯЗАН предоставить Google следующую информацию в рамках процесса регистрации:

  1. URL-адрес CPID_URL, к которому будут обращаться приложения для получения идентификаторов CPID. Один URL-адрес CPID_URL обязателен, но оператор может предоставить несколько URL-адресов для повышения доступности.
  2. Список IP-префиксов, принадлежащих оператору, а также мобильный код страны (MCC) и код(ы) мобильной сети (MNC), которые оператор хочет сопоставить с предоставленными URL-адресами CPID_URL. Если оператор использует SPN или GID1 для различения MVNO в своей сети, он ОБЯЗАН также предоставить эту информацию. Google будет использовать эту информацию для сопоставления клиентов с соответствующими конечными точками CPID, как показано на шаге 1 рисунка 2.

Формат запроса: GET CPID_URL По причинам устаревшего характера конечная точка CPID должна поддерживать следующий запрос:

GET CPID_URL?app={app_id}

Конечная точка CPID может игнорировать параметр URL {app_id} при генерации CPID. Однако она ДОЛЖНА иметь возможность обрабатывать запросы, содержащие этот параметр.

Запрос к конечной точке CPID МОЖЕТ включать заголовок Accept-Language . Если заголовок включен, то в удобочитаемых строках обновлений, отправляемых DPA с помощью API Mobile Data Plan Sharing, ДОЛЖНЫ использоваться настройки, указанные в запросе CPID.

Каждый раз, когда клиент отправляет запрос GET CPID_URL, он ДОЛЖЕН получать новый CPID. Если создание CPID прошло успешно, конечная точка CPID ДОЛЖНА вернуть ответ 200 OK. Тело ответа ДОЛЖНО содержать экземпляр CPIDResponse .

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

Возвращаемый CPID ДОЛЖЕН быть действителен в течение ttlSeconds секунд, даже если абонент впоследствии запросил другие CPID. Google рекомендует использовать значение TTL 30 дней, но не менее 14 дней для обеспечения наилучшего пользовательского опыта. GTAF будет кодировать CPID согласно RFC2396 в последующих вызовах DPA.

Генерация CPID

РЕКОМЕНДУЕМЫЙ способ создания CPID для конечной точки CPID:

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

Конечная точка CPID объединяет MSISDN, язык, отправленный клиентом в заголовке Accept-Language, и временную метку высокого разрешения и шифрует их с помощью AES с использованием secret ключа. Временная метка ДОЛЖНА соответствовать времени истечения срока действия CPID. Зашифрованный вывод кодируется в формате Base64. Кроме того, при использовании CPID в URL-адресе он ДОЛЖЕН быть закодирован в формате URL для обработки специальных символов (/+=), используемых в формате Base64. В частности, когда GTAF вызывает DPA или когда DPA вызывает API совместного использования мобильных данных, CPID ДОЛЖЕН быть закодирован в формате URL.

В зависимости от ситуации конкретного оператора, внедрение конечной точки CPID может оказаться непростой задачей. Одной из часто встречающихся проблем является получение доступа к MSISDN на конечной точке CPID. Мы рады поделиться опытом, полученным в ходе адаптации новых операторов. Пожалуйста, свяжитесь с нами, если у вас возникнут какие-либо трудности.

Хранилище CPID

Идентификатор CPID, сгенерированный с помощью описанного выше механизма, не обязательно хранить в базе данных. Необходимую информацию для обработки вызовов в DPA можно получить из идентификатора CPID.

  1. Когда DPA получает вызов от GTAF относительно статуса плана или предложений, MSISDN можно получить путем расшифровки CPID и извлечения MSISDN.
  2. Срок действия CPID можно определить, расшифровав CPID и извлекя из него временную метку срока действия.

Требования к доступности и емкости

Если клиенты не могут получить CPID, они не могут получить доступ к информации через API мобильного тарифного плана. По этой причине оператор ДОЛЖЕН принять необходимые меры для обеспечения доступности конечной точки CPID. Такие меры включают в себя наличие нескольких экземпляров конечной точки CPID и функций DPI, а также физическое, локальное и сетевое резервирование для обеих функций, а также обеспечение достаточности системных ресурсов и пропускной способности. Более того, конечная точка CPID, а также функция DPI, внедряющая заголовок, должны иметь достаточную пропускную способность для обработки нагрузки от всех клиентов Google, запрашивающих CPID. Конечная точка CPID может использовать большие значения в поле ttlSeconds для снижения частоты генерации CPID.

Случаи ошибок

В случае возникновения ошибки конечная точка CPID ДОЛЖНА вернуть HTTP-ошибку с телом ответа, которое ДОЛЖНО содержать экземпляр ErrorResponse . Хорошее сообщение об ошибке должно содержать информацию, которая может помочь в отладке причины ошибки. Например, в случае истёкшего срока действия CPID, информация о времени генерации и истечения срока действия CPID поможет нам убедиться, что конечная точка CPID работает должным образом.

{
    "errorMessage": "<error message>",
    "cause": "USER_ROAMING"
}

Конечная точка CPID ДОЛЖНА возвращать следующее в зависимости от сценария:

  1. Если запрос CPID получен для пользователя, который не принадлежит сети оператора (например, пользователь, принадлежащий другому оператору, но находящийся в роуминге в сети, обслуживаемой этой конечной точкой CPID) или который не выбрал обмен информацией о тарифном плане с Google, конечная точка CPID ДОЛЖНА вернуть код состояния HTTP 403 с указанием причины USER_ROAMING, USER_OPT_OUT или INELIGIBLE_FOR_SERVICE.
  2. Если запрос CPID получен с недействительным номером телефона, то конечная точка CPID ДОЛЖНА вернуть HTTP 400 с причиной ошибки INVALID_NUMBER.
  3. Если запрос к конечной точке CPID каким-либо образом искажен, конечная точка CPID ДОЛЖНА вернуть HTTP 400 с причиной ERROR_CAUSE_UNSPECIFIED.
  4. Для других причин ошибок приемлем любой совместимый код ошибки HTTP. В частности, HTTP 500 — подходящая причина ошибки для любого внутреннего сбоя на конечной точке CPID.