เริ่มต้นใช้งาน

ภาพรวม

เอกสารนี้จะแนะนำตัวอย่างวิธีใช้ API ที่ฝังอยู่ เมื่อเสร็จสิ้นแล้ว คุณจะมีแอปพลิเคชันที่มีลักษณะเช่นนี้

ภาพหน้าจอของตัวอย่างที่ครอบคลุมในคู่มือนี้
ภาพหน้าจอของตัวอย่างที่ครอบคลุมในคู่มือนี้

การสร้างหน้าแดชบอร์ดที่เรียบง่าย

คุณทำให้แอปพลิเคชันตัวอย่างทำงานบนเซิร์ฟเวอร์ได้โดยทำตาม 2 ขั้นตอนง่ายๆ ต่อไปนี้

  1. สร้างรหัสไคลเอ็นต์ใหม่
  2. คัดลอกและวางโค้ด

หลังจากที่คุณมีแอปพลิเคชันนี้ทำงานแล้ว ส่วนถัดไปจะอธิบายรายละเอียดว่าชิ้นส่วนทั้งหมดเชื่อมโยงกันอย่างไร

สร้างรหัสไคลเอ็นต์ใหม่

API ฝังจะจัดการขั้นตอนการให้สิทธิ์เกือบทั้งหมดให้คุณโดยมอบคอมโพเนนต์การลงชื่อเข้าใช้แบบคลิกเดียวที่ใช้ขั้นตอน OAuth 2.0 ที่คุ้นเคย หากต้องการให้ปุ่มนี้ทำงานบนหน้าเว็บ คุณจะต้องมีรหัสไคลเอ็นต์

หากไม่เคยสร้างรหัสไคลเอ็นต์ คุณจะสร้างได้โดยทำตาม วิธีการเหล่านี้

ในขณะที่คุณทำตามคำแนะนำต่างๆ คุณต้องไม่มองข้ามขั้นตอนสำคัญ 2 ขั้นตอนต่อไปนี้

  • เปิดใช้ Analytics API
  • กำหนดต้นทางที่ถูกต้อง

ต้นทางจะควบคุมว่าโดเมนใดบ้างที่จะใช้โค้ดนี้เพื่อให้สิทธิ์ผู้ใช้ได้ วิธีนี้ช่วยป้องกันไม่ให้ผู้อื่นคัดลอกโค้ดของคุณและเรียกใช้บนเว็บไซต์ของตน

เช่น หากเว็บไซต์โฮสต์อยู่บนโดเมน example.com โปรดตรวจสอบว่าได้ตั้งค่าต้นทางต่อไปนี้สําหรับรหัสไคลเอ็นต์ http://example.com แล้ว หากต้องการทดสอบโค้ดภายในเครื่อง คุณจะต้องเพิ่มต้นทางสำหรับเซิร์ฟเวอร์ภายในด้วย เช่น http://localhost:8080

คัดลอกและวางโค้ด

เมื่อคุณมีรหัสไคลเอ็นต์ที่มีการตั้งค่าต้นทางที่เหมาะสมแล้ว คุณก็พร้อมที่จะสร้างเดโมได้ เพียงคัดลอกและวางโค้ดต่อไปนี้ลงในไฟล์ HTML บนเซิร์ฟเวอร์ของคุณ ให้เสียบรหัสไคลเอ็นต์ที่มีข้อความว่า "ใส่รหัสไคลเอ็นต์ของคุณที่นี่"

<!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: สร้างคอนเทนเนอร์คอมโพเนนต์

คอมโพเนนต์ ฝัง API ส่วนใหญ่จะแสดงผลบางอย่างบนหน้าเว็บ วิธีที่คุณสามารถควบคุมตำแหน่งของคอมโพเนนต์เหล่านั้นคือการสร้างคอนเทนเนอร์สำหรับคอมโพเนนต์เหล่านั้น ในแอปพลิเคชันตัวอย่าง เรามีปุ่มการตรวจสอบสิทธิ์ ตัวเลือกมุมมอง และแผนภูมิ คอมโพเนนต์แต่ละรายการต่อไปนี้จะแสดงผลภายในองค์ประกอบ HTML ต่อไปนี้

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

เมื่อสร้างคอมโพเนนต์ คุณจะกำหนดว่าจะใช้คอนเทนเนอร์ใดโดยแอตทริบิวต์รหัสของคอมโพเนนต์ ดังที่คุณจะเห็นในตัวอย่างภายหลัง

ขั้นตอนที่ 2: โหลดไลบรารี

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: ให้สิทธิ์ผู้ใช้

API ฝังจะจัดการขั้นตอนการให้สิทธิ์เกือบทั้งหมดให้คุณโดยมอบคอมโพเนนต์การลงชื่อเข้าใช้แบบคลิกเดียวที่ใช้ขั้นตอน OAuth 2.0 ที่คุ้นเคย คุณจะต้องส่งข้อมูลอ้างอิงคอนเทนเนอร์และรหัสไคลเอ็นต์เพื่อให้ปุ่มนี้ทำงานบนหน้าเว็บ

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

การดำเนินการนี้จะสร้างปุ่มภายในองค์ประกอบที่มีรหัส "auth-button" ซึ่งจัดการขั้นตอนการให้สิทธิ์ให้คุณ

ขั้นตอนที่ 4: สร้างตัวเลือกข้อมูลพร็อพเพอร์ตี้

คุณสามารถใช้คอมโพเนนต์ตัวเลือกมุมมองเพื่อดูรหัสของข้อมูลพร็อพเพอร์ตี้หนึ่งๆ เพื่อให้เรียกใช้รายงานได้

หากต้องการสร้างตัวเลือกข้อมูลพร็อพเพอร์ตี้ คุณแค่ต้องใช้การอ้างอิงคอนเทนเนอร์ที่คุณสร้างในขั้นตอนที่ 1

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

ซึ่งจะเป็นการสร้างคอมโพเนนต์ตัวเลือกมุมมอง แต่ยังไม่แสดงผลในหน้าเว็บ ในการทำเช่นนั้น คุณต้องเรียก execute() ซึ่งดำเนินการในขั้นตอนที่ 6

ขั้นตอนที่ 5: สร้างแผนภูมิเส้นบอกเวลา

API ที่ฝังมีคอมโพเนนต์ของแผนภูมิที่เป็นทั้ง Google แผนภูมิและออบเจ็กต์รายงาน ซึ่งจะช่วยลดความซับซ้อนของกระบวนการแสดงข้อมูลได้อย่างมาก เนื่องจากออบเจ็กต์แผนภูมิจะเรียกใช้รายงานในเบื้องหลังและอัปเดตผลลัพธ์โดยอัตโนมัติ

หากต้องการสร้างคอมโพเนนต์แผนภูมิ คุณจะต้องระบุพารามิเตอร์การค้นหาของ API และตัวเลือกแผนภูมิ ภายในตัวเลือกแผนภูมิจะเป็นการอ้างอิงไปยังรหัสของคอนเทนเนอร์ที่คุณสร้างในขั้นตอนที่ 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'
  }
});

การทำเช่นนี้จะเป็นการสร้างคอมโพเนนต์แผนภูมิเช่นเดียวกับตัวเลือกมุมมอง แต่หากต้องการแสดงผลไปยังหน้าเว็บ คุณจะต้องเรียกใช้ execute() ซึ่งจะมีการอธิบายในขั้นตอนถัดไป

ขั้นตอนที่ 6: เชื่อมต่อองค์ประกอบเข้าด้วยกัน

คอมโพเนนต์ 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

ขั้นตอนถัดไป

คู่มือนี้จะแนะนำวิธีสร้างการแสดงภาพแบบพื้นฐานด้วย Alternative API หากต้องการข้อมูลเพิ่มเติม โปรดดูเอกสารอ้างอิง API เพื่อทำความเข้าใจสิ่งที่เป็นไปได้โดยละเอียด