Memulai

Ringkasan

Dokumen ini akan memberikan contoh lengkap tentang cara menggunakan Embed API. Setelah selesai, Anda akan memiliki aplikasi yang terlihat seperti ini.

Screenshot contoh yang tercakup dalam panduan ini
Screenshot contoh yang dibahas dalam panduan ini.

Membuat Dasbor Sederhana

Anda dapat menjalankan aplikasi contoh di server dengan mengikuti 2 langkah mudah berikut:

  1. Buat client ID baru
  2. Salin dan tempel kode

Setelah aplikasi ini aktif dan berjalan, bagian berikutnya akan menjelaskan secara mendetail bagaimana semua bagian berfungsi bersama.

Buat ID Klien Baru

Embed API menangani hampir semua proses otorisasi untuk Anda dengan menyediakan komponen login sekali klik yang menggunakan alur OAuth 2.0 yang sudah dikenal. Agar tombol ini berfungsi di halaman Anda, Anda memerlukan client ID.

Jika Anda belum pernah membuat client ID, Anda dapat melakukannya dengan mengikuti petunjuk ini.

Saat membaca petunjuk, penting untuk tidak mengabaikan dua langkah penting berikut:

  • Mengaktifkan Analytics API
  • Menetapkan asal yang benar

Asal dapat mengontrol domain yang diizinkan untuk menggunakan kode ini guna memberikan otorisasi kepada pengguna. Tindakan ini mencegah orang lain menyalin kode Anda dan menjalankannya di situs mereka.

Misalnya, jika situs Anda dihosting di domain example.com, pastikan untuk menetapkan asal berikut untuk client ID http://example.com. Jika ingin menguji kode secara lokal, Anda juga harus menambahkan asal untuk server lokal, misalnya: http://localhost:8080.

Salin dan Tempel Kode

Setelah memiliki client ID dengan asal yang tepat, Anda siap membuat demo. Cukup salin dan tempel kode berikut ke dalam file HTML di steker server Anda di client ID dengan keterangan: "Masukkan client ID di sini".

<!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>

Panduan Kode

Bagian ini memandu Anda, langkah demi langkah, persis apa yang terjadi dalam kode yang diberikan untuk aplikasi contoh. Setelah Anda memahami cara kerjanya, Anda seharusnya dapat membuatnya sendiri.

Langkah 1: Buat penampung komponen

Sebagian besar komponen Embed API akan merender sesuatu secara visual ke halaman Anda. Cara Anda mengontrol lokasi komponen tersebut adalah dengan membuat container untuk komponen tersebut. Dalam aplikasi contoh, kita memiliki tombol autentikasi, pemilih tampilan, dan diagram. Setiap komponen ini dirender dalam elemen HTML berikut:

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

Saat membuat komponen, Anda memberi tahu penampung apa yang akan digunakan berdasarkan atribut ID-nya, seperti yang akan Anda lihat dalam contoh berikutnya.

Langkah 2: Muat library

Embed API dapat dimuat dengan cuplikan berikut.

<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>

Saat library dimuat sepenuhnya, callback yang diteruskan ke gapi.analytics.ready akan dipanggil.

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

Langkah 3: Berikan otorisasi kepada pengguna

Embed API menangani hampir semua proses otorisasi untuk Anda dengan menyediakan komponen login sekali klik yang menggunakan alur OAuth 2.0 yang sudah dikenal. Agar tombol ini berfungsi di halaman, Anda harus meneruskan referensi penampung dan client ID.

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

Ini akan membuat tombol di dalam elemen dengan 'auth-button' ID yang menangani alur otorisasi untuk Anda.

Langkah 4: Buat pemilih tampilan

Komponen pemilih Tampilan dapat digunakan untuk mendapatkan ID tampilan tertentu, sehingga Anda dapat menjalankan laporan untuk komponen tersebut.

Untuk membuat pemilih tampilan, Anda hanya memerlukan referensi penampung yang Anda buat di langkah 1.

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

Tindakan ini akan membuat komponen pemilih tampilan, tetapi belum merendernya di halaman. Untuk melakukannya, Anda harus memanggil execute(), yang ditangani pada langkah 6.

Langkah 5: Buat diagram linimasa

Embed API memberi Anda komponen diagram yang merupakan diagram Google serta objek laporan dalam diagram. Hal ini sangat menyederhanakan proses untuk menampilkan data karena objek diagram akan menjalankan laporan Anda di balik layar dan otomatis memperbarui hasilnya.

Untuk membuat komponen diagram, Anda harus menentukan parameter kueri API serta opsi diagram. Dalam opsi diagram, ini merupakan referensi ke ID penampung yang Anda buat di langkah 1.

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'
  }
});

Seperti halnya pemilih tampilan, hal ini akan membuat komponen diagram, tetapi untuk merendernya ke halaman yang perlu Anda panggil execute(), yang akan dijelaskan pada langkah berikutnya.

Langkah 6: Hubungkan komponen untuk bekerja sama

Komponen API sematan memunculkan peristiwa saat berbagai hal terjadi seperti otorisasi, memilih tampilan baru, atau diagram yang dirender sepenuhnya.

Aplikasi contoh dalam panduan ini menunggu untuk merender pemilih tampilan sampai setelah otorisasi terjadi, dan memperbarui diagram linimasa setiap kali tampilan baru dipilih dari pemilih tampilan.

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

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

Untuk mengetahui daftar lengkap semua peristiwa yang dihasilkan oleh berbagai komponen, lihat referensi API.

Langkah Berikutnya

Panduan ini akan menuntun Anda dalam membuat visualisasi dasar dengan Embed API. Jika Anda ingin mempelajari lebih lanjut, lihat referensi API untuk mendapatkan gambaran lengkap tentang kemungkinan hal tersebut.