راهنمای نصب TCRM

مرحله 1: راه اندازی Google Cloud Platform (GCP)

هشدار: پروژه‌های GCP متعلق به Google ممکن است توسط Enforcer (ECP) اجرا شود. در این حالت، نصب با درخواست کلید امنیتی انجام نمی شود. برای جلوگیری از این امر، یک پروژه GCP جدید ایجاد کنید (حدود 24 ساعت طول می کشد تا ECP پروژه شما را پیدا کند)، یا از یک پروژه عمومی استفاده کنید که اجرا نمی شود در حالی که ما سعی می کنیم راه حلی دائمی برای این مشکل پیدا کنیم.

1.1 یک پروژه GCP را انتخاب یا ایجاد کنید

یک پروژه Google Cloud Platform جدید ایجاد کنید یا از یک پروژه موجود استفاده کنید. آن را باز کنید و مطمئن شوید که می توانید نام پروژه را در بالای صفحه ببینید.

مرحله 2: TCRM را نصب کنید

2.1 درخواست دسترسی به پوشه کد TCRM

تا زمانی که TCRM منبع باز و در دسترس خارجی باشد، برای هر استفاده مجوز شبیه سازی لازم است. برای دسترسی به شبیه سازی پوشه کد TCRM ، این فرم درخواست را ارسال کنید .

2.2 TCRM را نصب کنید

  1. روی نماد پوسته ابری در گوشه سمت راست بالای صفحه کلیک کنید تا خط فرمان GCP باز شود.

  2. برای کلون کردن پوشه کد TCRM دستور زیر را در پوسته اجرا کنید:

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

  3. بعد این دستور را اجرا کنید:

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

توجه: این دستور 3 مرحله زیر را انجام می دهد:

  1. یک محیط مجازی پایتون ایجاد کنید و تمام بسته های پایتون مورد نیاز را نصب کنید.
  2. APIهای Cloud مورد نیاز را در پروژه GCP فعال کنید.
  3. یک محیط Cloud Composer ایجاد کنید و DAG های TCRM را در آن مستقر کنید.

توجه: اجرای نصب باید حدود 2 ساعت طول بکشد. لطفاً صبر کنید تا اسکریپت به پایان برسد.

مرحله 3: پیکربندی جریان هوا و تنظیم متغیرها

3.1 راه اندازی اتصال BigQuery

برای خواندن داده‌ها از BigQuery، باید حساب سرویس خود را به اتصال BigQuery مرتبط کنید.

روی Identity → Service Accounts کلیک کنید. سپس روی سه نقطه کنار حساب سرویس که با tcrm-sa شروع می شود کلیک کنید و Create Key → JSON → Create را انتخاب کنید.

کلید دانلود شده را در یک ویرایشگر متن باز کنید و JSON را در آن کپی کنید.

به Airflow برگردید (Composer → Airflow) و Admin → Connections را انتخاب کنید.

روی نماد مداد در کنار اتصال bigquery_default کلیک کنید.

توجه: نام اتصال پیش‌فرض bigquery_default است. اگر از نام اتصال BigQuery دیگری استفاده می‌کنید، لطفاً مطمئن شوید که متغیرهای monitoring_bq_conn_id و bq_conn_id جریان هوا (متغیرها، نه اتصالات) را با نام اتصال جدید تنظیم کنید.

نکته: برای جزئیات بیشتر در مورد مدیریت اتصالات جریان هوا به این صفحه مراجعه کنید.

حساب سرویس JSON را در قسمت Keyfile JSON قرار دهید و روی ذخیره کلیک کنید.

3.2 تنظیم متغیرها با استفاده از Airflow UI

  1. منوی سمت چپ بالای صفحه را باز کنید. سپس روی Composer کلیک کنید تا صفحه محیط های Composer باز شود.

  2. در صفحه Composer، ردیفی به نام 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 ایجاد کنید. برای زمان بندی tcrm_gcs_to_ads_oc DAG، متغیری به نام tcrm_gcs_to_ads_oc_schedule ایجاد کنید.

نام DAG را می توان در رابط کاربری Airflow در برگه DAGs یافت:

3.3.1 جدول متغیر عمومی
نام متغیر مقدار پیش فرض اطلاعات متغیر
<DAG_Name>_retries 0 عدد صحیح تعداد دفعاتی که Airflow سعی می‌کند در صورت شکست، DAG را دوباره اجرا کند. توصیه می کنیم این را روی 0 نگه دارید زیرا TCRM مکانیزم خود را برای تکرار مجدد دارد. با این حال، تنظیم آن بر روی هر عدد صحیح دیگری باعث خطا نمی شود، اما تلاشی برای ارسال مجدد رویدادهای شکست خورده قبلی نخواهد داشت.
<DAG_Name>_retry_delay 3 عدد صحیح تعداد دقیقه بین هر اجرا مجدد DAG.
<DAG_Name>_schedule @once یک برنامه DAG. برای اطلاعات بیشتر در مورد نحوه زمانبندی DAGها، بخش 3.3.2 را برنامه ریزی کنید .
<DAG_Name>_is_retry 1 1 برای فعال کردن، 0 برای غیرفعال کردن. اینکه آیا DAG باید مجدداً رویدادهای ناموفق قبلی را به همان منبع خروجی ارسال کند یا خیر. این یک تلاش مجدد داخلی برای ارسال رویدادهای ناموفق از اجراهای مشابه قبلی است. این با آزمایش مجدد جریان هوا در کل DAG متفاوت است. برای اطلاعات بیشتر به بخش «مکانیسم امتحان مجدد» این راهنمای استفاده مراجعه کنید.
<DAG_Name>_is_run 1 1 برای فعال کردن، 0 برای غیرفعال کردن. اینکه آیا DAG باید شامل اجرای اصلی باشد یا خیر. در صورتی که کاربر بخواهد از اجرای اصلی صرفنظر کند و فقط عملیات تلاش مجدد را اجرا کند، می توان این گزینه را غیرفعال کرد. برای اطلاعات بیشتر به بخش Run این راهنمای استفاده مراجعه کنید.
<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 که می‌خواهید زمان‌بندی کنید، یک متغیر زمان‌بندی ایجاد کنید. نام متغیر باید با نام DAG و سپس _schedule شروع شود.

مقدار متغیر باید بازه‌ای باشد که می‌خواهید DAG خود را در آن زمان‌بندی کنید. مثلا:

برای اجرای DAG فقط یک بار @once را وارد کنید، یا @daily یا @weekly را وارد کنید تا DAG را مطابق با آن اجرا کنید. برای اطلاع از تمامی گزینه های زمان بندی موجود به این راهنما مراجعه کنید.

اینها متغیرهای اختیاری هستند. اگر متغیرهای زمان بندی تنظیم نشده باشند، زمان بندی پیش فرض برای همه DAG ها @once است.

3.4 متغیرهای خاص DAG را پیکربندی کنید

بخش زیر نشان می دهد که کدام متغیرها برای اجرای هر DAG مورد نیاز هستند. شما فقط باید متغیرهایی را برای DAGهایی که قصد استفاده از آنها را دارید تنظیم کنید.

3.4.1 tcrm_bq_to_ga DAG

To برای اجرای tcrm_bq_to_ga DAG متغیرهای زیر را تنظیم کنید:

  • bq_dataset_id : نام مجموعه داده BigQuery حاوی داده‌ها. مثال: my_dataset
  • bq_table_id : نام جدول BigQuery حاوی داده ها. مثال: my_table
  • ga_tracking_id : شناسه پیگیری گوگل آنالیتیکس. مثال: UA-123456789-1

3.4.2 tcrm_gcs_to_ga DAG

برای اجرای tcrm_gcs_to_ga DAG متغیرهای زیر را تنظیم کنید:

  • gcs_bucket_name : نام سطل فضای ذخیره‌سازی ابری. مثال: my_bucket
  • gcs_bucket_prefix : مسیر پوشه داده در داخل سطل. مثال: folder/sub_folder
  • gcs_content_type (اختیاری): نوع محتوای Cloud Storage. JSON یا CSV .
  • ga_tracking_id : شناسه پیگیری گوگل آنالیتیکس. مثال: UA-123456789-1

3.4.3 tcrm_bq_to_ads_oc DAG

برای اجرای tcrm_bq_to_ads_oc DAG متغیرهای زیر را تنظیم کنید:

3.4.4 tcrm_gcs_to_ads_oc DAG

برای اجرای tcrm_gcs_to_ads_oc DAG متغیرهای زیر را تنظیم کنید:

  • gcs_bucket_name : نام سطل فضای ذخیره‌سازی ابری. مثال: my_bucket
  • gcs_bucket_prefix : مسیر پوشه داده در داخل سطل. مثال: folder/sub_folder
  • gcs_content_type (اختیاری): نوع محتوای Cloud Storage. JSON یا CSV .
  • ads_credentials : اطلاعات احراز هویت برای Google Adwords API، لطفاً برای اطلاعات بیشتر به 3.5.1 ایجاد رشته ads_credentials YAML برای تأیید اعتبار Google Ads مراجعه کنید.

3.5 احراز هویت در برابر پلتفرم های گوگل

3.5.1 ایجاد ads_credentials رشته YAML برای احراز هویت Google Ads

برای احراز هویت در مقابل Google Ads باید یک رشته با فرمت YAML ایجاد کنید و آن را به عنوان پارامتر جریان هوا ذخیره کنید. این پارامتر توسط 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 پس از ورود به حساب Google Ads MCC خود در مرکز API قرار دارد.

client_id و client_secret را می توان در صفحه APIs & Services در کنسول GCP ایجاد کرد.

refresh_token را می توان با انجام کارهای زیر تولید کرد:

  • اسکریپت پایتون را دانلود می کند .

  • اسکریپت پایتون را با پارامترهای لازم در یک ترمینال اجرا کنید. python generate_refresh_token.py --client_id INSERT_CLIENT_ID --client_secret INSERT_CLIENT_SECRET

  • روی لینک کلیک کنید.

  • حساب ایمیلی را انتخاب کنید که اجازه تغییر داده های Google Ads شما را دارد و روی Allow کلیک کنید.

  • کد را کپی کرده و بعد از کد در ترمینال قرار دهید. نشانه رفرش در زیر نشان داده خواهد شد.

مرحله 4: داده ها را برای ارسال آماده کنید

4.1 آماده سازی داده ها برای Google Analytics (GA)

توجه: برای جزئیات مورد نیاز به Measurement Protocol API مراجعه کنید.

برای ارسال داده های خود به GA می توانید از 3 گزینه زیر انتخاب کنید:

  1. از BigQuery با استفاده از tcrm_bq_to_ga DAG در قالب جدول SQL.

  2. از Google Cloud Storage با استفاده از tcrm_gcp_to_ga DAG در قالب 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 با استفاده از tcrm_gcp_to_ga DAG در قالب 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 را می پذیرد، باید فیلتر ربات GA را پیکربندی کنید. برای انجام این کار، به Admin -> View Settings -> Bot Filtering در رابط کاربری Google Analytics خود بروید و علامت "Exclude all hits from known bots and spiders" را بردارید .

4.2 داده ها را برای تبدیل آفلاین Google Ads آماده کنید

برای ارسال اطلاعات خود به Google Ads می توانید از 3 گزینه زیر انتخاب کنید:

  1. از BigQuery با استفاده از tcrm_bq_to_ads_oc DAG در قالب جدول SQL.

  2. از Google Cloud Storage با استفاده از tcrm_gcs_to_ads_oc DAG در قالب 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 با استفاده از tcrm_gcp_to_ads_oc DAG در قالب 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 در سمت راست لیست، آن را اجرا کنید.