מיפוי מפרט 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. ‫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. ממשק ה-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
          }
        ]
      }
    }
  ]
}