Memulai

Ringkasan

Dokumen ini akan memandu Anda melalui 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 bisa menjalankan aplikasi contoh di server dengan mengikuti 2 langkah mudah ini:

  1. Buat client ID baru
  2. Menyalin dan menempel kodenya

Setelah Anda mengaktifkan dan menjalankan aplikasi ini, bagian berikutnya akan menjelaskan secara detail bagaimana semua bagian berfungsi bersama-sama.

Buat Client ID 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 memerlukan client ID.

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

Saat Anda mengikuti petunjuk ini, jangan mengabaikan dua langkah penting ini:

  • Mengaktifkan Analytics API
  • Tetapkan origin yang benar

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

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

Salin dan Tempel Kodenya

Setelah memiliki client ID dengan origin yang benar, Anda siap membuat demo. Cukup salin dan tempel kode berikut ke file HTML pada plugin server Anda di client ID yang bertuliskan: "Insert your client ID here".

<!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 akan memandu Anda, langkah demi langkah, apa yang terjadi dalam kode yang diberikan untuk aplikasi contoh. Setelah Anda memiliki pemahaman tentang cara kerjanya, Anda harus 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. Masing-masing komponen ini dirender di dalam elemen HTML berikut:

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

Saat membuat komponen, Anda memberi tahunya penampung apa yang akan digunakan berdasarkan atribut ID-nya, seperti yang akan Anda lihat pada contoh selanjutnya.

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, semua 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,
});

Tindakan ini akan membuat tombol di dalam elemen dengan ID 'tombol autentikasi' 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 laporannya.

Untuk membuat pemilih tampilan, Anda hanya perlu referensi container yang dibuat pada 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 perlu memanggil execute() yang ditangani pada langkah 6.

Langkah 5: Buat diagram linimasa

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

Untuk membuat komponen diagram, Anda harus menentukan parameter kueri API serta opsi diagram. Dalam opsi diagram, terdapat 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 pemilih tampilan, tindakan ini akan membuat komponen diagram, tetapi untuk merendernya ke halaman, Anda perlu memanggil execute(), yang akan dijelaskan pada langkah berikutnya.

Langkah 6: Hubungkan komponen untuk bekerja sama

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

Aplikasi contoh dalam panduan ini menunggu untuk merender pemilih tampilan hingga setelah otorisasi terjadi, dan aplikasi contoh akan 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 dikeluarkan oleh berbagai komponen, lihat referensi API.

Langkah Berikutnya

Panduan ini memandu Anda melalui cara membuat visualisasi dasar dengan Embed API. Jika Anda ingin mempelajari lebih lanjut, lihat referensi API untuk memahami sepenuhnya apa yang mungkin dilakukan.