תחילת העבודה

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

רוב הרכיבים של ממשק ה-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.

השלבים הבאים

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