הרשאת Tag Manager API

במסמך מתואר איך אפליקציה יכולה לקבל הרשאה לשליחת בקשות ל-Tag Manager API.

הרשאת בקשות

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

כל בקשה שהאפליקציה שולחת ל-Tag Manager API חייבת לכלול אסימון הרשאה. אסימון ההרשאה גם מזהה את האפליקציה שלכם ב-Google.

הסבר על פרוטוקולים של הרשאות

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

הרשאת בקשות עם פרוטוקול OAuth 2.0

כל הבקשות ל-Tag Manager API צריכות לקבל אישור ממשתמש מאומת.

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

  1. כשאתם יוצרים את האפליקציה, צריך לרשום אותה באמצעות Google API Console. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
  2. מפעילים את Tag Manager API ב-Google API Console. (אם ממשק ה-API לא מופיע ב-API Console, אפשר לדלג על השלב הזה).
  3. כשהאפליקציה צריכה גישה לנתונים של משתמשים, היא מעבירה ל-Google בקשת גישה בהיקף ספציפי.
  4. Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
  5. אם המשתמש מסכים, האפליקציה מקבלת מ-Google אסימון גישה לטווח קצר.
  6. האפליקציה מבקשת את נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
  7. אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.

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

אלה הפרטים לגבי היקפי OAuth 2.0 של Tag Manager API:

היקף משמעות
https://www.googleapis.com/auth/tagmanager.readonly הצגת הפריטים המכילים שלך ב-Google Tag Manager.
https://www.googleapis.com/auth/tagmanager.edit.containers ניהול של הפריטים המכילים שלך ב-Google Tag Manager.
https://www.googleapis.com/auth/tagmanager.delete.containers מוחקים את מאגרי התגים של Google Tag Manager.
https://www.googleapis.com/auth/tagmanager.edit.containerversions ניהול של גרסאות המאגרים שלך במנהל התגים של Google.
https://www.googleapis.com/auth/tagmanager.publish מפרסמים את מאגרי התגים של Google Tag Manager.
https://www.googleapis.com/auth/tagmanager.manage.users ניהול הרשאות המשתמשים בנתונים שלך במנהל התגים של Google.
https://www.googleapis.com/auth/tagmanager.manage.accounts לנהל את החשבונות שלכם ב-Google Tag Manager.

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

תחילת העבודה

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

כדי להגדיר חשבון שירות חדש:

  1. לוחצים על Create credentials > Service account key.
  2. בוחרים אם להוריד את המפתח הציבורי/פרטי של חשבון השירות כקובץ P12 סטנדרטי, או כקובץ JSON שאפשר לטעון באמצעות ספריית לקוח של Google API.

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

תהליכי OAuth 2.0 נפוצים

בהנחיות הבאות מפורטים תרחישים נפוצים לדוגמה לתהליכי OAuth 2.0 ספציפיים:

שרת אינטרנט

התהליך הזה מתאים לגישה אוטומטית, אופליין או מתוזמנת לחשבון Google Tag Manager של המשתמש.

לדוגמה:
  • עדכון אוטומטי של פרטי Tag Manager מהשרת.

בצד הלקוח

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

לדוגמה:
  • כלי תצורה מותאם אישית המבוסס על דפדפן.

אפליקציות מותקנות

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

דוגמאות:
  • ווידג'ט למחשב PC או Mac.
  • פלאגין למערכת ניהול תוכן. היתרון של התהליך הזה בהשוואה לשרת אינטרנט או לצד הלקוח הוא שאפשר להשתמש בפרויקט אחד של מסוף API לאפליקציה שלך. כך מתאפשרת התקנה פשוטה יותר למשתמשים.

חשבונות שירות

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

פתרון בעיות

אם התוקף של access_token פג או אם משתמשים בהיקף שגוי לקריאה מסוימת ל-API, מקבלים בתגובה את קוד הסטטוס 401.

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

מגרש משחקים עבור OAuth 2.0

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

מענק לא חוקי

אם קיבלת תגובה על שגיאת invalid_grant במהלך הניסיון להשתמש באסימון רענון, ייתכן שהשגיאה נגרמה על ידי אחד מהגורמים הבאים, או שניהם:

  1. השעון של השרת לא מסונכרן עם NTP.
  2. חרגת מהמגבלה של אסימוני הרענון.
    אפליקציות יכולות לבקש מספר אסימוני רענון כדי לגשת לחשבון יחיד של Google Tag Manager. לדוגמה, האפשרות הזו שימושית במצבים שבהם משתמש רוצה להתקין אפליקציה במספר מכונות ולגשת לאותו חשבון Google Tag Manager. במקרה כזה, נדרשים שני אסימוני רענון – אחד לכל התקנה. כשמספר אסימוני הרענון חורג מהמגבלה, אסימונים ישנים יותר הופכים ללא תקפים. אם האפליקציה מנסה להשתמש באסימון רענון לא תקף, תוחזר הודעת השגיאה invalid_grant. כל שילוב ייחודי של Client-ID/חשבון יכול לכלול עד 25 אסימוני רענון. (לתשומת ליבכם: המגבלה הזו עשויה להשתנות). אם האפליקציה ממשיכה לבקש אסימוני רענון עבור אותו שילוב של Client-ID/חשבון, ברגע הנפקת האסימון ה-26, אסימון הרענון הראשון שהונפק הופך ללא תקף. אסימון הרענון המבוקש ב-27 מבטל את התוקף של האסימון השני שהונפק, וכן הלאה.