사용자 제어 계정 프로비저닝 – API 개발자 가이드

이 문서에서는 Provisioning API를 사용하여 새 Google 애널리틱스 계정을 만드는 중요한 개념을 설명합니다.

주의: Provisioning API는 현재 초대를 통해서만 사용할 수 있습니다. 일반에 공개되어 즉시 사용할 수 있는 Google Analytics Admin API V1의 계정 프로비저닝 기능을 사용해 보세요.

소개

Provisioning API를 사용하면 신규 Google 애널리틱스 계정을 만들고 고객을 위해 Google 애널리틱스를 대규모로 사용 설정할 수 있습니다. 자격 있는 서비스 제공업체 및 대규모 파트너를 대상으로 합니다. Provisioning API에 대한 소개는 Provisioning API 개요를 참조하세요.

시작하기 전에

모든 Google 애널리틱스 API는 유사한 방식으로 액세스됩니다. 프로비저닝 API를 시작하기 전에 다음 작업을 수행해야 합니다.

• API에서 작동하는 프로그래밍 언어별 클라이언트 라이브러리의 전체 목록은 클라이언트 라이브러리 페이지를 참조하세요.
• API 인터페이스 및 클라이언트 라이브러리 없이 데이터에 액세스하는 방법에 대해 알아보려면 참조 가이드를 읽어보세요.

각 클라이언트 라이브러리는 Provisioning API에 액세스하기 위한 단일 애널리틱스 서비스 객체를 제공합니다. 서비스 객체를 만들려면 일반적으로 다음 단계를 따라야 합니다.

1. Google API 콘솔에 애플리케이션을 등록합니다.
2. 새 Google 애널리틱스 계정을 만들 수 있도록 승인합니다.
3. 애널리틱스 서비스 객체를 만듭니다.

이 단계를 완료하지 않았다면 중단하고 Hello Google Analytics API 튜토리얼을 읽어 보세요. 이 튜토리얼에서는 Google 애널리틱스 API 애플리케이션을 빌드하는 초기 단계를 안내합니다. 이 과정을 완료하면 Google 애널리틱스 API에 액세스하여 실제 작업을 수행하는 방법을 이해할 수 있습니다.

개요

Provisioning API를 사용하여 Google 애널리틱스 계정을 만드는 경우 다음과 같은 두 가지 별도의 흐름을 고려해야 합니다.

• 기술 흐름: 사용자를 위한 Google 애널리틱스 계정을 프로그래매틱 방식으로 프로비저닝하는 엔드 투 엔드 흐름입니다.
• 사용자 흐름: 사용자 관점에서 계정 생성 흐름을 위해 고려해야 하는 구현 고려사항입니다.

이 문서에서는 각 흐름의 대략적인 단계와 요구사항을 설명합니다.

기술적 흐름

Provisioning API를 사용하여 새 계정을 만들고 Google 애널리틱스와 통합하는 대략적인 단계는 다음과 같습니다.

1. 사용자에게 OAuth 2.0을 사용하여 애플리케이션/서비스를 인증 및 승인하라는 메시지를 표시합니다.
2. 프로비저닝 API를 사용하여 계정 티켓을 생성합니다.
3. Google 애널리틱스 서비스 약관 (TOS)에 동의하고 응답을 처리하도록 사용자를 리디렉션합니다.
4. (선택사항) 계정 및 통합 기회를 구성합니다.

이 모든 단계가 성공적으로 완료되면 사용자의 Google 애널리틱스 계정이 생성되고 새 계정의 계정 ID, 속성 ID, 보기 (프로필) ID가 생성됩니다.

아래의 각 단계에는 단계를 완료하기 위한 요구사항, 단계의 결과, 단계의 기술 흐름에 관한 설명이 있습니다.

1. 인증 및 승인

각 사용자는 애플리케이션을 승인하고 자신을 대신하여 Google 애널리틱스 계정을 프로비저닝할 수 있는 기능을 부여해야 합니다. 이 단계는 OAuth 2.0 웹 서버 애플리케이션 흐름을 수행하는 것이 좋습니다.

이 단계를 완료하는 데 필요한 사항

• 클라이언트 ID - 사용할 프로젝트의 Client ID입니다. 이 작업은 Google Developers Console에서 사용할 수 있습니다. 자세한 내용은 OAuth 2.0 웹 서버 흐름을 참조하세요.
• 리디렉션 URI - 사용자가 리디렉션되고 OAuth 2.0 응답이 전송됩니다.
  • Google Developers Console을 사용하여 프로젝트의 Redirect URIs를 구성하고 Client ID를 가져옵니다.
  • 이 매개변수의 값은 Google Developers Console에 등록된 값 중 하나와 정확하게 일치해야 합니다(http 또는 https 스키마, 대소문자, 후행 '/' 포함).
• Google Analytics Provisioning API의 인증 범위

이 단계의 결과

OAuth 2.0 흐름이 완료되면 사용자는 애플리케이션을 대신하여 계정을 프로비저닝하도록 애플리케이션을 승인하게 되며, 개발자는 사용자를 위한 액세스 토큰을 갖게 됩니다.

토큰 및 범위에 대한 참고사항:

• 계정을 만든 후 사용자의 계정 구성 또는 보고 데이터를 추가로 요청하려면 이 단계에서 추가 범위를 승인할 수도 있습니다. 예를 들어 readonly 또는 edit 범위입니다.
• 액세스 토큰의 수명은 제한되어 있습니다. 애플리케이션에서 단일 액세스 토큰의 전체 기간을 초과하여 Google Analytics API에 액세스해야 하는 경우 access_type=offline를 설정하여 갱신 토큰을 요청할 수도 있습니다. 갱신 토큰은 애플리케이션이 새 액세스 토큰을 가져올 수 있으므로 각 사용자의 안전한 장기 저장소에 저장해야 합니다. 자세한 내용은 오프라인 액세스를 참조하세요.

이 단계의 기술적 흐름

사용자의 액세스 토큰을 가져와야 합니다. OAuth 2.0 웹 서버에 설명된 흐름에 따라 사용자를 Google 계정 서비스로 보낸 다음, 인증 흐름을 완료한 후 사용자가 서비스로 다시 리디렉션될 때 응답을 처리합니다.

사용자가 방문할 OAuth 2.0 URL을 구성합니다.

사용자가 시작하기 또는 계정 만들기 버튼이나 링크를 클릭하면 이 링크는 사용자에게 프로비저닝 권한을 부여하도록 요청하는 OAuth 2.0 흐름의 시작을 가리켜야 합니다. 예를 들면 다음과 같습니다.

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}

Google 계정 서비스의 응답 처리

사용자가 애플리케이션 액세스 권한을 부여하기로 결정하면 승인 코드가 포함된 쿼리 매개변수로 구성한 URL에 지정된 redirect_uri로 리디렉션됩니다. 사용자가 요청을 승인하면 Google Accounts API에 POST 요청을 실행하여 승인 코드 응답을 사용하여 승인 코드를 액세스 토큰으로 교환할 수 있습니다.

참고: 사용자가 요청을 거부하면 오류 응답도 올바르게 처리해야 합니다.

갱신 토큰 저장 (해당하는 경우)

액세스 토큰은 다음 단계에서 사용되므로 일시적으로 저장할 수 있습니다. 사용자에 대해서도 갱신 토큰을 요청한 경우 장기적으로 사용할 수 있도록 안전하게 저장해야 합니다. 갱신 토큰은 수명이 길며 새 액세스 토큰을 발급하는 데 사용할 수 있습니다.

2. 프로비저닝 API를 사용하여 계정 티켓 만들기

승인된 사용자의 액세스 토큰이 있으면 이 토큰을 통해 Provisioning API에 사용자의 계정 티켓 생성 요청을 할 수 있습니다. 계정 티켓은 사용자 계정을 만들기 위한 첫 번째 단계입니다.

참고: createAccountTicket 메서드에 대한 자세한 내용은 Provisioning API 참조를 확인하세요.

이 단계를 완료하는 데 필요한 사항

인증 및 승인과 다음 프로비저닝 세부정보에 설명된 승인된 사용자의 액세스 토큰입니다.

• 리디렉션 URI
  • Google 애널리틱스 서비스 약관 (TOS) 페이지 이후에 사용자가 리디렉션되는 위치를 정의합니다. OAuth 2.0 승인 흐름에서 지정된 리디렉션 URI와 다를 수 있습니다.
  • 리디렉션 URI 매개변수의 값이 Google Developers Console에 등록된 값 (http 또는 https 스키마, 대소문자, 후행 '/' 포함) 중 하나와 정확하게 일치해야 합니다.
• 계정 필드
  • 계정의 name 속성은 필수입니다.
• 웹 속성 필드
  • name 속성은 속성의 필수 속성입니다.
  • websiteUrl은 필수입니다.
• 프로필 입력란
  • 프로필의 name 속성은 필수입니다.
  • timezone를 선택적으로 제공할 수 있습니다. 기본값은 America/Los_Angeles입니다.

계정 티켓을 만들 때 위에서 식별된 기본 필드만 설정할 수 있습니다. 계정이 생성된 후에는 Management API를 사용하여 속성 또는 보기 (프로필)의 추가 구성을 변경할 수 있습니다.

이러한 필드에 대한 자세한 내용은 계정, 속성, 보기(프로필)에 대한 API 참조를 확인하세요.

이 단계의 결과

프로비저닝 API에 요청이 성공적으로 전송되면 해당 사용자에게 단기 계정 티켓이 부여됩니다. 계정 티켓 ID는 사용자에게 서비스 약관 (TOS)에 동의하고 계정을 활성화하라는 메시지를 표시하는 마지막 단계에서 사용됩니다. 서비스 약관에 동의하기 전에는 계정을 사용할 수 없습니다.

이 단계의 기술적 흐름

인증 및 승인 중에 획득한 사용자의 액세스 토큰을 사용하여 프로비저닝 API에 HTTP POST 요청이 전송됩니다.

계정 티켓 생성을 위한 프로비저닝 API 요청

요청하는 방법에 대한 자세한 내용은 Provisioning API 참조의 createAccountTicket 메서드를 검토하세요.

프로비저닝 API의 응답

요청이 성공하면 200 응답이 반환됩니다. 응답 본문에는 수명이 짧은 계정 티켓이 포함됩니다. 계정 티켓은 새 계정 트리의 ID와 세부정보로 구성됩니다.

응답에 대한 자세한 내용은 프로비저닝 API 참조의 Account Ticket resource를 확인하세요.

오류 응답도 애플리케이션에서 처리해야 합니다.

3. 사용자가 Google 애널리틱스 서비스 약관(TOS)에 동의함

사용자의 계정 티켓 ID가 있으면 TOS 요청과 함께 이 ID를 사용하여 사용자에게 Google 애널리틱스 서비스 약관에 동의하라는 메시지를 표시할 수 있습니다.

이 단계를 완료하는 데 필요한 사항

승인된 사용자의 계정 티켓 ID

이 단계의 결과

계정 티켓 ID를 사용하여 TOS 흐름을 성공적으로 완료하면 계정, 속성, 보기 (프로필)가 생성됩니다. 이제 사용자는 활성 계정을 갖게 됩니다. TOS 페이지의 응답에 계정 ID, 속성 ID, 보기 (프로필) ID가 포함됩니다.

이 단계의 기술적 흐름

계정 티켓 ID를 사용하여 서비스 약관에 동의할 수 있는 Google 애널리틱스 서비스 약관 페이지로 사용자를 리디렉션하고 API의 응답을 처리해야 합니다.

사용자가 방문할 TOS URL을 작성합니다.

사용자를 서비스 약관 페이지로 리디렉션하고 URL에 계정 티켓 ID를 포함합니다.

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}

TOS 응답 처리

사용자가 TOS 페이지에서 작업을 수행하면 계정 티켓 생성 중에 지정된 redirectUri로 다시 리디렉션됩니다. TOS 페이지의 응답은 쿼리 문자열의 일부로 포함됩니다.

성공 응답은 새로 만든 계정 구조와 기존 accountTicketId에 대한 데이터를 반환합니다.

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

예를 들어 애플리케이션의 TOS 핸들러가 http://www.your-app.com/gaTOS에 있으면 계정 티켓을 생성할 때 redirectUri로 설정해야 합니다. 계정 티켓이 유효하고 사용자가 TOS에 동의한 경우 애플리케이션의 TOS 핸들러는 accountId, webPropertyId, profileId, accountTicketId 쿼리 매개변수가 포함된 HTTP GET 요청을 예상하고 적절하게 처리해야 합니다.

실패 응답에는 오류 응답이 포함됩니다.

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

또한 TOS 핸들러는 문제가 발생했음을 나타내는 error 쿼리 매개변수가 포함된 HTTP GET 요청을 올바르게 처리해야 합니다. 쿼리 매개변수의 값을 사용하여 추가 작업을 수행하거나 사용자에게 메시지를 표시할 수 있습니다.

• error=user_cancel - 사용자가 서비스 약관에 동의하지 않았습니다.
• error=max_accounts_reached - 사용자가 Google 애널리틱스 계정 한도에 도달했습니다.
• error=backend_error - 일반적인 오류입니다. 서버에서 위 카테고리에 속하지 않는 오류를 반환했습니다.

참고: 애플리케이션은 성공 응답 및 오류 응답을 모두 처리하고 error 쿼리 매개변수 또는 쿼리 매개변수가 없는 응답의 알 수 없는 값을 적절하게 처리해야 합니다.

4. (선택사항) 통합 기회

위의 기술 흐름을 따랐다면 사용자의 계정이 만들어졌고 계정 ID, 속성 ID, 보기 (프로필) ID를 갖게 됩니다. 또한 추가 권한을 요청한 경우 사용자의 갱신 토큰도 있을 수 있습니다. 이 데이터를 사용하여 다음을 수행할 수 있습니다.

• 해당하는 경우 사용자 웹사이트의 각 페이지에 대해 새로 만든 계정의 속성 ID를 표준 Google 애널리틱스 추적 스니펫에 자동으로 삽입합니다.
• Management API를 사용하여 사용자의 속성을 자동으로 구성합니다.
• Embed API 또는 Core Reporting API를 사용하여 제품 내 (예: 관리 패널) 내 사용자에게 보고서를 제공합니다.

사용자 흐름

이 섹션에서는 사용자 관점에서 계정 생성 흐름 단계와 관련된 구현 고려사항을 설명합니다.

이 흐름은 사용자가 속성에 대한 분석을 사용 설정하기 위해 다음 두 가지 옵션을 제공한 것으로 시작됩니다.

1. Google 애널리틱스 계정 만들기
2. 기존 Google 애널리틱스 계정을 사용하세요. (참고: 이 문서에서는 이 과정을 다루지 않습니다. 사용자의 Google 애널리틱스 구성 데이터에 액세스하는 방법에 관한 자세한 내용은 Management API를 참고하세요.)

새 Google 애널리틱스 계정을 만들 때 계정 이름, 속성 이름 등 프로비저닝 요청과 함께 보내야 하는 정보가 있습니다. 사용자 및 사용자에게 표시하려는 흐름에 대한 정보에 따라 사용자가 '계정 만들기'를 클릭한 후 사용자 흐름을 시작하는 세 가지 기본 옵션이 있습니다.

승인 후 계정 세부정보 요청

이 경우 프로세스 도중에 사용자에게 계정 세부정보를 묻는 메시지가 표시됩니다. 흐름은 다음과 유사합니다.

1. 사용자가 OAuth 2.0 흐름을 위해 Google 계정 서비스로 리디렉션됩니다. 사용자에게 Google 계정이 없거나 로그인하지 않은 경우 Google 계정을 만들거나 로그인하라는 메시지가 표시됩니다.
2. 사용자에게 'Google 애널리틱스 계정 만들기' 애플리케이션을 승인하라는 메시지가 표시됩니다.
3. 사용자가 애플리케이션에 대한 권한 요청을 수락합니다.
4. 사용자가 서비스 제공업체로 리디렉션됩니다. 사용자가 승인을 거부해도 서비스 제공업체로 다시 리디렉션됩니다.
5. 생성할 계정에 대한 세부정보 (예: 계정 이름, 속성 이름, 프로필 이름, 시간대, 웹사이트 URL 등)를 수집할 수 있는 양식이 사용자에게 표시됩니다.
6. 사용자가 양식을 작성하고 제출하면 Google로 리디렉션되거나 Google 애널리틱스 서비스 약관 (TOS)이 표시됩니다.
7. 사용자가 TOS에 동의합니다.
8. 사용자가 서비스 제공업체로 리디렉션되고 계정 세부정보와 계정 액세스 방법이 포함된 Google 애널리틱스 계정이 성공적으로 생성되었다는 성공 메시지가 표시됩니다. 사용자가 TOS에 동의하지 않으면 서비스 제공업체로 다시 리디렉션됩니다.

승인 전에 계정 세부정보 요청

이 경우 생성하려는 계정의 구성 세부정보를 사용자에게 미리 묻는 메시지가 표시됩니다. 흐름은 다음과 유사합니다.

1. 서비스 제공업체 사이트에서 사용자에게 생성할 계정에 대한 세부정보 (예: 계정 이름, 속성 이름, 프로필 이름, 시간대, 웹사이트 URL)를 수집하기 위한 양식이 표시됩니다.
2. 사용자가 양식을 작성하고 제출을 클릭하면 OAuth 2.0 흐름용 Google 계정 서비스로 리디렉션됩니다. 사용자에게 Google 계정이 없거나 로그인하지 않은 경우 Google 계정을 만들거나 로그인하라는 메시지가 표시됩니다.
3. 사용자에게 'Google 애널리틱스 계정 만들기' 애플리케이션을 승인하라는 메시지가 표시됩니다.
4. 사용자가 애플리케이션에 대해 요청된 권한을 수락합니다.
5. 사용자가 서비스 제공업체로 리디렉션됩니다.
6. 사용자가 Google로 리디렉션되거나 Google 애널리틱스 서비스 약관(TOS)이 표시됩니다.
7. 사용자가 TOS에 동의합니다.
8. 사용자가 서비스 제공업체로 리디렉션되고 계정 세부정보와 계정 액세스 방법이 포함된 Google 애널리틱스 계정이 성공적으로 생성되었다는 성공 메시지가 표시됩니다.

계정 세부정보 자동 입력 또는 양식 건너뛰기

사용자 계정에 대한 정보 (예: 웹사이트 URL, 웹사이트 이름, 시간대 등)가 이미 있는 경우 위의 두 옵션을 다음과 같이 더 단순화할 수 있습니다.

• 양식을 미리 채우고 사용자가 원하는 경우 수정할 수 있도록 허용
• 양식 단계를 완전히 건너뛰고 기존 정보를 사용하여 자동으로 계정을 만듭니다.

관련 리소스

• 애널리틱스 계정 설정 변경
• 애널리틱스 계정 삭제