Integrate with the KWS API

제품에 대한 부모 인증 플로를 트리거하기 위해 KWS API를 호출하는 방법을 살펴봅니다.

4 분 소요

PV 서비스 플로를 트리거하려면 send-parent-email API 엔드포인트를 호출해야 합니다.

API 통합 세부사항 구하기

키즈 웹 서비스(Kids Web Service, KWS) API를 호출하려면 액세스와 인증을 활성화하기 위한 특정 데이터 항목이 필요합니다.

통합 정보(Integration information) 탭에서 다음과 같은 세부사항을 복사합니다.

  • 제품 ID(Product ID) - 제품의 KWS ID입니다.
  • 제품 클라이언트 ID(Product client ID) - 인증에 사용됩니다.
  • 제품 API 키(Product API key) - 클라이언트 비밀 키입니다. 개발자 액세스 토큰을 구하는 데 사용됩니다.
통합 세부사항

이미지를 클릭하면 전체 크기로 볼 수 있습니다.

부모 인증(Parent Verification) 탭에서 다음과 같은 세부사항을 복사합니다.

  • 웹후크 비밀 코드(Webhook secret code) - 키즈 웹 서비스에서 전송된 실제 호출인지 확인하기 위해 페이로드에 서명하는 데 사용됩니다.
  • 서비스 API 호스트 URL(Service API host URL) - 부모 인증(Parent Verification, PV) 서비스가 위치한 URL입니다. API 쿼리는 이 URL에 대해 생성되어야 합니다.
PV 세부사항

이미지를 클릭하면 전체 크기로 볼 수 있습니다.

참고: 각 제품은 테스트 및 프로덕션 크리덴셜을 모두 가지고 있습니다. 올바른 세트를 사용하고 있는지 확인하세요.

사용자 세부사항 수집

다음과 같은 세부사항을 수집하려면 제품의 인터페이스를 환경설정해야 합니다.

  • 부모의 이메일 주소
  • 아동의 위치. 다음 포맷 중 하나를 사용할 수 있습니다.
  • ISO 3166-1 alpha-2 코드. 예시: 'US', 'GB', 'CA'
  • 확인된 ISO 3166-2 서브디비전. 예시: 'US-CA', 'GB-ENG', 'CA-BC'
  • 부모의 언어. KWS에서 부모에게 제공하는 이메일 및 인증 화면에 사용할 언어입니다. 예시: ‘en’, ‘de’, ‘ja’. 지원되는 전체 언어 목록은 PV 서비스 현지화 페이지를 참고하세요.

send-parent-email 엔드포인트 호출

제품이 send-parent-email 엔드포인트로의 인증된 API 호출을 통해 수집된 부모의 이메일 주소, 아동의 위치 및 부모의 언어를 KWS에 전송하도록 환경설정합니다.

속도 제한

속도 제한(rate limit)은 고유한 부모 이메일 주소마다 시간당 요청 10회로 고정되어 있습니다.

사용자 에이전트 요청 헤더

KWS API에 대한 모든 요청은 클라이언트 및/또는 HTTP 라이브러리를 식별하는 공백이 아닌 스트링을 포함하는 사용자 에이전트 헤더가 포함되어야 합니다. 그렇지 않으면 ‘Request blocked’ 403 응답이 발생합니다.

개발자 액세스 토큰을 통한 인증

API 호출은 '개발자 액세스 토큰'이라고 하는 베어러 토큰(Bearer token)을 통해 인증되어야 합니다.

개발자 액세스 토큰은 통합 정보(Integration information)에서 찾을 수 있는 클라이언트 ID제품 API 키 (클라이언트 비밀 키)를 사용하여 토큰 엔드포인트의 client_credentials OAuth 승인을 통해 KWS 인증 서비스에서 얻을 수 있습니다.

참고: 이러한 크리덴셜 및 토큰은 기밀 정보로 유지되어야 하며 클라이언트 애플리케이션에 전달되어서는 안 됩니다.

토큰을 얻으려면 다음과 같은 코드를 사용합니다.

POST https://auth.kws.superawesome.com/auth/realms/kws/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: basic <base64 of client-id:client-secret>
Request:
grant_type=client_credentials&scope=verification
Response (OAuth2 Token Response):
{
"access_token": "..."
"refresh_token": "..."
}

참고: 개발자 액세스 토큰은 만료 기간이 짧습니다. OAuth 토큰 요청에 대한 응답 시 토큰의 유효 기간을 알려 줍니다(유효 기간은 변경될 수 있음). OAuth2 사양에 따라 '토큰 새로고침'을 구현해야 합니다.

API 호출 재시도 행동

KWS API와 통합되는 모든 시스템은 API 호출을 위한 재시도 메커니즘을 구현해야 합니다. 재시도 메커니즘이 구현된 경우, 익스포넨셜 백오프(exponential backoff)를 수행하고 API 호출에서 전송된 속도 제한 헤더를 따라야 합니다.

KWS 플로

KWS API를 호출한 후 KWS는 다음과 같은 전체 인증 플로를 관리합니다.

  1. KWS에서 제공된 주소로 이메일을 보내 부모의 신원을 확인합니다.
  2. 부모는 이메일 내 링크를 클릭하여 인증 플로를 시작합니다.
  3. KWS에서 부모가 인증 크리덴셜을 입력할 수 있는 웹 기반 인터페이스를 제공합니다. 아동의 위치 및 부모에게 제공할 인증 방식에 따라 각종 인증 방식을 사용할 수 있습니다.
  4. 인증 성공 시:
Body
{
"name": "parent-verified",
"time": "ISO8601 timestamp",
"orgId": "uuid",
"productId": "uuid",
"environmentId": "uuid",
"payload": {
"parentEmail": "...",
"externalPayload": "...",
"status: {
"verified": true,
"transactionId": "..."
}
}
}
  • 부모의 이메일 주소 해시가 KWS ParentGraph에 저장됩니다. 이를 통해 KWS는 다음 번 PV 서비스에서 부모가 사전 인증되었는지 여부를 확인할 수 있습니다.

사전 인증된 부모는 인증 크리덴셜을 제공하지 않아도 됩니다. ‘사전 인증’되었다는 것은 부모의 해시된 이메일 주소가 ParentGraph에 포함되어 있으며, 해당 부모가 현재 액세스 중인 제품에 적용된 또는 인증 시 적용되었던 인증 방식을 사용하여 이전에 KWS PV 서비스에 의해 인증되었다는 것을 의미합니다.

  • KWS에서 부모에게 성공적으로 인증되었으며 ParentGraph에 추가되었음을 알리는 확인 이메일을 전송합니다. 이메일에 ParentGraph를 비활성화하는 링크가 포함되기도 합니다. 결제 기반 인증 방식의 경우, 아동의 국가에서 요구하는 사항에 따라 이메일에는 인증, 캡처, 환불에 대한 세부사항이 포합됩니다.
  • 개발자 포털에서 URL 리디렉션 을 제공한 경우 KWS에서 부모를 해당 URL로 리디렉션합니다. 그렇지 않은 경우 KWS는 PV 서비스 웹 페이지에 인증 성공 메시지를 표시합니다.

PV 서비스 사용 사례 페이지에서 KWS가 부모에게 제공하는 이메일 및 웹뷰 예시를 살펴보세요.

다음 단계

PV 서비스에 커스텀 브랜딩을 적용합니다.