동기
개요에서 언급했듯이 DPA는 운영자가 지원하려는 사용 사례에 따라 Google 모바일 데이터 요금제 공유 API와 데이터 요금제 에이전트 API를 조합하여 구현해야 합니다. 이 문서에서는 Google이 사용자의 모바일 데이터 요금제를 식별하고, 요금제와 관련된 정보를 검색하고, 데이터 요금제를 구매하는 데 사용할 Data Plan Agent API를 설명합니다.
인증
GTAF가 전화를 걸려면 먼저 DPA가 GTAF를 인증해야 합니다. 연산자 온보딩 프로세스의 일부로 DPA SSL 인증서의 유효성이 확인됩니다. 현재 상호 인증에 OAuth2를 사용해야 합니다. GTAF가 DPA로 자신을 인증하는 방법에 관한 자세한 내용은 데이터 요금제 에이전트 인증을 참고하세요.
국제화
DPA에 대한 GTAF 요청에는 사람이 읽을 수 있는 문자열 (예: 요금제 설명)이 있어야 하는 언어를 나타내는 Accept-Language 헤더가 있습니다. 또한 DPA 응답 (PlanStatus, PlanOffers)에는 값이 BCP-47 언어 코드인 필수 languageCode 필드가 있습니다 (예: '-미국').
DPA가 사용자가 요청한 언어를 지원하지 않는 경우 기본 언어를 사용하고 languageCode 필드를 사용하여 선택사항을 나타낼 수 있습니다.
API 설명
GTAF는 연산자 DPA를 쿼리할 때 연산자의 구독자를 식별하는 사용자 키를 사용합니다. GTAF가 MSISDN에 액세스할 수 있는 애플리케이션을 대신하여 DPA를 쿼리하는 경우 GTAF는 MSISDN을 사용할 수 있습니다(MAY). 제안되는 Data Plan Agent API는 대략적으로 다음 구성요소로 구성됩니다.
- 사용자 데이터 요금제 상태를 쿼리하는 메커니즘
- DPA에서 사용자를 위한 데이터 요금제 혜택을 쿼리하는 메커니즘
- 사용자의 데이터 요금제를 변경하는 메커니즘 (예: 새 요금제 구매)
- 사용자에게 알림을 전송하는 데 사용할 수 있는 CPID를 공유하는 메커니즘입니다.
- 사용자가 Google 서비스에 가입할지 선택할 수 있는 방법을 공유하는 메커니즘입니다.
이 문서의 나머지 부분에서는 각 API 구성요소를 자세히 설명합니다. 명시적으로 언급되지 않는 한, 모든 통신은 HTTPS를 통해 이루어져야 합니다 (유효한 DPA SSL 인증서 사용). 지원되는 실제 기능에 따라, 연산자는 이러한 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). 오류 발생 시 예상되는 대응은 Error Cases를 참조하세요.
{
"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)가 하나의 앱이 여러 앱 간에 공유되는 경우를 모델링할 수 있음 (예: 게임 및 음악의 경우 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). 오류 발생 시 예상되는 대응은 Error Cases를 참조하세요.
{
"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 요금제만 표시됩니다. GTAF는 혜택을 쿼리하는 애플리케이션이 Google Play 서비스의 일부인 모바일 데이터 요금제 모듈인 경우에만 최대 50개의 요금제만 공유합니다. 이는 Google Play 서비스 사용자에게 우수한 사용자 환경을 제공하기 위한 것입니다.
업셀링 혜택에는 필터 태그가 각 계획에 연결된 태그 배열인 선택적 매개변수가 있습니다. 이러한 모든 filterTag는 필터 내부의 객체인 태그와 일치해야 합니다. Filter는 tuple<tag, displaytext="">가 포함된 첫 번째 수준 객체입니다. Filter는 UI에서 렌더링될 통합 필터 목록입니다. 사용자는 DisplayText를 클릭하여 필터링할 수 있습니다. displayText에
대한 태그는 제품을 필터링하는 데 사용됩니다.<lt;/tag,>
연산자는 사용자에게 확장된 혜택에 대한 구매 요청을 처리할 수 있는 메커니즘이 있어야 합니다(MUST). 사용자에게 비용이 청구되는 메커니즘은 응답에서 formOfPayment 옵션을 사용하여 GTAF와 통신할 수 있습니다.
데이터 구매
구매 요금제 API는 DPAF를 통해 GTAF가 요금제를 구매할 수 있는 방법을 정의합니다. GTAF는 DPA에 데이터 요금제 1개를 구매하는 거래를 시작합니다. 요청 SHALL에는 고유한 트랜잭션 식별자 (transactionId)가 포함되어 요청을 추적하고 중복 트랜잭션 실행을 방지합니다. DPA는 성공/실패 응답으로 응답합니다.
거래 요청
클라이언트에서 요청을 받으면 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 SHALL은 성공적으로 실행된 트랜잭션이나 큐에 추가된 트랜잭션에 대해서만 200-OK 응답을 생성합니다. 오류 발생 시 예상되는 대응은 Error Cases를 참조하세요. 큐에 추가된 트랜잭션의 경우 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는 요금제가 활성화되었다고 가정합니다.
CPID 등록
알림을 지원하는 클라이언트가 CPID 엔드포인트에서 새 CPID를 수신하면 클라이언트 조건이 GTAF에 허용되는 경우 CPID를 GTAF에 등록합니다. 고객이 CPF를 GTAF에 성공적으로 등록했다면 GTAF는 다음 API 호출을 사용하여 CPID를 DPA에 등록합니다.
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를 사용자와 연결한 후 영구적으로 저장하는 경우 DPA는 200-OK 응답을 생성해야 합니다. 오류 발생 시 예상되는 대응은 Error Cases를 참조하세요.
동의
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가 결정합니다. DPA가 동의 API를 구현하기로 선택한 경우 DPA는 각 사용자의 최신 동의 상태를 저장해야 합니다. 동의 상태 정보를 사용하는 방법은 CPID 선택을 참고하세요.
성공하는 경우 DPA는 빈 응답 본문과 함께 HTTP 200 OK를 반환해야 합니다(MUST). 오류 발생 시 예상되는 대응은 Error Cases를 참조하세요.