동기
개요에 언급된 바와 같이, 지원하려는 사용 사례에 따라 DPA는 Google 모바일 데이터 요금제 공유 API와 데이터 요금제 에이전트 API를 조합하여 구현해야 합니다. 이 문서에서는 Google이 사용자의 모바일 데이터 요금제를 식별하고, 이러한 요금제에 관한 정보를 검색하고, 데이터 요금제를 구매하는 데 사용하는 데이터 요금제 에이전트 API를 설명합니다.
인증
GTAF가 호출되기 전에 DPA가 GTAF를 인증해야 합니다. 운영자 온보딩 절차의 일환으로 DPA SSL 인증서의 유효성을 확인합니다. 현재 상호 인증에는 OAuth2를 사용해야 합니다. GTAF가 DPA로 자체 인증하는 방법에 관한 자세한 내용은 데이터 계획 에이전트 인증을 참고하세요.
다국어 지원
DPA에 대한 GTAF 요청에는 사람이 읽을 수 있는 문자열 (예: 요금제 설명)이 표시되어야 하는 언어를 나타내는 Accept-Language 헤더가 포함됩니다. 또한 DPA 응답 (PlanStatus, PlanOffers)에는 값이 BCP-47 언어 코드 (예: 'en-US')입니다.
DPA가 사용자가 요청한 언어를 지원하지 않는 경우 기본 언어를 사용하고 languageCode 필드를 사용하여 선택사항을 나타낼 수 있습니다.
API 설명
GTAF는 운영자의 DPA를 쿼리할 때 운영자의 구독자를 식별하는 사용자 키를 사용합니다. GTAF가 MSISDN에 액세스할 수 있는 애플리케이션을 대신하여 DPA를 쿼리하는 경우 GTAF는 MSISDN을 사용할 수 있습니다(MAY). 대략적으로 제안된 데이터 요금제 에이전트 API는 다음 구성요소로 구성됩니다.
- 사용자 데이터 요금제 상태를 쿼리하는 메커니즘
- 사용자의 데이터 요금제 혜택을 DPA에 쿼리하는 메커니즘
- 사용자의 데이터 요금제를 변경하는 메커니즘 (예: 새 요금제 구매)
- 사용자에게 알림을 전송하는 데 사용할 수 있는 CPID를 공유하는 메커니즘
- 사용자가 서비스에 가입할지 여부에 관한 선택사항을 공유하는 메커니즘
이 문서의 나머지 부분에서는 이러한 각 API 구성요소를 자세히 설명합니다. 명시적으로 언급되지 않는 한 모든 통신은 HTTPS(유효한 DPA SSL 인증서 사용)를 통해 이루어져야 합니다(MUST). 지원되는 실제 기능에 따라 운영자는 이러한 API 구성요소의 전부 또는 일부를 구현할 수 있습니다(MAY).
GTAF-DPA 상호작용
그림 4. 사용자 데이터 요금제 정보를 요청하고 수신하는 호출 흐름
그림 4는 사용자의 데이터 요금제 상태 및 기타 데이터 요금제 정보를 쿼리하는 클라이언트와 관련된 호출 흐름을 보여줍니다. 이 호출 흐름은 UE에서 클라이언트에 의해 트리거된 API 호출에 공유됩니다.
- 클라이언트는 비공개 Google API를 호출하여 데이터 요금제 상태 또는 기타 정보를 요청합니다. 클라이언트는 GTAF에 대한 요청에 사용자 키를 포함합니다.
- GTAF는 사용자 키와 클라이언트 식별자를 사용하여 운영자의 DPA를 쿼리합니다. 지원되는 클라이언트 식별자는 mobiledataplan 및 youtube입니다. DPA는 이러한 클라이언트 식별자 중 하나를 사용하여 전화를 수신할 때 클라이언트가 사용할 수 있는 계획 정보로 응답해야 합니다(MUST).
- GTAF는 요청된 정보를 클라이언트에 반환하고 계획 정보는 DPA에서 지정한 만료 시간까지 GTAF에 의해 캐시됩니다.
그림 4의 1단계와 3단계는 비공개 Google API이므로 더 이상 설명하지 않습니다. 2단계는 아래에 설명된 공개 API입니다. DPA는 GTAF에서 이러한 API 호출을 제공할 때 Cache-Control: no-cache HTTP 헤더를 준수해야 합니다(MUST).
데이터 요금제 상태 쿼리
GTAF는 요금제 상태를 가져오기 위해 다음 HTTP 요청을 실행합니다.
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
GTAF가 DPA에 연락하는 클라이언트는 CLIENT_ID를 사용하여 식별됩니다. Google 클라이언트와 운영자 간의 계약에 따라 DPA는 GTAF에 대한 응답을 맞춤설정할 수 있습니다. 성공한 경우 DPA는 PlanStatus를 나타내는 응답 본문과 함께 HTTP 200 OK를 반환해야 합니다(MUST). 오류 발생 시 예상되는 응답은 오류 사례를 참고하세요.
{
"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는 요금제 반복 날짜(즉, 데이터 잔액이 새로고침/다시 로드되는 시점)여야 합니다(MUST).
각 계획 모듈에는 여러 계획 모듈 트래픽 카테고리가 포함될 수 있습니다(예를 들어 계획 모듈이 여러 앱 간에 공유되는 사례를 모델링하기 위해 PMTCs)). 게임 및 음악의 경우 500MB). 다음 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는 PlanOffer를 나타내는 응답 본문과 함께 HTTP 200 OK를 반환해야 합니다(MUST). 오류 발생 시 예상되는 응답은 오류 사례를 참고하세요.
{
"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 배열의 데이터 요금제 순서에 따라 사용자에게 데이터 요금제가 표시되는 순서가 결정될 수 있습니다(MAY). 또한 UI 또는 기타 제한사항으로 인해 애플리케이션에서 x 요금제만 표시할 수 있고 응답에 y > x 요금제만 포함된 경우 처음 x 요금제만 표시해야 합니다(SHALL). GTAF는 혜택을 쿼리하는 애플리케이션이 Google Play 서비스의 일부인 모바일 데이터 요금제 모듈인 경우 최대 50개의 요금제만 공유합니다. 이는 Google Play 서비스 사용자의 우수한 사용자 환경을 보장하기 위한 것입니다.
업셀 제안에는 각 요금제에 연결된 태그 배열인 filterTags가 선택적 매개변수로 있습니다. 이러한 모든 filterTags는 필터 내 객체인 태그와 일치해야 합니다. Filter는 튜플<tag, displaytext="">를 포함하는 첫 번째 수준 객체입니다. Filter는 UI에 렌더링되는 통합 필터 목록입니다. 사용자가 DisplayText를 클릭하여 필터링할 수 있습니다. displayText에 해당하는 태그는 혜택을 필터링하는 데 사용됩니다.</tag,>
운영자는 사용자에게 제공되는 모든 혜택의 구매 요청을 처리하는 메커니즘이 있어야 합니다(MUST). 사용자에게 구매 비용이 청구되는 메커니즘은 응답의 formOfPayment 옵션을 사용하여 GTAF와 통신할 수 있습니다.
데이터 구매
구매 계획 API는 GTAF가 DPA를 통해 계획을 구매하는 방법을 정의합니다. GTAF는 DPA에서 하나의 데이터 요금제를 구매하는 거래를 시작합니다. 요청에는 요청을 추적하고 중복 거래 실행을 방지하기 위한 고유 거래 식별자(transactionId)가 포함되어야 합니다(SHALL). DPA는 성공/실패 응답으로 응답해야 합니다(MUST).
거래 요청
클라이언트로부터 요청을 수신하면 GTAF는 DPA에 POST 요청을 발행합니다. 요청의 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 응답을 생성해야 합니다(SHALL). 오류 발생 시 예상되는 응답은 오류 사례를 참고하세요. 대기열에 추가된 거래의 경우 DPA는 거래 상태만 입력하고 응답의 다른 필드는 비워 두어야 합니다. 대기열에 추가된 트랜잭션이 처리되면 DPA는 응답과 함께 GTAF를 다시 호출해야 합니다(MUST). 응답 본문은 다음 세부정보가 포함된 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는 계획이 활성화된 것으로 간주해야 합니다(SHALL).
CPID 등록
알림을 지원하는 클라이언트가 CPID 엔드포인트에서 새 CPID를 가져오면 클라이언트 약관에서 GTAF가 이를 허용하는 경우 GTAF에 CPID를 등록합니다. 클라이언트가 GTAF에 CPID를 성공적으로 등록하면 GTAF는 다음 API 호출을 사용하여 DPA에 CPID를 등록합니다.
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를 저장할 수 있습니다(MAY). 등록된 CPID를 사용하여 알림을 보내는 방법에 관한 안내는 CPID 선택을 참고하세요.
DPA는 CPID를 사용자와 연결하고 영구적으로 저장하는 데 성공하면 200 OK 응답을 생성해야 합니다. 오류 발생 시 예상되는 응답은 오류 사례를 참고하세요.
동의
GTAF는 사용자 동의 환경설정을 이동통신사에 전달하기 위해 다음 요청을 발행할 수 있습니다(MAY).
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는 각 사용자의 최신 동의 상태를 저장해야 합니다(MUST). 동의 상태 정보를 사용하는 방법에 관한 안내는 CPID 선택을 참고하세요.
성공한 경우 DPA는 빈 응답 본문과 함께 HTTP 200 OK를 반환해야 합니다(MUST). 오류가 발생한 경우 예상되는 응답은 오류 사례를 참고하세요.