הקצאת חשבונות בפיקוח משתמש - מדריך למפתחי API

מסמך זה מסביר מושגים חשובים לגבי השימוש בממשק ה-API להקצאת משתמשים ליצירת חשבונות Google Analytics חדשים.

מבוא

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

לפני שתתחיל

הגישה לכל ממשקי ה-API של Google Analytics מתבצעת באופן דומה. לפני שתתחיל עם ממשק ה-API להקצאת משתמשים, עליך:

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

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

  1. רשום את האפליקציה שלך במסוף Google API.
  2. הרשאה ליצור חשבון Google Analytics חדש.
  3. יוצרים אובייקט שירות של Analytics.

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

סקירה

כשיוצרים חשבונות Google Analytics באמצעות API להקצאת משתמשים, צריך לקחת בחשבון שני תהליכי עבודה נפרדים:

  • תהליך טכני: התהליך מקצה לקצה להקצאה פרוגרמטית של חשבון Google Analytics למשתמש.
  • זרימת משתמש: שיקולי ההטמעה שעליך לבצע בתהליך יצירת החשבון מנקודת המבט של המשתמש.

במסמך הזה מתוארים השלבים הכלליים והדרישות בכל תהליך.

תהליך טכני

השלבים הכלליים לשימוש בממשק ה-API להקצאת משתמשים כדי ליצור חשבון חדש ולשלב אותו עם Google Analytics הם:

  1. הצגת בקשה למשתמש לאמת ולאשר את האפליקציה/השירות באמצעות OAuth 2.0.
  2. אפשר ליצור כרטיס חשבון באמצעות ה-API להקצאת משתמשים.
  3. מפנים את המשתמש לאישור התנאים וההגבלות של Google Analytics ולטיפול בתגובה.
  4. (אופציונלי) מגדירים את החשבון ואת הזדמנויות השילוב.

אם כל השלבים האלה יסתיימו בהצלחה, ייווצר למשתמש חשבון Google Analytics ומזהה החשבון, מזהה הנכס ומזהה התצוגה המפורטת (פרופיל) יהיו זמינים לחשבון החדש.

בכל שלב בהמשך יש דרישות להשלמת השלב, תוצאות של השלב ותיאור תהליך הטכני של השלב.

‫1. אימות והרשאה

כל משתמש צריך לאשר את האפליקציה ולהעניק לה את היכולת להקצות חשבון Google Analytics בשמו. מומלץ לבצע את השלב הזה בתהליך ההפעלה של שרת האינטרנט OAuth 2.0.

מה צריך כדי לבצע את השלב הזה

התוצאה של השלב הזה

בסיום התהליך של OAuth 2.0, המשתמש יאשר לאפליקציה שלכם להקצות חשבון בשמו. לאחר מכן יוקצה לו אסימון גישה.

הערה לגבי אסימונים והיקפים:

  • אם בכוונתך לשלוח בקשות נוספות להגדרת החשבון של המשתמש או לנתוני דיווח אחרי יצירת החשבון, אפשר גם לאשר היקפים נוספים במהלך השלב הזה. לדוגמה, ההיקפים readonly או edit.
  • לאסימוני גישה יש משך חיים מוגבל. אם האפליקציה שלך זקוקה לגישה אל Google Analytics API לאחר משך החיים של אסימון גישה יחיד, אפשר גם לבקש אסימון רענון על ידי הגדרת access_type=offline. צריך לשמור אסימון רענון באחסון מאובטח לטווח ארוך לכל משתמש, כי הוא מאפשר לאפליקציה לקבל אסימוני גישה חדשים. לפרטים נוספים, אפשר לעיין בגישה אופליין.

התהליך הטכני של השלב הזה

אתם צריכים לקבל אסימון גישה למשתמש. בהתאם לתהליך שמתואר בשרת האינטרנט OAuth 2.0, שולחים את המשתמש לשירות של חשבונות Google, ולאחר מכן מטפלים בתגובה כשהמשתמש מופנה חזרה לשירות שלכם אחרי השלמת תהליך האימות.

עליך למלא את כתובת ה-URL של OAuth 2.0 שאליה המשתמש יוכל להיכנס

כשהמשתמש לוחץ על לחצן או על קישור כדי להתחיל או כדי ליצור חשבון, הקישור צריך להצביע על התחלת התהליך של OAuth 2.0, כדי לבקש מהמשתמש להעניק הרשאות להקצאת ההרשאות. למשל:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
טיפול בתגובה משירות של חשבונות Google

אחרי שהמשתמש מחליט אם להעניק גישה לאפליקציה, הוא יופנה אוטומטית לכתובת redirect_uri שצוינה בכתובת ה-URL שיצרתם באמצעות פרמטר שאילתה שמכיל קוד הרשאה. אם המשתמש אישר את הבקשה, ניתן יהיה להשתמש בתגובה של קוד ההרשאה כדי להמיר את קוד ההרשאה לאסימון גישה, על ידי שליחת בקשת POST ל-Google Accounts API.

שמירת אסימון הרענון (אם רלוונטי)

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

2. יצירת כרטיס חשבון באמצעות API להקצאת הרשאות

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

מה צריך כדי לבצע את השלב הזה

אסימון גישה של המשתמש המורשה, כפי שמתואר בקטע אימות והרשאה ובפרטי ההקצאה הבאים:

  • URI של הפניה אוטומטית
    • מגדיר לאן המשתמש יופנה אחרי דף התנאים וההגבלות (TOS) של Google Analytics. הוא יכול להיות שונה מה-URI של ההפניה האוטומטית שצוין בתהליך ההרשאה של OAuth 2.0.
    • הערך של הפרמטר Redirect URI חייב להתאים בדיוק לאחד מהערכים שרשומים ב-Google Developers Console (כולל סכימות http או https, אותיות רישיות וקטנות '/').
  • שדות בחשבון
    • חובה להוסיף לחשבון נכס name.
  • שדות של נכס אינטרנט
    • חובה לכלול את המאפיין name בנכס.
    • websiteUrl הוא חובה.
  • שדות פרופיל
    • נדרש מאפיין name לפרופיל.
    • אפשר גם לציין timezone. ברירת המחדל היא America/Los_Angeles.

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

פרטים נוספים על השדות האלה מופיעים בחומרי העזר של API עבור Accounts, Properties ו-Views (Profiles).

התוצאה של השלב הזה

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

התהליך הטכני של השלב הזה

באמצעות אסימון הגישה עבור המשתמש שהתקבל במהלך האימות וההרשאה, נשלחת בקשת HTTP POST ל-API להקצאת משתמשים.

בקשת API להקצאת משתמשים ליצירת כרטיס חשבון

לקבלת פרטים על אופן שליחת הבקשה, קראו את השיטה createAccountTicket בחומרי העזר של API להקצאת משתמשים.

תגובה מה-API להקצאת משתמשים

בקשה מוצלחת מחזירה תגובה של 200. גוף התגובה מכיל כרטיס חשבון, לטווח קצר. כרטיס החשבון כולל תעודה מזהה ופרטים של עץ החשבונות החדש.

לפרטים על התגובה, קראו את המאמר Account Ticket resource בחומר העזר בנושא הקצאת API.

גם תגובות לשגיאות צריכות להתבצע על ידי האפליקציה.

3. המשתמש מסכים לתנאים ולהגבלות של Google Analytics (תנאים והגבלות)

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

מה צריך כדי לבצע את השלב הזה

המזהה של כרטיס החשבון של המשתמש המורשה.

התוצאה של השלב הזה

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

התהליך הטכני של השלב הזה

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

עליך למלא את כתובת ה-URL של התנאים וההגבלות שבהם המשתמש יוכל לבקר

מפנים את המשתמש לדף התנאים וההגבלות וכוללים את מספר הכרטיס של החשבון כחלק מכתובת ה-URL:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
טיפול בתגובה לתנאים ולהגבלות

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

תגובות מוצלחות יחזירו נתונים על מבנה החשבון החדש שנוצר וגם על accountTicketId המקורי:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

לדוגמה, אם ה-handler של התנאים וההגבלות של האפליקציה הוא http://www.your-app.com/gaTOS, צריך להגדיר אותו בתור redirectUri בזמן יצירת כרטיסי החשבון. הגורם המטפל בתנאים ובהגבלות של האפליקציה שלכם אמור לצפות ולטפל בצורה נכונה בבקשות HTTP GET שמכילות את הפרמטרים accountId, webPropertyId, profileId ו-accountTicketId, במקרים שבהם הכרטיס של החשבון תקין והמשתמש אישר את התנאים וההגבלות.

תשובות לא מוצלחות יכללו את תגובת השגיאה:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

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

  • error=user_cancel - המשתמש לא אישר את התנאים וההגבלות.
  • error=max_accounts_reached - המשתמש הגיע למגבלה של חשבון Google Analytics.
  • error=backend_error - שגיאה כללית. השרת החזיר שגיאה שלא משתייכת לקטגוריות שלמעלה.

‫4. (אופציונלי) הזדמנויות לשילוב

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

תהליך העבודה של המשתמש

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

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

  1. יצירת חשבון Google Analytics
  2. צריך להשתמש בחשבון Google Analytics קיים. (הערה: התהליך הזה לא מופיע במסמך הזה. מידע נוסף על הגישה לנתוני התצורה של משתמש ב-Google Analytics מופיע ב-Management API.)

כשיוצרים חשבון Google Analytics חדש, יש מידע שחובה לשלוח עם הבקשה להקצאת ההרשאות, כמו שם החשבון, שם הנכס וכו'. בהתאם למידע על המשתמש ולתהליך המועדף שרוצים להציג, יש 3 אפשרויות עיקריות לביצוע תהליך המשתמש אחרי שהמשתמש לוחץ על 'יצירת חשבון':

לבקש את פרטי החשבון אחרי ההרשאה

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

  1. המשתמש מופנה אוטומטית לשירות חשבון Google לתהליך OAuth 2.0. אם למשתמש אין חשבון Google או שהוא לא מחובר, הוא יתבקש ליצור חשבון Google או להיכנס לחשבון.
  2. המשתמש מתבקש לאשר לאפליקציה 'יצירת חשבונות Google Analytics'.
  3. המשתמש מקבל את בקשת ההרשאה לאפליקציה.
  4. המשתמש מופנה אל ספק השירות. לתשומת ליבך: אם המשתמש דוחה את ההרשאה, הוא עדיין מופנה חזרה לספק השירות.
  5. מוצג למשתמש טופס לאיסוף פרטים על החשבון שברצונך ליצור (למשל, שם החשבון, שם הנכס, שם הפרופיל, אזור הזמן, כתובת האתר וכו')
  6. משתמש ממלא את הטופס ושולח אותו, ומופנה מחדש ל-Google/מוצגים בתנאים ובהגבלות של Google Analytics.
  7. המשתמש מקבל את התנאים וההגבלות.
  8. המשתמש מופנה לספק השירות ומוצגת לו הודעת הצלחה על כך שהוא יצר בהצלחה חשבון Google Analytics עם פרטים על החשבון ואופן הגישה אליו. לתשומת ליבך: גם אם המשתמש לא מאשר את התנאים וההגבלות, הוא עדיין יופנה בחזרה לספק השירות.

צריך לבקש את פרטי החשבון לפני קבלת ההרשאה

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

  1. באתר של ספק השירות מוצג למשתמש טופס שבאמצעותו אפשר לאסוף פרטים על החשבון שרוצים ליצור (למשל, שם החשבון, שם הנכס, שם הפרופיל, אזור הזמן, כתובת האתר).
  2. המשתמש ממלא את הטופס, לוחץ על לחצן השליחה ומופנה אוטומטית לשירות חשבון Google לתהליך OAuth 2.0. אם למשתמש אין חשבון Google או שהוא לא מחובר, הוא יתבקש ליצור חשבון Google או להיכנס.
  3. המשתמש מתבקש לאשר לאפליקציה 'יצירת חשבונות Google Analytics'.
  4. המשתמש מאשר את ההרשאות הנדרשות לאפליקציה.
  5. המשתמש מופנה אל ספק השירות.
  6. המשתמש מופנה מחדש אל Google/מוצגים התנאים וההגבלות של Google Analytics (התנאים וההגבלות).
  7. המשתמש מקבל את התנאים וההגבלות.
  8. המשתמש מופנה לספק השירות ומוצגת לו הודעת הצלחה על כך שהוא יצר בהצלחה חשבון Google Analytics עם פרטים על החשבון ואופן הגישה אליו.

מילוי מראש של פרטי החשבון או דילוג על טפסים

אם המידע על חשבון המשתמש כבר זמין (למשל, כתובת האתר, שם האתר, אזור הזמן וכו') אפשר לפשט עוד יותר את שתי האפשרויות שלמעלה:

  • מילוי מראש של הטופס ומתן הרשאה למשתמש לערוך אותו אם הוא רוצה
  • דילוג על שלב הטופס ויצירה אוטומטית של החשבון באמצעות הפרטים הקיימים.