시작하기

개요

이 문서에서는 Embed API를 사용하는 방법에 대한 전체 예를 설명합니다. 완료되면 다음과 같은 애플리케이션이 생성됩니다.

이 가이드에서 다룬 예시의 스크린샷
이 가이드에서 다룬 예시의 스크린샷

간단한 대시보드 만들기

다음의 간단한 2단계를 따라 샘플 애플리케이션을 서버에서 실행할 수 있습니다.

  1. 새 클라이언트 ID 만들기
  2. 코드 복사하여 붙여넣기

이 애플리케이션을 설정하고 실행한 후 다음 섹션에서는 모든 요소가 어떻게 함께 작동하는지 자세히 설명합니다.

새 클라이언트 ID 만들기

Embed API는 친숙한 OAuth 2.0 흐름을 사용하는 원클릭 로그인 구성요소를 제공하여 거의 모든 승인 프로세스를 처리합니다. 이 버튼이 페이지에서 작동하도록 하려면 클라이언트 ID가 필요합니다.

아직 클라이언트 ID를 만든 적이 없다면 이 안내에 따라 만들 수 있습니다.

안내를 따를 때는 다음 두 가지 중요한 단계를 간과하지 않아야 합니다.

  • Analytics API 사용 설정
  • 올바른 출처 설정

출처는 이 코드를 사용하여 사용자를 승인할 수 있는 도메인을 관리합니다. 이렇게 하면 다른 사람이 코드를 복사하여 사이트에서 실행하는 것을 방지할 수 있습니다.

예를 들어 웹사이트가 example.com 도메인에서 호스팅되는 경우 클라이언트 ID http://example.com에 다음 출처를 설정해야 합니다. 코드를 로컬에서 테스트하려면 로컬 서버의 출처도 추가해야 합니다(예: http://localhost:8080).

코드 복사 및 붙여넣기

적절한 출처가 설정된 클라이언트 ID를 확보하면 데모를 만들 수 있습니다. 다음 코드를 복사하여 서버의 HTML 파일에 붙여넣고 '여기에 클라이언트 ID 삽입'이라고 표시된 클라이언트 ID를 연결하세요.

<!DOCTYPE html>
<html>
<head>
  <title>Embed API Demo</title>
</head>
<body>

<!-- Step 1: Create the containing elements. -->

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

<!-- Step 2: Load the library. -->

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
<script>
gapi.analytics.ready(function() {

  // Step 3: Authorize the user.

  var CLIENT_ID = 'Insert your client ID here';

  gapi.analytics.auth.authorize({
    container: 'auth-button',
    clientid: CLIENT_ID,
  });

  // Step 4: Create the view selector.

  var viewSelector = new gapi.analytics.ViewSelector({
    container: 'view-selector'
  });

  // Step 5: Create the timeline chart.

  var timeline = new gapi.analytics.googleCharts.DataChart({
    reportType: 'ga',
    query: {
      'dimensions': 'ga:date',
      'metrics': 'ga:sessions',
      'start-date': '30daysAgo',
      'end-date': 'yesterday',
    },
    chart: {
      type: 'LINE',
      container: 'timeline'
    }
  });

  // Step 6: Hook up the components to work together.

  gapi.analytics.auth.on('success', function(response) {
    viewSelector.execute();
  });

  viewSelector.on('change', function(ids) {
    var newIds = {
      query: {
        ids: ids
      }
    }
    timeline.set(newIds).execute();
  });
});
</script>
</body>
</html>

코드 둘러보기

이 섹션에서는 샘플 애플리케이션에 제공된 코드에서 정확히 어떤 작업을 할 수 있는지 단계별로 설명합니다. 작동 방식을 파악하면 직접 만들 수 있습니다.

1단계: 구성요소 컨테이너 만들기

대부분의 Embed API 구성요소는 페이지에 시각적으로 무언가를 렌더링합니다. 이러한 구성요소의 위치를 제어하는 방법은 해당 구성요소를 위한 컨테이너를 만드는 것입니다. 예시 애플리케이션에는 인증 버튼, 뷰 선택기, 차트가 있습니다. 이러한 각 구성요소는 다음 HTML 요소 내에서 렌더링됩니다.

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

구성요소를 만들 때는 이후 예에서 살펴볼 것처럼 구성요소 ID 속성으로 사용할 컨테이너를 지정합니다.

2단계: 라이브러리 로드

Embed API는 다음 스니펫으로 로드할 수 있습니다.

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

라이브러리가 완전히 로드되면 gapi.analytics.ready에 전달된 콜백이 호출됩니다.

<script>
gapi.analytics.ready(function() {
  // Put your application code here...
});
</script>

3단계: 사용자 승인하기

Embed API는 친숙한 OAuth 2.0 흐름을 사용하는 원클릭 로그인 구성요소를 제공하여 거의 모든 승인 프로세스를 처리합니다. 페이지에서 이 버튼이 작동하도록 하려면 컨테이너 참조 및 클라이언트 ID를 전달해야 합니다.

gapi.analytics.auth.authorize({
  container: 'auth-button',
  clientid: CLIENT_ID,
});

이렇게 하면 승인 흐름을 처리하는 'auth-button' ID를 가진 요소 내부에 버튼이 생성됩니다.

4단계: 뷰 선택기 만들기

뷰 선택기 구성요소를 사용하여 특정 뷰의 ID를 가져올 수 있으므로 해당 뷰에 대한 보고서를 실행할 수 있습니다.

뷰 선택기를 만들려면 1단계에서 만든 컨테이너 참조만 있으면 됩니다.

var viewSelector = new gapi.analytics.ViewSelector({
  container: 'view-selector'
});

이렇게 하면 뷰 선택기 구성요소가 생성되지만 아직 페이지에 렌더링되지는 않습니다. 이렇게 하려면 6단계에서 처리되는 execute()를 호출해야 합니다.

5단계: 타임라인 차트 만들기

Embed API는 Google 차트인 동시에 보고서 객체인 차트 구성요소를 제공합니다. 이렇게 하면 차트 객체가 백그라운드에서 보고서를 실행하고 결과에 따라 자동으로 업데이트되므로 데이터 표시 프로세스가 크게 간소화됩니다.

차트 구성요소를 만들려면 API 쿼리 매개변수와 차트 옵션을 지정해야 합니다. 차트 옵션에는 1단계에서 만든 컨테이너의 ID가 표시됩니다.

var timeline = new gapi.analytics.googleCharts.DataChart({
  reportType: 'ga',
  query: {
    'dimensions': 'ga:date',
    'metrics': 'ga:sessions',
    'start-date': '30daysAgo',
    'end-date': 'yesterday',
  },
  chart: {
    type: 'LINE',
    container: 'timeline'
  }
});

이렇게 하면 뷰 선택기와 마찬가지로 차트 구성요소가 생성되지만 페이지로 렌더링하려면 execute()를 호출해야 합니다. 이 내용은 다음 단계에서 설명합니다.

6단계: 함께 작동하도록 구성요소 연결

Embed API 구성요소는 승인 성공, 새 뷰 선택, 차트 완전히 렌더링 등 다양한 상황이 발생할 때 이벤트를 내보냅니다.

이 가이드의 예시 애플리케이션은 승인이 완료될 때까지 뷰 선택기 렌더링을 대기하고 뷰 선택기에서 새 뷰가 선택될 때마다 타임라인 차트를 업데이트합니다.

gapi.analytics.auth.on('success', function(response) {
  viewSelector.execute();
});

viewSelector.on('change', function(ids) {
  var newIds = {
    query: {
      ids: ids
    }
  }
  timeline.set(newIds).execute();
});

다양한 구성요소가 내보내는 모든 이벤트의 전체 목록은 API 참조를 확인하세요.

다음 단계

이 가이드에서는 Embed API를 사용하여 기본적인 시각화를 만드는 방법을 설명했습니다. 자세히 알아보려면 API 참조에서 무엇이 가능한지 확인해 보세요.