Google 연동 요청 — BizSpring Google OAuth 연동 API
핵심 요약
- 고객사 플랫폼과 Google 간 OAuth 연동 절차를 4단계로 설명하는 API 문서입니다.
- 먼저 자사 API(/media/oauth2/{MEDIA_CODE})를 GET 호출해 Google 인증 URL을 발급받습니다.
- 발급받은 인증 URL을 팝업 창으로 열어 클라이언트가 로그인·권한 승인을 직접 진행합니다.
- 인증 완료 후 팝업이 postMessage로 부모창에 연동 결과(status, code)를 전달하고 닫힙니다.
- 부모창은 수신한 메시지를 바탕으로 연동 상태를 확인하고 UI 업데이트 등 후속 작업을 수행합니다.
# Google 연동 요청
연동고객사 플랫폼과 Google 간의 연동 절차에 대해 설명합니다. 이 과정은 연동 시작을 위한 자사 URL 호출부터 연동 완료 후 UI 업데이트까지 단계별로 진행됩니다.
Google 연동 프로세스
Google 연동은 다음과 같은 단계로 진행됩니다.
1. 자사 URL 호출
연동을 시작하기 위한 첫 단계로, Google의 인증을 위해 필요한 인증 URL 을 반환받기 위해 자사 API URL을 호출합니다.
> MEDIA\_CODE
>
> * GOOGLE : 구글
요청URL
**https://growthplatform.ai/media/oauth2/{MEDIA_CODE}
**
프로토콜
HTTPS
HTTP 메서드
GET
헤더
| 필드 | 설명 |
|---|---|
| Content-type | 요청 데이터 타입. application/json 으로 고정 |
| x-authorization | 사용자 인증 수단, 인증 토큰. Bearer {AUTH TOKEN} |
- 요청 예시
GET /media/oauth2/GOOGLE
HEADER
Content-Type: application/json
x-authorization: BEARER {AUTH TOKEN}- 응답 결과 예시
**HTTP/1.1 200 OK
**Content-Type: application/json;charset=UTF-8
{
"status": "OK",
"message": "https://accounts.google.com/o/oauth2/v2/auth?acce......2111003%22%7D"
}
2. 팝업 창을 통한 인증 URL 호출
고객사 플랫폼은 자사 서버로부터 반환 받은 인증 URL을 팝업 창 형식으로 호출합니다. 이 팝업 창은 클라이언트가 매체사와의 연동 절차(예: 로그인, 권한 승인 등)을 직접 수행할 수 있는 환경을 제공합니다.
3. 연동 완료 후 메시지 송신 및 팝업 창 닫기
클라이언트가 매체사의 인증 절차를 완료하면, 팝업 창에 연동 결과와 함께 닫기 버튼이 표시됩니다. 클라이언트가 닫기 버튼을 클릭하면, 팝업 창이 닫히면서 부모창(고객사 플랫폼)으로 연동 결과 메시지를 송신합니다.
응답 데이터 항목
| 파라미터 | 타입 | 설명 |
|---|---|---|
| status | string | 매체 연동 결과 authorized : 연동 성공 unauthorized : 연동 실패 |
| code | string | 사용자 고유 식별 키 |
- 서버 측 코드 예시
// 매체 연동 로직 처리
// 매체 토큰 발생 (callback)
.....
// 연동 완료 후 부모창에 메시지 송신 및 팝업창 닫기
window.opener.postMessage('authorized', location.origin); // 성공, 실패 시 unauthorized
window.close();
$(document).ready(function() {
// 확인 클릭 시 부모 창에 연동 결과를 메시지로 보내고 팝업을 닫음
$('#confirmLink').click(function(e) {
e.preventDefault();
// 부모 창에 메시지 전송
// 연동 성공
window.opener.postMessage('{"status": "authorized", "code": "10135....90241"}', '*');
// 연동 실패
window.opener.postMessage('{"status": "unauthorized"}', '*');
// 팝업 창 닫기
window.close();
});
});
4. 연동 상태에 따른 UI 업데이트 (verified 속성 참고)
부모창(고객사 플랫폼)은 수신 된 메시지를 바탕으로 연동 상태를 확인하고, 필요한 후속 작업(예: UI 업데이트, 데이터 동기화 등)을 수행할 수 있습니다.
[^1]: 인증 토큰
[^2]: 인증 토크ㄴ
자주 묻는 질문
Google 연동을 시작하려면 어떤 API를 호출해야 하나요?
https://growthplatform.ai/media/oauth2/{MEDIA_CODE} 를 HTTPS GET 방식으로 호출합니다. MEDIA_CODE는 구글의 경우 GOOGLE로 지정합니다.
API 호출 시 인증은 어떻게 처리하나요?
헤더의 x-authorization 필드에 Bearer {AUTH TOKEN} 형식으로 인증 토큰을 담아 전달해야 합니다. Content-Type은 application/json으로 고정합니다.
연동 성공 여부는 어떻게 확인할 수 있나요?
팝업 창에서 인증이 완료되면 window.opener.postMessage를 통해 status 값(authorized 또는 unauthorized)과 code가 부모창으로 전달됩니다. 부모창은 이 메시지를 바탕으로 연동 성공 여부를 판단할 수 있습니다.
연동 완료 후 팝업 창은 자동으로 닫히나요?
클라이언트가 인증 절차를 완료하면 팝업 창에 결과와 닫기 버튼이 표시되며, 닫기 버튼을 클릭하면 팝업이 닫히면서 부모창으로 결과 메시지가 전송됩니다.
연동 결과를 받은 후 고객사 플랫폼에서 해야 할 작업은 무엇인가요?
수신한 메시지의 연동 상태를 확인하여 UI 업데이트나 데이터 동기화 같은 필요한 후속 작업을 수행하면 됩니다.