ภาพรวม
เอกสารนี้จะแนะนำตัวอย่างวิธีใช้ API ที่ฝังอยู่ เมื่อเสร็จสิ้นแล้ว คุณจะมีแอปพลิเคชันที่มีลักษณะเช่นนี้
การสร้างหน้าแดชบอร์ดที่เรียบง่าย
คุณทำให้แอปพลิเคชันตัวอย่างทำงานบนเซิร์ฟเวอร์ได้โดยทำตาม 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 เพื่อทำความเข้าใจสิ่งที่เป็นไปได้โดยละเอียด