מיפוי מפרט ECAPI

המדריך הזה עוזר למפתחים שמשתמשים במפרט של Event and Conversion API‏ (ECAPI) של IAB Tech Lab למפות את נתוני האירועים וההמרות שלהם לסכימת הטמעת האירועים של 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.
אם אתם משתמשים במאגרי אחסון לפרוטוקולים, אתם יכולים להשתמש בפונקציות בסיסיות כמו 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 לבין הייצוג שלו כ-Data Manager 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
          }
        ]
      }
    }
  ]
}