שיתוף נתונים מגוגל אנליטיקס – המדריך המלא ל-superProxy

אם הייתם יכולים להוציא בקלות את נתונים מגוגל אנליטיקס לאתר או לאפליקציה שלכם – מה הייתם עושים איתם? למשל לשתף משתמשים במה שחם ממש עכשיו או ליצור וויג’טים מגניבים או מיני דשבורדים ב-CRM.

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

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

דוגמא לשיתוף נתונים ניתן לראות כאן בבלוג עם הוויג’ט ה”גולשים באתר” שבניתי. זה נמצא בסיידבר במידה ואתם מסתכלים ממחשב נייח או בתחתית העמוד אם אתם מסתכלים ממובייל. ליתר ביטחון במידה ואסיר אותו בעתיד הנה צילום מסך שלו:

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

אמאלה! superProxy

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

• התחברות ל-API של אנליטיקס ושליפת מידע
• אגירה וריענון המידע באופן תדיר
• הגשת המידע לדפדפן
• ולבסוף צריך להציג את המידע

החדשות הטובות הן שאת החלק המפחיד באמת superProxy פותרת לנו בכך שהיא סוגרת בשבילינו את שלושת השלבים הראשונים. התוכנה בסופו של דבר מאכסנת בשרת את הנתונים מהשאילתה שהגדרתם לה והיא מחכה שיבקשו אותם ממנה. ברגע שהנתונים אצלינו אנחנו (או יותר נכון המפתחים שלנו) יכולים לייצר מהם מה שתבקשו.

עוד 2 פיצ’רים מעניינים ש-superProxy תומכת בהם:
1) ייצוא פלט בפורמטים שונים, כולל פורמט DataTable של ספריית הויזואליזציה של גוגל.
2) חיסכון בבקשות ל-API של גוגל אנליטיקס: במידה והתוכנה לא מקבלת בקשה להגשת מידע לאחר זמן מה היא עוצרת את ריענון המידע מאנליטיקס באופן אוטומטי.

superProxy והשירות מאחורי הקלעים

superProxy היא תוכנה וובית עם לא מעט מאחורי הקלעים שנכתב ב-Python. היא מופעלת דרך הפלטפורמה של Google App Engine ומשתמשת בתשתית של Google Cloud. במילים פחות גיקיות, כל הפיתרון הזה מבוסס ענן שלא מצריך מכם תפעול שוטף של תשתיות או קוד תוכנה. התשתית של Google Cloud חינמית עד גבול מסויים ובדומה לשירותי הענן של המתחרה אמזון, אתם משלמים פר שימוש בתשתית ולא על התשתית עצמה שכבר נקנתה והותקנה עבורכם מראש. לאלו מכם שמתכוונים להשתמש בכלי הזה בסקיילים גדולים קחו בחשבון שתהיינה לכך עלויות.

הערות חשובות לפני שמתחילים במדריך

• המדריך מיועד למי שיש לו ידע בסיסי במחשבים. אם אתם מסתבכים עם התקנות או לא יודעים לפתוח קובץ zip רצוי להעזר במישהו שמתמצא.
• עשו את המדריך לאט ובסבלנות. קיראו את כל ההוראות ובידקו פעמיים כל שלב שאתם עושים.
• גוגל ידועים ביכולותיהם להחליף את ניראות הממשקים שלהם באופן תדיר. התמונות או הלינקים ששותפו כאן יכולים לא להיות רלוונטים מחר אבל העיקרון בדרך כלל נשאר זהה.
• רצוי לוודא מתחילת התהליך עד סופו כי אתם מבצעים אותו דרך חשבון גוגל אחד שאתם מחוברים אליו בדפדפן Chrome (לא במצב אנונימי). לאותו חשבון צריכה להיות גם הרשאת קריאת נתונים ל-view של גוגל אנליטיקס ממנו אתם רוצים להוציא מידע.
• שימו לב שכל המדריך הזה נעשה ללא הרשמה פורמלית לשירותי הענן של Google Cloud – אני מניח שבשלב מסויים השירות יעצר ואתם תתבקשו להרשם ולשים כרטיס אשראי. יש גם Free Trail ל-60 יום.

אז פיתחו לעצמכם notepad כי יהיו לנו דברים שנצטרך לשמור בצד ובואו נתחיל:

שלב 1) פתיחת פרוייקט גוגל אנליטיקס ב-Google API Console

כדי לעשות קריאות ל-API של אנליטיקס יש לפתוח קודם לכן פרוייקט ב-Google API Console שיאפשר ל-superProxy לשלוף את הנתונים.

הכנסו לקונסלת ה-Cloud ופתחו פרוייקט חדש. יכול להיות שתצטרכו לעשות זאת דרך התפריט העליון Select a Project -> Create a Project

תנו לפרוייקט שם כמו לדוגמא השם הסביר “superProxy”.
עבור כל פרוייקט גוגל מנפיקים מזהה (ID). למי שחפץ במזהה אחר קיימת אפשרות לערוך את ה-ID באמצעות לחיצה על Edit.
שימרו את ה-ID ב-notepad שפתחתם.
במידה ופיספסתם ניתן תמיד לראות את ה-ID בתפריט העליון Create a Project.
*יכול להיות שתראו חלון קצת שונה בכל אופן 2 השדות שאני מדבר עליהם הם החשובים.

שלב 2) בחירת API והגדרת Credentials

מרשימת ה-APIs שנפתחה לכם (אם במקרה לא נפתחה, פיתחו את התפריט הראשי מצד שמאל וביחרו ב-API Manager) ביחרו את ה-API של Analytics ובחלון הבא שיפתח לכם לחצו על Enable.

כעת גשו בלשונית שמצד שמאל ל-Credentials. ביחרו ב-OAuth consent screen והזינו שם לפרוייקט. גם כאן השם “superProxy” תופס. כל השאר לא חשוב.

כעת אני מניח שהוחזרתם ללשונית Credentials (אם לא, פשוט גשו לשם). לחצו על Create Credentials כדי ליצור תעודה חדשה. ביחרו בסוג OAuth client ID.

ב-Application type ביחרו Web application. וב-Authorized redirect URIs הזינו את הערך הבא כשהחלק המודגש הוא ה-ID של הפרוייקט שלכם:

https://project-id.appspot.com/admin/auth

לבסוף לחצו Create – שאר השדות לא חשובים לצרכים שלנו.

כעת נפתח בפניכם פופאפ עם 2 נתונים: client ID ו-client secret. שמרו אותם ב-notepad. שימרו היטב על הערכים האלה – מי שישים עליהם יד יוכל לגשת לנתונים שלכם באנליטיקס דרך ה-API.

אם עשיתם עד כה את השלבים כמו שצריך צריך להיות לכם ב-notepad שלושה ערכים:

• ID של הפרוייקט
• Client ID
• Client Secret

שלב 3) הורדות והתקנות

כעת יש להוריד לא פחות מ-3 דברים:

• Python 2.7 – *לא לנסות להוריד את הגירסה החדשה יותר
• Google App Engine SDK for Python בהתאם למערכת ההפעלה שלכם. הדבר יתקין גם תוכנה בשם Google App Engine Launcher (להלן נתייחס להתקנה זו בשם זה).
• קוד התוכנה של superProxy מ-Git Hub, חפשו את הכפתור Download Zip בצד ימין.

התקינו את Python 2.7, העזרו בסבלנות עד שההתקנה תסתיים.
כעת התקינו את Google App Engine והמתינו בסבלנות לסיום התקנה זו גם כן.
כעת תעשו Extract לקובץ zip של הפרוייקט של superProxy שירד מ-Git Hub.

אם הגעתם עד לכאן אתם ממש אלופים
עכשיו צריך ללכלך קצת את הידיים 🙂

שלב 4) הגדרות קבצי superProxy

בתיקיית הפרוייקט שזה עתה פתחתם אתרו את הקובץ app.yaml שנמצא בתקיית src ופתחו אותו עם עורך טקסט נורמלי – אני ממליץ על ++notepad – שחס וחלילה לא תעלו בדעתכם לפתוח אותו באיזה תמלילן מצחיק.
בשורה הראשונה הזינו את ה-ID של הפרוייקט שלכם. שימרו וסיגרו.

כעת נעבור לקובץ config.py. שנמצא באותה תיקיה. בקובץ הזה יש לא מעט דברים קריטים לעשות אז תהיו בפוקוס:
– בשורה 36 השלימו את ה-Client ID.
– בשורה 37 השלימו את ה-Client Secret.
– בשורה 42 רישמו https://project-id.appspot.com כשהחלק המודגש הוא ה-ID של הפרוייקט.
– בשורה 47 שימו ערך רנדומלי של תווים באנגלית ומספרים (כן, בקשה קצת מוזרה – פשוט תחרבשו משהו).
שימרו וסיגרו את הקובץ.

הקובץ co.py להרפתקנים שביניכם. הקובץ נמצא בנתיב \src\controllers\util\ ומאפשר לכם לקבוע פורמט ברירת מחדל שונה מ-json. תוכלו לשנות זאת בשדה DEFAULT_FORMAT שמקבל את הערכים: json, csv, data-table, data-table-response, tsv.

שלב 5) העלאת התוכנה ל-App Engine

נפתח את Google App Engine Launcher (ככל הנראה מצוי על שולחן העבודה) ונעשה את הפעולות הבאות:

בתפריט File -> Add Existing Application נלחץ על Browse ונבחר את תיקיית ה-src שבתיקיה שפתחנו (לא להתבלבל עם התיקיה עצמה).
בחלון הראשי לחצו על הפרוייקט שהרגע הוספתם ולחצו על הכפתור הגדול Deploy.

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

*אם אינכם מקבלים את חלון האוטנטיקציה וקיבלתם שגיאה “You do not have permission to modify this app” נסו לעשות Control -> Clear Deployment Credential ואז נסו ללחוץ שוב Deploy.

במידה והפעולה הצליחה אתם תקבלו הודעה בדפדפן:
The authentication flow has completed.

כעת כנסו בדפדפן ל-https://project-id.appspot.com/admin כשהחלק המודגש הוא ה-ID של הפרוייקט.
לחצו על Authorize Access ושוב בצעו אוטנטיקציה לחשבון שלכם.
בקבלתכם הודעת Success לחצו על Continue.

ברכותיי, הצלחתם להתקין את superProxy בהצלחה!
כעת נוכל להפעיל אותה 🙂

שלב 6) יצירת שאילתה בממשק אדמין

אז אתם בממשק הראשי של התוכנה אליו תמיד תוכלו להגיע בכתובת https://project-id.appspot.com/admin כשהחלק המודגש הוא ה-ID של הפרוייקט שלכם).
על מנת ליצור שאילתה חדשה יש ללחוץ על Create Query.

בחלון שנפתח לכם עליכם לערוך 3 שדות:

1. שם השאילתה – שם שיהיה לכם נח לזהות את השאילתה באדמין.
2. Interval – באיזה תדירות הנתונים יתרעננו, הערך המוזן צריך להיות בשניות כשיום יוצא 86400. לנתוני Real Time אני שם כ-500 שניות וגם זה מוציא שגיאות מדי פעם.
3. השאילתה עצמה שעליה נרחיב ממש עכשיו

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

Query Explorer עובד מול ה-Core Reporting API כך שהוא לא תומך במימדי Real Time. שאליתה ל-Real Time Reporting API תצטרכו לבנות בעצמכם ללא סיוע של הכלי. תוכלו להעזר בסימוכין ל-Real Time API.

לאחר שנריץ את השאילתה ב-Query Explorer ונראה שהיא מחזירה את הנתונים הרצויים נוכל להוציא אותה ולהציב אותה בשדה השלישי. השאילתה תופיע במורד העמוד תחת הכותרת “API Query URI”.

רצוי לעשות בדיקה שהשאילתה לגוגל אנליטיקס עובדת ע”י לחיצה על Test Query. התשובה מה-API של גוגל תופיעה מתחת לכפתור. בתמונה ניתן לראות כיצד נראת תשובה תקינה של מה-API. היה וקיבלתם שגיאה אתם תראו לא מעט את המילה error עם פירוט קל אודות השגיאה שאמור לסייע לכם לפתור את הבעיה.

אם הכל תקין נשמור את השאילתה על ידי לחיצה על Save & Schedule Query

שלב 7) סוף הדרך: מסך השאילתה

לאחר שמירת השאילתה אתם מובלים למסך שנותן לכם איפורמציה על השאילתה. ניתן להגיע למסך הזה גם ממסך האדמין ע”י לחיצה על כפתור Manage שזמין עבור כל שאילתה ששמרתם.

Public Request Endpoint

שורת ה-URL מציגה כתובת שמחזירה את תוצאת השאילתה האחרונה שמאוחסנת ב-superProxy. שילחו את הכתובת הזו למתכנתים שלכם והם מה לעשות – יש גם קצת הנחיות למפתחים בהמשך. בכל אופן תנו לזה דקה-שתיים להתעדכן, בדקות הראשונות התוכנה מחזירה את ההודעה The query is not yet available.

שורה ה-Formats מכילה גם היא כתובות URL רק שאלו מכילות פרמטר נוסף שמשנה את הפלט לפורמט אחר מזה שהוגדר כברירת מחדל אם לא שיניתם כלום בקובץ co.py אז ברירת המחדל היא json.

Scheduling

התפריט ממוקם מתחת ל-Public Request Endpoint. הוא יציג לכם האם השאילתה פעילה ומתי היה הריענון האחרון. שימו לב ש-Scheduling זה פיצ’ר שניתן גם שלא להשתמש בו במידה ואין לכם צורך בריענון. ניתן לעצור אותו עם הכפתור Pause (למי ששם לב, במסך השאילתה היה גם ניתן לשמור את השאילתה ללא Schedule).

Response Info

התפריט ממוקם מתחת ל-Scheduling. בו נוכל לקבל פירוט קל אודות הבקשות מהתוכנה: כמה בקשות נעשו עד כה, מתי הייתה הבקשה האחרונה והפלט האחרון שיצא מהתוכנה.

דמו

הנתונים בתרשימים שלפניכם הגיעו ישירות מ-superProxy עם טעינת העמוד הזה. לצורך יצירת הגרפים השתמשתי ב-Google Visualization ספריית הויזואליזציה של גוגל:

לסיכום

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

לסיום, עוד שני שלבים שיכולים לחסוך למפתחים שלכם שעתיים ביציאה:

למפתחים: שימוש ב-JSONP

superPorxy עובד ב-REST. לכן שליפת נתונים ישירות לדפדפן צריכה להעשות באמצעות JSONP כל עוד אנחנו לא משתמשים בספריה חכמה שעושה זאת בשבילנו כמו ספריית הויזואליזציה של גוגל.

superProxy תומכת ב-JSONP וזאת הדרך ליישם את הבקשה באמצעות jQuery:

*השלימו את ה-ID של הפרוייקט ואת הפרמטר ID מה-URL שקיבלתם מ-superProxy

jQuery.ajax({
	url: "http://PROJECT-ID.appspot.com/query",
	dataType: "jsonp",
	data: {id: 'ID PARAM FROM URL QUERY'},
	jsonp: "callback",
	success: function(data){
		// superProxy data is ready
	}
});

למפתחים: בעיות עם פורמט DataTable

במהלך העבודה על הדמו, הופתעתי לגלות שה-superProxy לא תמיד מצליח להחזיר תשובה עבור הפורמט dataTable (פורמט המתאים לעבודה עם Google Visualization). התוכנה פשוט מחזירה סוג של שגיאה לא ממש שימושית: “uncaught application failure”. אני לא בטוח מה קורה שם ומכאן אני רק יכול להחזיק אצבעות שלכם זה לא יקרה. בכל אופן פתחתי על זה Issue ב-Git Hub בתקווה שיום אחד יתקנו את זה.

לצורך יצירת טבלה ב-Google Visualization אני משתמש במתודה drawChart. מתודה זו יודעת לקבל דאטה בפורמט dataTable עם פרמטרים ומסרטטת טבלה על-פיהם. כאמור פורמט ה-dataTable מסרב לחזור כמו שצריך מ-superProxy אז מה שנעשה זה נחזיר את הפלט בפורמט JSON נהפוך אותו לפורמט הרצוי dataTable ובסוף נגיש ל-drawChart את הפורמט הנדרש. למטה תוכלו למצוא את הקוד וכאן אני אסביר על כל שלב:

1. הצהרה על מערך דו מימדי ויצירה ידנית של האיבר הראשון (העמודות).
2. לולאה שמכניסה לאיבר השני (השורות) את הדאטה שחוזר מ-superProxy. לפני שאני עושה את זה אני ממיר עמודות מספריות שחוזרות כמחרוזת מה-API של גוגל אנליטיקס לערך מספרי.
   *הרשתי לעצמי לממש את זה קצת מגעיל בגלל שהתוכנית פשוטה. למשהו יותר מורכב הייתי משתמש באינדקס columnHeaders כדי לזהות את סוג העמודה שחוזרת מה-API.
3. המרה המערך הדו מיימדי ל-dataTable של Visualizations בסיוע המתודה arrayToDataTable.

*הקוד הבא מתייחס למה שקורה אחרי ה-success של ה-JSON כך ש-data זמין לנו. אם לא הייתה את הבעיה ב-superProxy ודאי שזה לא משהו שהיינו צריכים לעשות, ספריית הויזואליזציה הייתה סוגרת לנו את כל הפינות האלה בשורה אחת.

// create the 2 dimension array + set columns
var arr = [[
	{label: 'Page', type: 'string'},
	{label: 'Pageviews', type: 'number'}
]];

// convert value types + set rows
for (var i=0 ; i