דף זה תורגם על ידי Cloud Translation API.

שליחת אירועים

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

אפשר להשתמש ב-Data Manager API באחד מהתרחישים הבאים:

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

בוחרים את הגרסה של המדריך שרוצים לראות:

במדריך למתחילים הזה תבצעו את הפעולות הבאות:

מכינים Destination לקבלת נתוני אירועים.
מכינים את נתוני האירועים לשליחה.
יצירת בקשת IngestionService לאירועים.
שולחים את הבקשה באמצעות Google APIs Explorer.
הסבר על תגובות הצלחה וכישלון.

הכנת יעד

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

    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

מגדירים את accountId של operatingAccount למזהה חשבון Google Ads שיקבל את נתוני האירועים. הערך accountType של התג operatingAccount חייב להיות GOOGLE_ADS.
מגדירים את הערך של productDestinationId למזהה של פעולת ההמרה עבור האירועים. במקרה של אירועים אונליין, פעולת ההמרה צריכה להיות פעולת המרה ב-Google Ads עם הערך WEBPAGE שמוגדר ל-type. במקרה של אירועים אופליין, פעולת ההמרה צריכה להיות פעולת המרה ב-Google Ads עם הערך type שמוגדר ל-UPLOAD_CLICKS.

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

הכנת נתוני אירועים

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

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

אלה הנתונים של האירוע הראשון:

אירוע מס' 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`

אלה הנתונים של האירוע השני:

אירוע מס' 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`

עיצוב הנתונים

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

אירוע מס' 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`

אלה הנתונים של האירוע השני אחרי העיצוב:

אירוע מס' 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`

גיבוב וקידוד הנתונים

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

אירוע מס' 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`

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

אירוע מס' 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`

המרת הנתונים ל-`Event`

ממירים את הנתונים המפורמטים והמגובבים של כל אירוע ל-Event. ממלאים את שדות החובה הבאים:

‫event_timestamp: השעה שבה האירוע התרחש.
‫event_source: המקור של האירוע. חובה בשביל אירועים אופליין. אופציונלי לאירועים אונליין. אם מציינים את הערך הזה לאירוע אונליין, הוא חייב להיות WEB.
‫ad_identifiers או user_data: האירוע חייב לכלול מזהה פרסום או נתוני משתמש. אם יש לכם את שניהם לאירוע, כדאי לשלוח את שניהם.

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

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

הנה דוגמה ל-Event של הנתונים המפורמטים, המגובבים והמקודדים מהאירוע השני:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "eventTimestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ],
      "userProperties": {
        "customerType": "RETURNING"
      }
   }
}

יצירת גוף הבקשה

משלבים את Destination ו-Events בגוף הבקשה:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       }
     }
  ],
  "validateOnly": true
}

מעדכנים את ה-placeholders בגוף ההודעה, כמו OPERATING_ACCOUNT_ID ו-CONVERSION_ACTION_1_ID, עם הערכים של החשבון והיעד.
מגדירים את validateOnly ל-true כדי לאמת את הבקשה בלי להחיל את השינויים. כשמוכנים להחיל את השינויים, מגדירים את validateOnly לערך false.
שימו לב שבמקרה הזה לא נעשה שימוש בהצפנה.

שליחת הבקשה

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

תגובות שבוצעו בהצלחה

אם הבקשה מצליחה, מוחזרת תגובה עם אובייקט שמכיל requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

כדאי לתעד את requestId שמוחזר כדי שתוכלו לאחזר אבחון כשכל יעד בבקשה יעבור עיבוד.

תגובות שמעידות על כשל

בקשה שנכשלה מניבה קוד סטטוס של תגובה עם שגיאה, כמו 400 Bad Request, ותגובה עם פרטי השגיאה.

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

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

מחרוזת email_address שלא עוברת גיבוב ומקודדת רק בפורמט הקסדצימלי מפיקה את התגובה הבאה:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

שליחת אירועים למספר יעדים

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

לדוגמה, אם יש לכם אירוע עם מזהה פעולת ההמרה 123456789 ואירוע נוסף עם מזהה פעולת ההמרה 777111122, אתם יכולים לשלוח את שני האירועים בבקשה אחת על ידי הגדרת reference של כל Destination. הערך של reference מוגדר על ידי המשתמש – הדרישה היחידה היא שלכל Destination יהיה reference ייחודי. זו רשימת destinations ששונתה עבור הבקשה:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789",
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122",
      "reference": "conversion_action_2"
    }
  ]

מגדירים את destination_references של כל Event כדי לשלוח אותו ליעד ספציפי אחד או יותר. לדוגמה, הנה Event שרלוונטי רק ל-Destination הראשון, ולכן רשימת destination_references שלו מכילה רק את reference של Destination הראשון:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "conversion_action_1"
   ]
}

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

השלבים הבאים

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

סקירה כללית של אירועים