מיפוי מפרט 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 הערך הזה משמש לביטול כפילויות של אירועי המרה. מידע נוסף
timestamp event_timestamp חובה. ב-ECAPI נעשה שימוש בפורמט של תקופת הזמן של מערכת Unix (מספר שלם) לחותמות זמן. כשממפים ל-Data Manager API, צריך להמיר את השדה event_timestamp לאחד מהפורמטים הבאים:
  • אם משתמשים בפורמט JSON, צריך להגדיר ערך בפורמט RFC 3339.
  • אם משתמשים ב-Protocol Buffers, צריך להשתמש ב-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 מייצג מזהה משתמש. ממשק ה-API של המרכז לניהול נתונים לא תומך בשדות כלליים של מזהי לקוחות ליעדים אחרים.
uids אין דוח מקביל ‫Data Manager API לא תומך במערך מובנה uids שמכיל סוגים של סוכנים ודומיינים.
customer_segments user_properties מפה לUserProperties בEvent.
email_address user_data.user_identifiers[].email_address מגדירים את כתובת האימייל בפורמט מגובב. אפשר גם להצפין את כתובת האימייל המגובבת.
phone_numbers user_data.user_identifiers[].phone_number מוגדר למספר הטלפון המפורמט והמגובב. אפשר גם להצפין את מספר הטלפון המגובב.
utcoffset אין דוח מקביל אם אתם משתמשים בפורמט JSON, אתם יכולים לציין את ההפרש מאזור הזמן ישירות במחרוזת event_timestamp RFC 3339. ‫
אם אתם משתמשים ב-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. פועלים לפי ההנחיות בנוגע לפורמט ולגיבוב. אפשר גם להצפין את מאפייני הכתובת שעברו גיבוב.
last_name family_name מיפוי לשדה family_name ב-AddressInfo. פועלים לפי ההנחיות בנוגע לפורמט ולגיבוב. אפשר גם להצפין את מאפייני הכתובת שעברו גיבוב.
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 עם נתונים מעגלות קניות (CwCD). מגדירים את הערך למזהה המוצר בחשבון 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
          }
        ]
      }
    }
  ]
}