מדריך להתקנת TCRM

שלב 1: הגדרת Google Cloud Platform (GCP)

אזהרה: ייתכן שנאכפים על ידי לאכוף (ECP) בפרויקטים של GCP שבבעלות Google. במקרה כזה, ההתקנה תיכשל ותהיה לך בקשה למפתח אבטחה. כדי להימנע מכך, כדאי ליצור פרויקט GCP חדש (יחלפו כ-24 שעות עד שאפשר יהיה למצוא את הפרויקט ב-ECP), או להשתמש בפרויקט ציבורי שלא נאכף בזמן שאנחנו מנסים למצוא פתרון קבוע לבעיה הזו.

1.1 בחירה או יצירה של פרויקט GCP

תוכלו ליצור פרויקט חדש ב-Google Cloud Platform או להשתמש בפרויקט קיים. פותחים את הקובץ כדי לוודא שאפשר לראות את שם הפרויקט בחלק העליון של הדף.

שלב 2: מתקינים את TCRM

2.1 בקשת גישה לתיקיית קוד TCRM

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

2.2 התקנת TCRM

  1. לוחצים על הסמל של Cloud Shell בפינה השמאלית העליונה של הדף כדי לפתוח את שורת הפקודה של GCP.

  2. מריצים את הפקודה הבאה במעטפת כדי לשכפל את התיקייה של קוד ה-TCRM:

      git clone https://github.com/google/TaglessCRM.git

  3. עכשיו, מריצים את הפקודה הבאה:

      cd TaglessCRM && sh setup.sh --project_id=$GOOGLE_CLOUD_PROJECT

הערה: הפקודה הזו תבצע את שלושת השלבים הבאים:

  1. ליצור סביבה וירטואלית ב-Python ולהתקין את כל חבילות ה-Python הנדרשות.
  2. מפעילים את ממשקי ה-API הנדרשים ב-Cloud בפרויקט GCP.
  3. יצירת סביבה של Cloud Composer ופריסת DAG DAGs בתוכה.

הערה: תהליך ההתקנה אמור להימשך כשעתיים. יש להמתין עד לסיום הפעלת הסקריפט.

שלב 3: מגדירים זרימת אוויר ומגדירים משתנים

3.1 הגדרת חיבור BigQuery

כדי לקרוא נתונים מ-BigQuery, צריך לקשר את חשבון השירות לחיבור של BigQuery.

לוחצים על 'זהות' ← 'חשבונות שירות'. לאחר מכן לוחצים על שלוש הנקודות שלצד חשבון השירות שמתחיל ב-tcrm-sa ובוחרים באפשרות 'יצירת מפתח ← JSON' ← 'יצירה'.

פותחים את המַפתח שהורדתם בעורך טקסט ומעתיקים את קובץ ה-JSON שבתוכו.

חוזרים אל Airflow (מלחין ← Airflow) ובוחרים באפשרות Admin → Connections.

לוחצים על סמל העיפרון לצד החיבור bigquery_default.

הערה: ברירת המחדל של שם החיבור היא bigquery_default. אם אתם משתמשים בשם חיבור אחר ל-BigQuery, חשוב להגדיר את המשתנים של monitoring_bq_conn_id ושל bq_conn_id זרימת האוויר (משתנים, לא חיבורים) עם שם החיבור החדש.

טיפ: לפרטים נוספים על ניהול חיבורי Airflow, קראו בדף הזה.

מדביקים את קובץ ה-JSON של חשבון השירות בשדה JSON של קובץ JSON ולוחצים על 'שמירה'.

3.2 הגדרת המשתנים באמצעות ממשק המשתמש של Airflow

  1. פותחים את התפריט בפינה הימנית העליונה של המסך. לאחר מכן לחצו על Composerכדי לפתוח את הדף סביבות מלחין.

  2. במסך 'מלחין', חפשו את השורה tcrm-env בשם בצד שמאל של הרשימה. בשורה הזו, לוחצים על הקישור Airflow כדי לפתוח את מסוף Airflow.

  3. במסוף Airflow, לוחצים על האפשרות Admin בסרגל התפריטים העליון ובוחרים באפשרות Variables מהתפריט הנפתח.

  4. במסך של המשתנים, לוחצים על Create.

  5. כדי להוסיף משתנה חדש, מזינים את השם של מפתח המשתנה ואת הערך שלו, ואז לוחצים על save. עיינו ב-2 השלבים הבאים כדי לראות אילו משתנים נדרשים לכל DAG.

3.3 הגדרת משתני DAG כלליים

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

כדי שלהגדרות DAG שונות יהיו תצורות שונות, חלק מהשמות של המשתנים יכללו את שם ה-DAG כקידומת. חשוב להחליף את החלק <DAG Name> ולהשתמש בשם הנכון של DAG.

לדוגמה: כדי להגדיר את משתנה התזמון עבור tcrm_gcs_to_ga DAG, השתמשו בשם המשתנה מהטבלה הבאה <DAG Name>_schedule וצרו משתנה בשם tcrm_gcs_to_ga_schedule. כדי לתזמן את DAG tcrm_gcs_to_ads_oc, יש ליצור משתנה בשם tcrm_gcs_to_ads_oc_schedule.

ניתן למצוא את שם ה-DAG בממשק המשתמש של Airflow בכרטיסייה 'DAG':

3.3.1 טבלה של משתנים כלליים
שם משתנה ערך ברירת מחדל פרטי המשתנה
<DAG_Name>_retries 0 מספר שלם. מספר הפעמים ש-Airflow תנסה להריץ מחדש את ה-DAG אם הוא ייכשל. מומלץ לשמור על ערך זהה של אפס, כי ל-TCRM יש מנגנון ניסיון חוזר משלה. עם זאת, הגדרת מספר שלם אחר לא תגרום לשגיאות, אבל היא לא תנסה לשלוח מחדש אירועים שנכשלו.
<DAG_Name>_retry_delay 3 מספר שלם. מספר הדקות בין כל DAG להפעלה מחדש.
<DAG_Name>_schedule @once לוח זמנים קצר. בקטע 3.3.2 תזמון DAG יש מידע נוסף על תזמון DAG.
<DAG_Name>_is_retry 1 1 להפעלה, 0 להשבתה. האם על ה-DAG לנסות שוב לשלוח אירועים שנכשלו בעבר לאותו מקור פלט. זהו ניסיון פנימי נוסף לשלוח אירועים שנכשלו מהפעלות דומות קודמות. הבדיקה שונה מניסיון ההפעלה מחדש של DAG כולו. למידע נוסף, ניתן לעיין בקטע ניסיון נוסף במנגנון במדריך השימוש הזה.
<DAG_Name>_is_run 1 1 להפעלה, 0 להשבתה. האם ה-DAG צריך לכלול הפעלה מרכזית. ניתן להשבית את האפשרות הזו אם המשתמש רוצה לדלג על ההפעלה הראשית ולבצע רק את הפעולה החוזרת. מידע נוסף זמין בקטע הפעלה במדריך השימוש הזה.
<DAG_Name>_enable_run_report 0 1 להפעלה, 0 להשבתה. מציין אם ה-DAG יחזיר דוח הרצה או לא. לא לכל המידע האישי (DAG) יש דוחות. מידע נוסף זמין בקטע דוחות במדריך השימוש הזה.
<DAG_Name>_enable_monitoring 1 1 להפעלה, 0 להשבתה. מידע נוסף זמין בקטע מעקב במדריך השימוש הזה.
monitoring_dataset tcrm_monitoring_dataset מזהה מערך הנתונים של טבלת המעקב.
monitoring_table tcrm_monitoring_table שם הטבלה של טבלת המעקב.
monitoring_bq_conn_id bigquery_default מזהה החיבור של BigQuery לטבלת המעקב. מספר זה יכול להיות שונה ממזהה החיבור BQ, או להזין אותו בנפרד.
3.3.2 תזמון DAG

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

ערך המשתנה צריך להיות המרווח שאיתו רוצים לתזמן את DAG. למשל:

הוסיפו את התו @once כדי להריץ את DAG רק פעם אחת, או את הערך @daily או @weekly כדי להגדיר את DAG כך שיפעל בהתאם. היעזרו במדריך הזה כדי לברר מהן האפשרויות הזמינות.

המשתנים האלה הם אופציונליים. אם לא הוגדרו משתני תזמון, לוח הזמנים של ברירת המחדל לכל DAG הוא @once.

3.4 הגדרת משתני DAG ספציפיים

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

3.4.1tcrm_bq_to_ga DAG

כדי להריץ את ה-DAG tcrm_bq_to_ga, יש להגדיר את המשתנים הבאים:

  • bq_dataset_id: השם של מערך הנתונים ב-BigQuery שמכיל את הנתונים. דוגמה: my_dataset
  • bq_table_id: השם של טבלת BigQuery שמכיל את הנתונים. דוגמה: my_table
  • ga_tracking_id: מזהה לצורכי מעקב של Google Analytics. דוגמה: UA-123456789-1

3.4.2tcrm_gcs_to_ga DAG

כדי להפעיל את ה-DAG tcrm_gcs_to_ga, יש להגדיר את המשתנים הבאים:

  • gcs_bucket_name: שם קטגוריה של Cloud Storage. דוגמה: my_bucket
  • gcs_bucket_prefix: הנתיב לתיקיית הנתונים שבתוך הקטגוריה. דוגמה: folder/sub_folder
  • gcs_content_type(אופציונלי): סוג התוכן ב-Cloud Storage. JSON או CSV.
  • ga_tracking_id: מזהה לצורכי מעקב של Google Analytics. דוגמה: UA-123456789-1

3.4.3tcrm_bq_to_ads_oc DAG

כדי להפעיל את ה-DAG tcrm_bq_to_ads_oc, יש להגדיר את המשתנים הבאים:

3.4.4 tcrm_gcs_to_ads_oc DAG

כדי להפעיל את ה-DAG tcrm_gcs_to_ads_oc, יש להגדיר את המשתנים הבאים:

  • gcs_bucket_name: שם קטגוריה של Cloud Storage. דוגמה: my_bucket
  • gcs_bucket_prefix: הנתיב לתיקיית הנתונים שבתוך הקטגוריה. דוגמה: folder/sub_folder
  • gcs_content_type(אופציונלי): סוג התוכן ב-Cloud Storage. JSON או CSV.
  • ads_credentials: פרטי האימות ב-Google AdWords API זמינים במאמר 3.5.1 יצירת מחרוזת YAML של ads_credentials לאימות של Google Ads.

3.5 אימות מול Google Platforms

3.5.1 יצירת מחרוזת YAML של ads_credentials לאימות Google Ads

כדי לאמת את עצמכם מול Google Ads, תצטרכו ליצור מחרוזת בפורמט YAML ולשמור אותה כפרמטר של Airflow. הפרמטר הזה ישמש את TCRM לאימות בין TCRM לבין Google Ads. פורמט המחרוזת הוא:

developer_token: abcd
client_id: test.apps.googleusercontent.com
client_secret: secret
refresh_token: 1//token
login_customer_id: 1234567890
use_proto_plus: True

login_customer_id מופיע בפינה השמאלית העליונה, מעל הודעת האימייל, אחרי ההתחברות ל-Google Ads. מספר הלקוח צריך להיות מספר של חשבון ניהול (MCC) שכולל את חשבונות Google Ads שרוצים להפוך לאוטומטיים.

המאפיין developer_token מופיע במרכז ה-API לאחר שנכנסתם לחשבון Google Ads שלכם.

client_id ו-client_secret אפשר ליצור בדף ממשקי ה-API והשירותים במסוף ה-GCP.

אפשר ליצור את refresh_token בדרכים הבאות:

  • הורדת הסקריפט של Python.

  • מריצים את הסקריפט של Python עם הפרמטרים הנדרשים במסוף. python generate_refresh_token.py --client_id INSERT_CLIENT_ID --client_secret INSERT_CLIENT_SECRET

  • לוחצים על הקישור.

  • בוחרים את חשבון האימייל עם ההרשאה לשנות את נתוני Google Ads, ולוחצים על 'אישור'.

  • מעתיקים את הקוד ומדביקים אותו במסוף אחרי הקוד. אסימון הרענון יופיע למטה.

שלב 4: הכנת הנתונים לשליחה

4.1 הכנת הנתונים ל-Google Analytics (GA)

הערה: הדרישות המפורטות מפורטות ב-Measurement Protocol API.

יש 3 אפשרויות לשלוח נתונים ל-Google Analytics:

  1. באמצעות BigQuery בעזרת DAG tcrm_bq_to_ga בטבלה של SQL.

  2. מ-Google Cloud Storage עם DAG tcrm_gcp_to_ga בפורמט JSON.

{"cid": "12345.67890", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "300" }
{"cid": "12345.67891", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "301" }
{"cid": "12345.67892", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "302" }
{"cid": "12345.67893", "t":"event", "ec": "video", "ea": "play", "el": "holiday", "ev": "303" }
  1. מ-Google Cloud Storage עם DAG tcrm_gcp_to_ga בפורמט CSV.
cid,t,ec,ea,el,ev
12345.67890,event,video,play,holiday,300
12345.67891,event,video,play,holiday,301
12345.67892,event,video,play,holiday,302
12345.67893,event,video,play,holiday,303

אזהרה: כדי לוודא ש-GA יקבל את הנתונים שנשלחים מ-TCRM, צריך להגדיר את סינון הבוטים של Google Analytics. כדי לעשות זאת, עוברים אל Admin -> View Settings -> Bot Filtering בממשק המשתמש של Google Analytics ומבטלים את הסימון של 'החרגת כל ההיטים מבוטים ומסורקים ידועים'.

4.2 הכנת הנתונים להמרה אופליין ב-Google Ads

יש 3 אפשרויות לשליחת הנתונים ל-Google Ads:

  1. באמצעות BigQuery בעזרת DAG tcrm_bq_to_ads_oc בטבלה של SQL.

  2. מ-Google Cloud Storage עם DAG tcrm_gcs_to_ads_oc בפורמט JSON.

{"conversionName": "my_conversion_1", "conversionTime":"20191030 122301 Asia/Calcutta", "conversionValue": "0.47", "googleClickId": "gclid1"}
{"conversionName": "my_conversion_1", "conversionTime":"20191030 122401 Asia/Calcutta", "conversionValue": "0.37", "googleClickId": "gclid2"}
{"conversionName": "my_conversion_2", "conversionTime":"20191030 122501 Asia/Calcutta", "conversionValue": "0.41", "googleClickId": "gclid3"}
{"conversionName": "my_conversion_2", "conversionTime":"20191030 122601 Asia/Calcutta", "conversionValue": "0.17", "googleClickId": "gclid4"}
  1. מ-Google Cloud Storage עם DAG tcrm_gcp_to_ads_oc בפורמט CSV.
conversionName,conversionTime,conversionValue,googleClickId
my_conversion_1,20191030 122301 Asia/Calcutta,0.47,gclid1
my_conversion_1,20191030 122401 Asia/Calcutta,0.37,gclid2
my_conversion_2,20191030 122501 Asia/Calcutta,0.41,gclid3
my_conversion_2,20191030 122601 Asia/Calcutta,0.17,gclid4

שלב 5: הפעלת TCRM

במסוף Airflow, לוחצים על האפשרות DAGs בסרגל התפריטים העליון. ברשימה שמימין, מוצאים את ה-DAG שרוצים להפעיל. אחר כך לוחצים על הלחצן Play בצד שמאל של הרשימה.