תחילת העבודה

סקירה

מסמך זה ינחה אותך בדוגמה מלאה של אופן השימוש ב-embed API. לאחר השלמת התהליך, תהיה לך אפליקציה שנראית כך.

צילום מסך של הדוגמה שכלולה במדריך הזה
צילום מסך של הדוגמה במדריך הזה.

יצירת מרכז בקרה פשוט

תוכלו להריץ את האפליקציה לדוגמה בשרת שלכם באמצעות שני שלבים פשוטים:

  1. יצירת מזהה לקוח חדש
  2. העתקה והדבקה של הקוד

אחרי שתפעילו את האפליקציה, בחלק הבא נסביר בפירוט איך כל החלקים משתלבים זה בזה.

יצירת מזהה לקוח חדש

ב-embed API מטפל כמעט בכל תהליך ההרשאה בכך שהוא מספק רכיב כניסה בלחיצה אחת שמשתמש בתהליך OAuth 2.0 המוכר. כדי שהלחצן הזה יפעל בדף שלכם, אתם זקוקים למזהה לקוח.

אם מעולם לא יצרתם מזהה לקוח, תוכלו לעשות זאת על ידי ביצוע ההוראות האלה.

כשעוברים על ההוראות, חשוב לא להתעלם משני השלבים הקריטיים האלה:

  • הפעלה של Analytics API
  • הגדרת המקורות הנכונים

המקורות קובעים באילו דומיינים מותר להשתמש בקוד הזה כדי לאשר משתמשים. כך אנשים אחרים לא יוכלו להעתיק את הקוד שלכם ולהריץ אותו באתר שלהם.

לדוגמה, אם האתר מתארח בדומיין example.com, חשוב להגדיר את המקור הבא עבור מזהה הלקוח http://example.com. אם רוצים לבדוק את הקוד באופן מקומי, צריך להוסיף גם את המקור של השרת המקומי, לדוגמה: http://localhost:8080.

העתק והדבק את הקוד

לאחר שתקבלו את מזהה הלקוח עם המקורות המתאימים, תוכלו ליצור את ההדגמה. פשוט מעתיקים ומדביקים את הקוד הבא בקובץ HTML בשרת שלכם, ומזינים את מזהה הלקוח במקום שבו מופיע הכיתוב: "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>

הדרכה מפורטת בנושא קוד

הקטע הזה מסביר בצורה מפורטת מה בדיוק קורה בקוד של האפליקציה לדוגמה. ברגע שתבינו איך זה עובד, תוכלו ליצור בעצמכם.

שלב 1: יוצרים את מאגרי התגים של הרכיבים

רוב הרכיבים של embed 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: יוצרים את תרשים ציר הזמן

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

השלבים הבאים

במדריך הזה נסביר איך ליצור תצוגה חזותית בסיסית באמצעות embed API. למידע נוסף, מומלץ לעיין בחומר העזר בנושא API כדי להבין בצורה מלאה מה אפשר לעשות.