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

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

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

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

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

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

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

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

הכנת יעד

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

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  • מגדירים את accountId של operatingAccount למזהה חשבון Google Ads שיקבל את נתוני האירועים. הערך product של התג 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: השעה שבה האירוע התרחש.
  • ‫transaction_id: המזהה הייחודי של האירוע.
  • ‫event_source: המקור של האירוע. חובה לאירועים אופליין. אופציונלי לאירועים אונליין. אם מציינים את הערך הזה לאירוע אונליין, הוא חייב להיות WEB.
  • ‫ad_identifiers או user_data: האירוע חייב לכלול מזהה פרסום או נתוני משתמש. אם יש לכם את שניהם לאירוע, כדאי לשלוח את שניהם.

רשימה מלאה של השדות הזמינים מופיעה במסמכי העזרה של 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": {
        "product": "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
}
  1. מעדכנים את ה-placeholders בגוף ההודעה, כמו OPERATING_ACCOUNT_ID ו-CONVERSION_ACTION_1_ID, עם הערכים של החשבון והיעד.
  2. מגדירים את validateOnly לערך true כדי לאמת את הבקשה בלי להחיל את השינויים. כשמוכנים להחיל את השינויים, מגדירים את validateOnly לערך false.
  3. שימו לב שבמקרה הזה לא נעשה שימוש בהצפנה.

שליחת הבקשה

  1. מעתיקים את גוף הבקשה באמצעות לחצן ההעתקה בפינה השמאלית העליונה של הדוגמה.
  2. עוברים לדף events.ingest.
  3. לוחצים על הלחצן API בצד שמאל, ואז על הלחצן Try it! בקטע המורחב.
  4. מדביקים את גוף הבקשה שהועתק בתיבה גוף הבקשה.
  5. לוחצים על הלחצן Execute (הפעלה), פועלים לפי ההנחיות לאישור הגישה ובודקים את התגובה.

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

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

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

תגובות שגיאה

בקשה שנכשלה מניבה קוד סטטוס של תגובה עם שגיאה, כמו 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": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "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, Data Manager API שולח את האירוע לכל היעדים בבקשה.

השלבים הבאים