מיפוי מפרט ECAPI

המדריך הזה עוזר למפתחים שמשתמשים במפרט של IAB Tech Lab Event and Conversion API (ECAPI) למפות את נתוני האירועים וההמרות שלהם לסכימת הטמעת האירועים של Data Manager API.

סקירה כללית

‫ECAPI הוא תקן נתונים בקוד פתוח שלא תלוי בפלטפורמה, שמגדיר את המבנה של אירועים והמרות שקשורים לשיווק.

בטבלה הבאה מוצגת סקירה כללית של ההבדלים בין מאפיינים מרכזיים ועקרונות עיצוב של ECAPI לבין Data Manager API:

ECAPI Data Manager API
ביטול כפילויות מסתמך על id (מזהה אירוע) מסתמך על transaction_id
ניתוב אירועים השדה data_set_id במטען הייעודי (payload) של האירוע מציין את יעד הנתונים. בשדה destinations של הבקשה מוגדרים יעדי האירועים.

‫Data Manager API תומך גם בהעברת אירועים לכמה יעדים בבקשה אחת.

מידע נוסף זמין במאמר הגדרת יעדים וכותרות.
שדות של פרטיות והסכמה מחרוזות הסכמה ב-Global Privacy Platform (הפלטפורמה הגלובלית להעדפות פרטיות, GPP) ‫Data Manager API לא מקבל או מנתח מחרוזות הסכמה של Global Privacy Platform (הפלטפורמה הגלובלית להעדפות פרטיות, GPP). מגדירים את שדות ההסכמה באובייקט Consent.

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

מיפוי שדות מבניים

בטבלאות המיפוי הבאות מוגדר איך שדות ספציפיים מהמפרט של ECAPI מתורגמים לשדות שמתקבלים על ידי Data Manager API:

מיפוי אובייקטים של אירועים

‫ECAPI (event) ‫Data Manager API‏ (Event) הערות
data_set_id
  • ‫destinations[].product_destination_id (רמת הבקשה)
  • destination_references (ברמת האירוע)
 אפשר להגדיר יעדים ברמות הבאות:
  • רמת הבקשה (חובה): מציינים את רשימת destinations בתוך IngestEventsRequest.
  • ברמת האירוע (אופציונלי): משתמשים בשדה destination_references באובייקט Event. מוסיפים רשומה כדי לציין איזה יעד מהרשימה destinations אמור לקבל את האירוע.

מידע נוסף על הגדרת Destination וקביעת מזהה היעד של המוצר זמין במאמר הגדרת יעדים וכותרות.
id transaction_id מבטל כפילויות של אירועי המרה. במאמרים בנושא שליחת אירועים ל-Google Ads,‏ Google Analytics ו-Floodlight מוסבר איך Google מטפלת בנתונים ממקורות שונים.
timestamp event_timestamp חובה. ב-ECAPI נעשה שימוש בפורמט ראשית זמן יוניקס (Unix epoch) (מספר שלם) לחותמות זמן. כשממפים ל-Data Manager API, ממירים את השדה event_timestamp לאחד מהפורמטים הבאים:
  • אם משתמשים בפורמט JSON, צריך להגדיר ערך בפורמט RFC 3339.
  • אם משתמשים במאגרי אחסון לפרוטוקולים, צריך להשתמש ב-Timestamp ולהגדיר את השדות seconds ו-nanoseconds (אופציונלי).

מידע נוסף מופיע בקטע פורמטים של חותמות זמן.
event_type / custom_event event_name זה יכול להיות שם האירוע המומלץ (לדוגמה, purchase) או שם של אירוע מותאם אישית. פרטים נוספים זמינים במאמר שמות של אירועים רגילים.
user_data user_data מיפוי לאובייקט UserData, שמקבל רשימה של אובייקטים מסוג UserIdentifier.
value conversion_value ממפים ישירות כערך מסוג double או float שמייצג את הערך הכספי של ההמרה.
currency_code currency מיפוי לקוד מטבע בן שלוש אותיות באותיות רישיות (לדוגמה, USD).
source event_source הערך מוגדר מתוך enum של EventSource.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 ממפים פריטים ברמת העסקה למערך cart_data.items באובייקט CartData. ה-Data Manager API תומך בכמה שדות אופציונליים של Merchant Center למוצרים שקיימים בחשבונות Merchant Center.

אם היעד הוא פעולת המרה ב-Google Ads, אפשר גם לכלול פרמטרים מותאמים אישית נוספים בשדה custom_variables כרשימה של אובייקטים מסוג CustomVariable.

אם היעד הוא מקור נתונים של Google Analytics, אפשר לכלול פרמטרים נוספים של אירועים בשדה additional_event_parameters כרשימה של אובייקטים מסוג AdditionalEventParameter.
ext אין דוח מקביל

מיפוי אובייקטים של נתוני משתמשים

ב-Data Manager API, השדה user_data באובייקט Event מקבל אובייקט UserData. הפונקציה הזו מצפה לרשימה של אובייקטים מסוג UserIdentifier, שיכולים להכיל מזהי משתמשים בודדים כמו כתובות אימייל, מספרי טלפון או רכיבי כתובת:

‫ECAPI (user_data) ‫Data Manager API‏ (Event) הערות
customer_identifier user_id (Google Analytics) עבור אירועים ב-Google Analytics, השדה user_id מייצג User-ID. ‫Data Manager API לא תומך בשדות כלליים של מזהה לקוח ליעדים אחרים.
uids אין דוח מקביל ה-API של המרכז לניהול נתונים לא תומך במערך uids מובנה שמכיל סוגי סוכנים ודומיינים.
customer_segments user_properties מפה אל UserProperties בEvent.
email_address user_data.user_identifiers[].email_address מגדירים את כתובת האימייל בפורמט הנכון ועם גיבוב (hash). אפשר גם להצפין את כתובת האימייל שעברה גיבוב.
phone_numbers user_data.user_identifiers[].phone_number מגדירים את מספר הטלפון בפורמט הנכון ומגובב. אפשר גם להצפין את מספר הטלפון המגובב.
utcoffset אין דוח מקביל אם אתם משתמשים בפורמט JSON, אתם יכולים לציין את ההפרש מאזור הזמן ישירות במחרוזת RFC 3339 event_timestamp.
אם אתם משתמשים ב-protocol buffers, אתם יכולים להשתמש בפונקציות עזר כמו Timestamps.parse(String) כדי לטפל בהמרה של אזור זמן לשניות ולננו-שניות.
מידע נוסף מופיע בקטע פורמטים של חותמות זמן.
address user_data.user_identifiers[].address מיפוי לאובייקט AddressInfo. מיפוי של אובייקט Address
gpp_string אין דוח מקביל מיפוי ההסכמה לאובייקט Consent ברמת הבקשה או ברמת האירוע. מידע כללי על פרטיות והסכמה
gpp_sid אין דוח מקביל ממפים את ההסכמה לאובייקט Consent ברמת הבקשה או ברמת האירוע. סקירה כללית בנושא פרטיות והסכמה
mmt_only אין דוח מקביל
click_id ad_identifiers.gclid מיפוי למספר הקליק ב-Google ‏ (gclid). פרטים נוספים זמינים במאמר בנושא AdIdentifiers.
impression_id ad_identifiers.impression_id פרטים נוספים מופיעים במאמר AdIdentifiers.
event_ip_address event_device_info.ip_address אפשר לעיין בDeviceInfo כדי לראות את השדות הזמינים.
event_user_agent event_device_info.user_agent אפשר לעיין בDeviceInfo כדי לראות את השדות הזמינים.
ifa ad_identifiers.mobile_device_id מיפוי למזהה לצורכי פרסום בנייד (IDFA ב-iOS, ‏ AdID ב-Android). פרטים נוספים מופיעים במאמר AdIdentifiers.
landing_ip_address ad_identifiers.landing_page_device_info.ip_address אפשר לראות את השדות הזמינים במאמר DeviceInfo.
landing_user_agent ad_identifiers.landing_page_device_info.user_agent אפשר לראות את השדות הזמינים במאמר DeviceInfo.
age_range אין דוח מקביל
gender אין דוח מקביל
ext אין דוח מקביל

מיפוי של אובייקט כתובת

‫ECAPI (address) ‫Data Manager API‏ (AddressInfo) הערות
first_name given_name ממופה לשדה given_name ב-AddressInfo. פועלים לפי ההנחיות בנושא פורמט וגיבוב (hash). אפשר גם להצפין את המאפיינים המגובבים של כתובת.
last_name family_name ממופה לשדה family_name ב-AddressInfo. פועלים לפי ההנחיות להזנת נתונים בפורמט הנכון ולגיבוב (hash). אפשר גם להצפין את המאפיינים המגובבים של כתובת.
street אין דוח מקביל לא נתמך ב-Data Manager API.
city אין דוח מקביל לא נתמך ב-Data Manager API.
state אין דוח מקביל לא נתמך ב-Data Manager API.
country_code region_code לא לבצע גיבוב. ממופה לשדה region_code ב-AddressInfo. פועלים לפי ההנחיות בנושא פורמט.
postal_code postal_code אל תבצעו גיבוב. ממופה לשדה postal_code ב-AddressInfo. פועלים לפי ההנחיות בנושא פורמט.
address_type אין דוח מקביל לא נתמך ב-Data Manager API.
ext אין דוח מקביל

מיפוי אובייקטים של פריטים

‫ECAPI (item) ‫Data Manager API‏ (Item) הערות
id item_id חובה לאירועים ב-Google Analytics. צריך להגדיר מזהה ייחודי סטנדרטי לפריט.
אין דוח מקביל merchant_product_id חובה להמרות ב-Floodlight ולהמרות ממודעות ב-Google Ads עם נתוני עגלות הקניות. מגדירים את מזהה המוצר בחשבון Merchant Center.
name additional_item_parameters מפה בתור item_name ברשימה additional_item_parameters.
price unit_price
discount additional_item_parameters או custom_variables ממפים בתור discount ב-additional_item_parameters (ל-Google Analytics) או בתור משתנה מותאם אישית ב-custom_variables (ל-Google Ads).
quantity quantity המרת הערך float למספר שלם (int64).
brand additional_item_parameters מפה של item_brand ברשימה additional_item_parameters.
affiliation additional_item_parameters מפה בתור affiliation ברשימה additional_item_parameters.
category additional_item_parameters מפה של item_category ברשימה additional_item_parameters.
cattax אין דוח מקביל
item_coupon additional_item_parameters מפה בתור coupon ברשימה additional_item_parameters.
item_list_id additional_item_parameters מפה בתור item_list_id ברשימה additional_item_parameters.
item_list_name additional_item_parameters מפה בתור item_list_name ברשימה additional_item_parameters.
item_item_variant additional_item_parameters מפה של item_variant ברשימה additional_item_parameters.
item_location_id additional_item_parameters מיפוי בתור location_id בadditional_item_parameters.
ext אין דוח מקביל

שמות סטנדרטיים של אירועים

האירועים הרגילים של ECAPI תואמים במידה רבה למוסכמות מתן השמות של Google Analytics.

לרוב האירועים הרגילים של ECAPI (כמו purchase,‏ add_to_cart,‏ begin_checkout,‏ search ו-refund) יש שם זהה לשם של האירועים המומלצים ב-Google Analytics. עם זאת, יש כמה מקרים חריגים שבהם מערכת Google Analytics משתמשת בזמן הווה במקום בזמן עבר:

  • ‫viewed_item עד view_item

  • ‫viewed_item_list עד view_item_list

  • ‫viewed_cart ממופה אל view_cart

דוגמאות לבקשות

בכרטיסיות הבאות מוצגת השוואה בין מטען ייעודי (payload) של אירוע המרה ב-ECAPI לבין הייצוג שלו כ-API תקף של המרכז לניהול נתונים IngestEventsRequest:

ECAPI

הנה דוגמה למטען ייעודי (payload) של JSON שתואם למפרט של ECAPI:

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

Data Manager API

הנה דוגמה ל-IngestEventsRequest של נתוני האירועים אחרי העיצוב, הגיבוב והקידוד. סוג החשבון GOOGLE_ADS ביעד מציין שהבקשה מטרגטת יעד ב-Google Ads:

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}