סימוכין לרכיבים מובנים

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

אימות

gapi.analytics.auth

רכיב האימות הוא סינגלטון שניתן להשתמש בו כדי לתת הרשאה למשתמש.

שיטות
authorize(options:Object)	החזרות:  gapi.analytics.auth מוצג לחצן כניסה של Google Analytics בתוך מאגר התגים שצוין, שמאפשר למשתמש להיכנס באמצעות חשבון Google שלו.
isAuthorized()	החזרות:  boolean הפונקציה מחזירה את הערך true אם המשתמש אישר בהצלחה, false אחרת.
signOut()	החזרות:  gapi.analytics.auth מוציא את המשתמש הנוכחי מהחשבון. הפונקציה גם מפעילה את האירוע signOut.
getAuthResponse()	החזרות:  Object הפונקציה מקבלת את נתוני האימות שהוחזרו על ידי בקשת ההרשאה המקורית. האובייקט שמוחזר כולל את אסימון הגישה, שבדרך כלל אפשר להשתמש בו כדי לשלוח בקשות מאומתות באופן ידני.
getUserProfile()	החזרות:  Object קבלת פרטי פרופיל בסיסיים על המשתמש שמחובר עכשיו. המידע הזה כולל את שם המשתמש, כתובת האימייל ותמונת הפרופיל הציבורית שלו (אם היא מוגדרת).

שיטות שעברו בירושה
on
once
off

אפשרויות
clientId	סוג:  string מזהה הלקוח של הפרויקט שלך ב מסוף המפתחים.
container	סוג:  string|HTMLElement המזהה של רכיב HTML ב-DOM שיארח את לחצן הכניסה. תוכלו גם להעביר הפניה לרכיב עצמו.
userInfoLabel	סוג:  string הטקסט שיוצג לפני כתובת האימייל של המשתמש המחובר. ברירת המחדל היא 'You are logged in as: '.
scopes	סוג:  Array רשימה של היקפי ההרשאות של Google API שהאפליקציה שלך מבקשת. כדי לראות את כל היקפי ההרשאות הזמינים, אפשר לעיין ב-OAuth 2.0 Playground. לגבי היקפי ההרשאות של Google Analytics API, אפשר לעיין במדריכים למפתחים לגבי מקורות המידע הגדרות ודיווח.
overwriteDefaultScopes	סוג:  boolean הערך מציין אם האפשרות scopes מחליפה את ההיקפים של הטמעת ה-API שמוגדרים כברירת מחדל או מוסיפה להם. ציון של false (ברירת המחדל) יוסיף להיקפים המוגדרים כברירת מחדל, וציון true יחליף אותם בהיקפים שצוינו באפשרות scopes. ערך ברירת המחדל של ההיקפים הוא:['https://www.googleapis.com/auth/analytics.readonly']. הערה: אימות באמצעות embed API מחייב גישה לפרופיל הבסיסי של המשתמש. לא ניתן להחליף את ההיקפים האלה.
serverAuth.access_token	סוג:  string אם כבר יש לכם אסימון גישה תקף, אפשר להעביר אותו ישירות לשיטת ההרשאה והמשתמש לא יתבקש להעניק הרשאה. לפרטים על אופן האחזור של אסימון גישה, ניתן לעיין במסמכי התיעוד בנושא OAuth 2.0.

אירועים
signIn	ארגומנטים: ללא מופעל כשהמשתמש נכנס בהצלחה.
signOut	ארגומנטים: ללא מופעל כשהמשתמש יצא מהחשבון בהצלחה.
needsAuthorization	ארגומנטים: ללא כשמפעילים את השיטה gapi.analytics.auth.authorize, מתבצעת בדיקה ראשונית כדי לראות אם המשתמש מחובר כרגע. אם המשתמש לא מחובר, האירוע הזה יופעל כדי לציין שנדרשת הרשאה נוספת.
error	ארגומנטים:  response מופעל כשמתרחשת שגיאה בתהליך האימות. אם ברצונך לקבל את הודעת השגיאה מאובייקט התשובה, היא תהיה בכתובת response.error.message.

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

דוגמה

// Standard client-side authorization.

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

gapi.analytics.auth.on('signIn', function() {
  console.log(gapi.analytics.auth.getUserProfile());
});

// Authorization using an access token obtained server-side.
// You do not need to register an event handler because
// authorization happens immediately.

gapi.analytics.auth.authorize({
  serverAuth: {
    access_token: 'XXXXXX'
  }
});

הערה: ההרשאה מתבצעת באופן מיידי כשמשתמשים ב-serverAuth.access_token, כך שאין צורך לרשום handler של אירועים.

חשוב: כשמשתמשים ב- serverAuth.access_token, באחריותכם לוודא שהאסימון תקף ושלא פג תוקפו. לפרטים על הרענון של אסימון גישה שפג תוקפו, אפשר לעיין במסמכי התיעוד של OAuth 2.0.

נתונים

gapi.analytics.report.Data

יצרן
Data(options:Object)	רכיב הנתונים מאפשר להריץ שאילתות על Core Reporting API של Google Analytics ולקבל את התוצאות.

אפשרויות
query	סוג:  Object אובייקט שמכיל פרמטרים של שאילתות מ- Core Reporting API. ערכי ברירת המחדל הבאים משמשים בנוסף לברירות המחדל הרגילות שה-API מספק: { 'start-date': '7daysAgo', 'end-date': 'yesterday }

שיטות שעברו בירושה
get
set
execute
on
once
off
emit

אירועים
success	ארגומנטים:  response מופעל כשהשאילתה הושלמה.
error	ארגומנטים:  response מופעל כשמתרחשת שגיאה במהלך תהליך השאילתה. אם ברצונך לקבל את הודעת השגיאה מאובייקט התשובה, היא תהיה בכתובת response.error.message.

דוגמה

var report = new gapi.analytics.report.Data({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:city'
  }
});

report.on('success', function(response) {
  console.log(response);
});

report.execute();

DataChart

gapi.analytics.googleCharts.DataChart

יצרן
DataChart(options:Object)	DataChart כולל תרשים רגיל של Google ורכיב נתונים, כדי שתוכלו ליצור בקלות תצוגה חזותית משאילתה בלי לחבר אותה יחד בעצמכם.

אפשרויות
query	סוג:  Object עיינו באפשרות השאילתה לגבי רכיב הנתונים.
chart	סוג:  Object בהמשך מופיעים פרטים על אפשרויות תרשים ספציפיות.
chart.container	סוג:  string|HTMLElement המזהה של רכיב HTML ב-DOM שיארח את DataChart. תוכלו גם להעביר הפניה לרכיב עצמו.
chart.type	סוג:  string סוג התרשים. האפשרויות האפשריות הן: LINE, COLUMN, BAR, TABLE ו-GEO.
chart.options	סוג:  Object כל האפשרויות שניתן להעביר לאובייקט התואם של Google Chart.

שיטות שעברו בירושה
get
set
execute
on
once
off
emit

אירועים
success	ארגומנטים:  result מופעל כשהשאילתה הושלמה בהצלחה והתרשים מעובד במלואו. result.chart – המופע של Google Chart. result.data – התגובה לדוח בפורמט פרמטר נתונים. result.dataTable – המופע של DataTable שנוצר מהאובייקט result.data. result.response – האובייקט הגולמי של תגובת ה-API.
error	ארגומנטים:  response מופעל כשמתרחשת שגיאה במהלך השאילתה או תהליך הרינדור. אם ברצונך לקבל את הודעת השגיאה מאובייקט התשובה, היא תהיה בכתובת response.error.message.

דוגמה

var chart = new gapi.analytics.googleCharts.DataChart({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:date'
  },
  chart: {
    type: 'LINE',
    container: 'line-chart',
    options: {
      title: 'Sessions over the past week.',
      fontSize: 12
    }
  }
});
chart.on('success', function(response) {
  // response.chart : the Google Chart instance.
  // response.data : the Google Chart data object.
});

chart.execute();

ViewSelector

gapi.analytics.ViewSelector

יצרן
ViewSelector(options:Object)	הרכיב ViewSelector מאפשר לבחור את החשבון, הנכס והתצוגה באמצעות תפריטים נפתחים.

אפשרויות
container	סוג:  string|HTMLElement המזהה של רכיב HTML ב-DOM שיארח את ה-ViewSelector. תוכלו גם להעביר הפניה לרכיב עצמו.

שיטות שעברו בירושה
get
set
execute
on
once
off
emit

מאפייני מכונה
ids	סוג:  string מזהה הטבלה הייחודי של הטופס ga:XXXX, כאשר XXXX הוא מזהה התצוגה המפורטת (הפרופיל) ב-Analytics.

אירועים
change	ארגומנטים:  ids מופעל בכל פעם שהמשתמש בוחר תצוגה חדשה מתוך התפריטים הנפתחים. הוא מופעל גם כשמופע ViewSelector עובר עיבוד בפעם הראשונה ומוצגת תצוגת ברירת המחדל.

דוגמה

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

viewSelector.on('change', function(ids) {
  console.log(ids);
});

viewSelector.execute();

שיטות של רכיבים משותפים

שיטות
set(options)	החזרות: this מגדיר או מעדכן את אפשרויות התצורה של הרכיב (ניתן לעשות זאת גם בזמן היצירה ב-constructor).
get()	החזרות: Object מחזירה את אפשרויות התצורה הנוכחיות של רכיב.
execute()	החזרות: this מפעיל את הפעולה הראשית של הרכיב. בדרך כלל מתבצע עיבוד של משהו בדף או הרצת דוח (או שניהם).
on(event, handler)	החזרות: this רושם פונקציה שתופעל כשהרכיב פולט את האירוע שצוין.
once(event, handler)	החזרות: this רושם פונקציה שתופעל רק באירוע הבא של האירוע שצוין. לאחר שה-handler מופעל ברגע שהוא מבטל את הרישום של עצמו באופן אוטומטי.
off(opt_event, opt_handler)	החזרות: undefined הסרה של גורם מטפל באירועים מרכיב. אם לא מועבר אף handler, מתבצעת הסרה של כל ה-handlers של האירוע שהועבר. אם לא עבר אירוע, כל ה-handlers יוסרו לכל האירועים.
emit(event, ...opt_args)	החזרות: undefined משדר אירוע. אפשר לציין את הארגומנטים שיועברו לכל רכיבי handler רשומים.

set

מגדיר או מעדכן את אפשרויות התצורה של הרכיב (ניתן לעשות זאת גם בזמן היצירה ב-constructor).

Usage

component.set(options);

פרמטרים

שם	סוג	תיאור
options	Object	אפשרויות התצורה של הרכיב הזה. האפשרויות שהועברו ימוזגו עם אפשרויות קיימות.

החזרות

this – מופע הרכיב.

---

get

מחזירה את אפשרויות התצורה הנוכחיות של רכיב.

החזרות

Object – אפשרויות ההגדרה הנוכחיות של הרכיב.

---

execute()

מפעיל את הפעולה הראשית של הרכיב. בדרך כלל מתבצע עיבוד של משהו בדף או הרצת דוח (או שניהם).

החזרות

this – מופע הרכיב.

---

on(event, handler)

רושם פונקציה שתופעל כשהרכיב פולט את האירוע שצוין.

פרמטרים

שם	סוג	תיאור
event	string	שם האירוע.
handler	Function	הפונקציה שתופעל כשהאירוע מתרחש. (כדי לקבל את פרטי הפרמטרים, אפשר לעיין בהפניות לאירועים נפרדים.)

החזרות

this – מופע הרכיב.

---

once(event, handler)

רושם פונקציה שתופעל רק באירוע הבא של האירוע שצוין. לאחר שה-handler מופעל ברגע שהוא מבטל את הרישום של עצמו באופן אוטומטי.

פרמטרים

שם	סוג	תיאור
event	string	שם האירוע.
handler	Function	הפונקציה שתופעל כשהאירוע מתרחש. (כדי לקבל את פרטי הפרמטרים, אפשר לעיין בהפניות לאירועים נפרדים.)

החזרות

this – מופע הרכיב.

---

off(opt_event, opt_handler)

הסרה של גורם מטפל באירועים מרכיב. אם לא מועבר אף handler, מתבצעת הסרה של כל ה-handlers של האירוע שהועבר. אם לא עבר אירוע, כל ה-handlers יוסרו לכל האירועים.

פרמטרים

שם	סוג	תיאור
opt_event	string	שם האירוע. אם לא יוגדר אירוע, כל הגורמים המטפלים בכל האירועים יוסרו. אופציונלי.
opt_handler	Function	הפניה ל-handler של הפונקציה שיש להסיר. אם לא מעבירים פונקציה, כל רכיבי ה-handler יוסרו. אופציונלי.

החזרות

undefined

---

emit(event, ...opt_args)

משדר אירוע. אפשר לציין את הארגומנטים שיועברו לכל רכיבי handler רשומים.

פרמטרים

שם	סוג	תיאור
event	string	שם האירוע.
...opt_args	*	ארגומנטים אופציונליים שיועברו לכל מטפלים רשומים באירועים.

החזרות

undefined