מיפוי שדות

כדי לשדרג כל שלב בתהליך העבודה של ההתאמה ללקוחות מ-Google Ads API ל-Data Manager API, אתם יכולים להשתמש במיפוי השדות:

אימות

‫Data Manager API דורש פרטי כניסה עם היקף שונה מזה של Google Ads API. כדי ליצור פרטי כניסה חדשים שכוללים את ההיקף של Data Manager API, פועלים לפי השלבים שמפורטים במאמר הגדרת גישה ל-API.

מיפוי שדות של המרכז לניהול קהלים

אתם יכולים להשתמש במיפויים שבטבלאות כדי למפות UserList ב-Google Ads API לערך המקביל שלו, UserList, ב-Data Manager API.

UserList (Google Ads API) UserList (Data Manager API) הערות
resource_name name פרטים נוספים זמינים בקטע שמות של משאבים.
id id
read_only read_only
name display_name חובה
description description חובה
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

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

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

size_for_display size_info.display_network_members_count
size_range_for_display אין מקבילה. אפשר להשתמש בsize_info.display_network_members_count כדי לקבל מידע על הגודל.
size_for_search size_info.search_network_members_count
size_range_for_search אין מקבילה. אפשר להשתמש בsize_info.search_network_members_count כדי לקבל מידע על הגודל.
type אין מקבילה.
access_reason access_reason
account_user_list_status account_access_status
closing_reason closing_reason
eligible_for_search target_network_info.eligible_for_search
eligible_for_display target_network_info.eligible_for_display
match_rate_percentage ingested_user_list_info.contact_id_info.match_rate_percentage
basic_user_list ingested_user_list_info.pseudonymous_id_info לא משמשת להתאמה ללקוחות.
crm_based_user_list ingested_user_list_info חובה. מידע על קהלים מסוג "התאמה ללקוחות"
אין מקבילה. ingested_user_list_info.pair_id_info לא משמשת להתאמה ללקוחות.
אין מקבילה. ingested_user_list_info.partner_audience_info לא משמשת להתאמה ללקוחות.
logical_user_list אין מקבילה. לא משמשת להתאמה ללקוחות.
logical_user_list אין מקבילה. לא משמשת להתאמה ללקוחות.
lookalike_user_list אין מקבילה. לא משמשת להתאמה ללקוחות.
rule_based_user_list אין מקבילה. לא משמשת להתאמה ללקוחות.
similar_user_list אין מקבילה. לא משמשת להתאמה ללקוחות.

פרטי הקהל מסוג "התאמה ללקוחות"

ב-Google Ads API, צריך להגדיר את השדה crm_based_user_list לערך CrmBasedUserListInfo כשיוצרים קהל התאמה ללקוחות.

ב-Data Manager API, מגדירים את המאפיינים המקבילים על ידי הגדרת השדה ingested_user_list_info לערך IngestedUserListInfo, ואז מגדירים את שדות החובה של "התאמה ללקוחות" ואת סוג נתוני המשתמשים.

פרטים ליצירת קשר

upload_key_types
צריך להגדיר רשימה שמכילה את CONTACT_ID. זה שווה ערך להגדרה של upload_key_type ל-CONTACT_INFO ב-Google Ads API.
contact_id_info

מגדירים ContactIdInfo.

מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY. הפעולה הזו מקבילה להגדרה של data_source_type לערך FIRST_PARTY ב-Google Ads API.

Mobile ID (mID)

upload_key_types
צריך להגדיר רשימה שמכילה את MOBILE_ID. זה שווה ערך להגדרה של upload_key_type ל-MOBILE_ADVERTISING_ID ב-Google Ads API.
mobile_id_info

מגדירים MobileIdInfo.

  • מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY. הפעולה הזו מקבילה להגדרת data_source_type לערך FIRST_PARTY ב-Google Ads API.
  • מגדירים את key_space לערך IOS או ANDROID. הערך הזה נדרש ב-Data Manager API. זה שונה מ-Google Ads API, שבו מרחב המפתחות מוסק מהשדה app_id.
  • מגדירים את app_id למחרוזת שמזהה באופן ייחודי את האפליקציה לנייד שממנה נאספו הנתונים. השתמשו באותו פורמט שבו אתם משתמשים בשדה app_id ב-Google Ads API.

מזהי משתמשים

upload_key_types
צריך להגדיר רשימה שמכילה את USER_ID. זה שווה ערך להגדרה של upload_key_type ל-CRM_ID ב-Google Ads API.
user_id_info

מגדירים UserIdInfo.

מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY. הפעולה הזו מקבילה להגדרת data_source_type לערך FIRST_PARTY ב-Google Ads API.

שמות המשאבים

הפורמט של שם המשאב ב-Data Manager API שונה מהפורמט ב-Google Ads API.

Google Ads API

ב-Google Ads API, שם המשאב של UserList מבוסס על הפורמט הבא:

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

ב-Data Manager API, שם המשאב של UserList הוא בפורמט הבא:

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

העלאת מיפוי השדות

אתם יכולים להשתמש במיפויים שבטבלאות כדי למפות AddOfflineUserDataJobOperationsRequest ב-Google Ads API לבקשת IngestionService המקבילה ב-Data Manager API.

שדות של בקשה

המיפויים האלה משתמשים ב-IngestAudienceMembersRequest ב-Data Manager API כקובץ עזר, אבל אתם יכולים להשתמש במיפויים האלה גם אם אתם ממירים את בקשת Google Ads API ל-RemoveAudienceMembersRequest או ל-RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) הערות
  • שדה customer_id
  • השדה customer_match_user_list_metadata של OfflineUserDataJob
  • ‫request header של login-customer-id
  • ‫request header של linked-customer-id
destinations שדות של לקוחות וקהלים
‫consent מתוך customer_match_user_list_metadata של OfflineUserDataJob consent הגדרות ברירת מחדל אופציונליות בנוגע להסכמה של משתמשים מקהל היעד בבקשה. אפשר לשנות את הערך הזה למשתמש ספציפי מקהל היעד על ידי הגדרת השדה consent של AudienceMember.
אין דוח מקביל encoding חובה: צריך להגדיר את Encoding שמשמש לערכי UserIdentifier.
אין דוח מקביל encryption_info צריך להגדיר אם הבקשה מכילה ערכים מוצפנים. פרטים נוספים זמינים במאמר בנושא הצפנה.
job_id אין דוח מקביל משתמשים ב-request_id שמוחזר בתגובה כדי לאחזר אבחון.
enable_partial_failure אין דוח מקביל ‫Data Manager API משתמש במודל שגיאות מסוג fast-fail. אם שדה כלשהו של IngestAudienceMembersRequest נכשל באימות, ה-Data Manager API דוחה את הבקשה כולה. אחזור שגיאות עיבוד באמצעות אבחון.
enable_warnings אין דוח מקביל ‫Data Manager API לא מדווח על אזהרות בתגובה. אפשר לאחזר אזהרות עיבוד באמצעות אבחון.
validate_only validate_only
operations audience_members רשימת המשתמשים מקהל היעד שרוצים להוסיף או להסיר. לפרטים נוספים, ראו את הקטע "שדות של פעולות".
אין דוח מקביל terms_of_service חובה. הגדרה שמציינת אם המשתמש אישר או דחה את התנאים וההגבלות של "התאמה ללקוחות".

שדות של לקוחות וקהלים

ב-Google Ads API אפשר להעלות משתמשים מקהל היעד רק לקהל אחד בכל משימה. בנוסף, אתם מגדירים את כותרות הבקשות login-customer-id ו-linked-customer-id לתרחישי אימות שונים.

‫Data Manager API תומך בשליחת משתמשים מכמה קהלים בבקשה אחת. ב-Data Manager API, אתם מציינים את פרטי ההתחברות ואת נתוני הלקוח המקושר באמצעות שדות של Destination במקום request header. במאמר הגדרת יעדים תוכלו לקרוא מידע נוסף על יעדים.

ב-Google Ads API, אפשר להסיר את כל החברים בקהל על ידי הגדרת השדה remove_all של OfflineUserDataJobOperation לערך true.

ב-Data Manager API, עושים את זה באמצעות שליחת RemoveAllAudienceMembersRequest. פרטים נוספים זמינים במדריך הסרת כל החברים.

כך ממפים את השדות של Google Ads API לקהל יחיד לשדות המקבילים ב-Destination:

Google Ads API Destination (Data Manager API) הערות
customer_id של הבקשה operating_account מגדירים את account_id כמספר הלקוח של הקהל. מגדירים את account_type של operating_account לערך GOOGLE_ADS.
‫request header של developer-token אין דוח מקביל ב-Data Manager API לא משתמשים בקודי מפתח. גם ב-Google Ads API אין יותר צורך בהם.
‫request header של login-customer-id login_account מגדירים את account_id למספר הלקוח של חשבון ההתחברות. מגדירים את account_type לערך GOOGLE_ADS אם החשבון שמתחברים אליו הוא חשבון Google Ads, או לערך DATA_PARTNER אם החשבון שמתחברים אליו הוא חשבון של שותף נתונים.
‫request header של linked-customer-id linked_account אם אתם ניגשים אל operating_account באמצעות קישור שותף, הגדירו את account_id למספר הלקוח של החשבון המקושר והגדירו את account_type ל-DATA_PARTNER. אחרת, אל תגדירו את השדה linked_account.
‫user_list מתוך customer_match_user_list_metadata של OfflineUserDataJob product_destination_id חובה. מוגדר למזהה המספרי של הקהל. אל תשתמשו בשם המשאב של UserList.
אין דוח מקביל reference מזהה שמוגדר על ידי המשתמש ל-Destination. צריך להגדיר את השדה הזה אם שולחים משתמשים מכמה קהלי יעד בבקשה אחת.

שדות של פעולות

‫Data Manager API מכיל שיטות נפרדות להוספה ולהסרה של משתמשים מקהל היעד. לעומת זאת, השדה AddOfflineUserDataJobOperationsRequest ב-Google Ads API מכיל רשימה של operations, שכל אחד מהם מוסיף חבר, מסיר חבר או מסיר את כל החברים, בהתאם לסוג הפעולה. כאן מפורט המיפוי של כל סוג פעולה ל-method המתאים ב-Data Manager API:

OfflineUserDataJobOperation (Google Ads API) IngestionService (Data Manager API) הערות
create IngestAudienceMembers פרטים נוספים זמינים בקטע "שדות של משתמשים מקהל היעד".
remove RemoveAudienceMembers פרטים נוספים זמינים בקטע "שדות של משתמשים מקהל היעד".
remove_all RemoveAllAudienceMembers פרטים נוספים זמינים בקטע הסרת כל המשתמשים מקהל היעד.

שדות של משתמשים מקהל היעד

UserData (Google Ads API) AudienceMember (Data Manager API) הערות
consent consent

הגדרה לציון ההסכמה של המשתמש מקהל היעד.

שני ממשקי ה-API משתמשים באובייקט Consent דומה (ad_user_data, ad_personalization).

ב-Data Manager API, אפשר גם להגדיר הסכמה לכל המשתמשים מקהל היעד בבקשה על ידי הגדרת השדה consent ברמת הבקשה.

transaction_attribute אין מקבילה. לא רלוונטי להתאמה ללקוחות.
user_attribute אין מקבילה. לא רלוונטי להתאמה ללקוחות.
user_identifiers
  • mobile_data
  • user_id_data
  • composite_data
    • user_data
    • ip_data

מאכלסים את השדה שתואם לסוג הנתונים ששולחים לגבי המשתמשים מקהל היעד. פרטים נוספים זמינים במאמר בנושא שדות של מזהי משתמשים.

שדות של מזהי משתמשים

ב-Google Ads API, בין שאתם שולחים פרטים ליצירת קשר, Mobile ID (mID) או מזהי משתמשים, אתם משתמשים ב-UserIdentifier. ‫Data Manager API משתמש בגישה שונה, עם שדות שונים לכל סוג של נתונים.

ב-Data Manager API, מאכלסים את השדה שתואם לסוג הנתונים ששולחים:

פרטים ליצירת קשר

אם משתמשים בפרטים ליצירת קשר כמו כתובת אימייל, מספר טלפון או כתובת, מגדירים את composite_data בתור CompositeData עם רשומה נפרדת ב-user_data.user_identifiers לכל פריט של פרטים ליצירת קשר.

עדיין יש תמיכה ב-user_data, אבל מומלץ להשתמש ב-composite_data כדי לוודא שהשילוב מוכן לשיפורים עתידיים. פרטים נוספים זמינים במאמר נתונים מורכבים.

UserIdentifier (Google Ads API) UserIdentifier (Data Manager API) הערות
address_info address פרטים נוספים זמינים בקטע שדות כתובת.
hashed_email email_address מגדירים את כתובת האימייל בפורמט הנכון ומגובבת. אפשר גם להצפין את כתובת האימייל המגובבת.
hashed_phone_number phone_number צריך להגדיר את מספר הטלפון בפורמט הנכון ואחרי גיבוב. אתם יכולים גם להצפין את מספר הטלפון המגובב.
user_identifier_source אין מקבילה.

שדות כתובת

אלה מיפויי השדות בין OfflineUserAddressInfo ב- Google Ads API לבין AddressInfo ב- Data Manager API. צריך להשתמש במיפויים האלה אם משתמשים בפרטים ליצירת קשר כדי לאכלס את הקהל של ההתאמה ללקוחות.

OfflineUserAddressInfo (Google Ads API) AddressInfo (Data Manager API) הערות
city אין מקבילה.
country_code region_code חובה
hashed_first_name given_name

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

hashed_last_name family_name

חובה. מגדירים את שם המשפחה בפורמט הנכון ומגובב. אפשר גם להצפין את שם המשפחה המגובב.

hashed_street_address אין מקבילה.
postal_code postal_code חובה
state אין מקבילה.

כתובת IP

ב-Data Manager API אפשר לכלול כתובות IP בהעלאות של התאמה ללקוחות, בנוסף למזהי משתמשים. הם מסופקים ב-CompositeData, שכולל את UserData ואת IpData. הוספת השדות האלה יחד יכולה לעזור לשפר את אחוז הלקוחות לטירגוט.

פרטים נוספים זמינים במאמר הטמעת כתובות IP לצורך התאמה ללקוחות.

Google Ads API CompositeData (Data Manager API) הערות
אין מקבילה. ip_data.ip_address צריך להגדיר את כתובת ה-IPv4 או ה-IPv6 הגולמית. אפשר לעיין בהנחיות בנושא פורמט של כתובת IP.
אין מקבילה. ip_data.observe_start_time מגדירים את חותמת הזמן בפורמט RFC 3339 שבה כתובת ה-IP נצפתה לראשונה.
אין מקבילה. ip_data.observe_end_time מוגדרת לחותמת הזמן בפורמט RFC 3339 שבה כתובת ה-IP נצפתה בפעם האחרונה.
user_identifiers user_data צריך להגדיר לאובייקט UserData.

Mobile ID (mID)

אם משתמשים ב-Mobile ID (mID), צריך להגדיר את mobile_data בתור MobileData עם רשומה ב-mobile_ids לכל מזהה.

UserIdentifier (Google Ads API) MobileData (Data Manager API) הערות
mobile_id mobile_ids מגדירים את רשימת מזהי המכשירים הניידים (mID) של המשתמש מקהל היעד.

ב-Google Ads API, מוסיפים נפרד UserIdentifier עם mobile_id לכל Mobile ID (mID) של משתמש מקהל היעד. ב-Data Manager API, מוסיפים MobileData יחיד עם mobile_ids שמוגדר לרשימה של כל ה-Mobile ID (mID) של המשתמש מקהל היעד.

user_identifier_source אין מקבילה.

מזהי משתמשים

אם משתמשים במזהי משתמשים, מגדירים את user_id_data בתור UserIdData, ומגדירים את user_id בתור מזהה המשתמש של משתמש מקהל היעד.

UserIdentifier (Google Ads API) UserIdData (Data Manager API) הערות
third_party_user_id user_id

ב-Google Ads API, מוסיפים נפרד UserIdentifier עם third_party_user_id לכל מזהה משתמש של המשתמש מקהל היעד.

ב-Data Manager API, מגדירים את השדה user_id_data כ-UserIdData, ומגדירים את השדה user_id כמזהה המשתמש של משתמש מקהל היעד. אי אפשר לשלוח כמה מזהי משתמשים לאותו משתמש מקהל היעד.

user_identifier_source אין מקבילה.