מיפוי שדות

כדי לשדרג כל שלב בתהליך העבודה של ההתאמה ללקוחות מ-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.

מזהים לנייד

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 כקובץ עזר, אבל אפשר להשתמש בהם גם אם ממירים את בקשת ה-API ב-Google Ads API ל-RemoveAudienceMembersRequest או ל-RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest ‫(Google Ads API) IngestAudienceMembersRequest (Data Manager API) הערות
  • שדה customer_id
  • השדה customer_match_user_list_metadata של OfflineUserDataJob
  • developer-token request header
  • login-customer_id request header
  • linked-customer-id request header
 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 משתמש במודל שגיאות של 'כשל מהיר'. אם אחד מהשדות של IngestAudienceMembersRequest לא עובר את האימות, Data Manager API דוחה את הבקשה כולה. אחזור שגיאות עיבוד באמצעות אבחון.
enable_warnings אין דוח מקביל ה-Data Manager API לא מדווח על אזהרות בתשובה. אפשר לאחזר אזהרות עיבוד באמצעות אבחון.
validate_only validate_only
operations audience_members רשימת חברי הקהל להוספה או להסרה. פרטים נוספים זמינים בקטע שדות של פעולות.
אין דוח מקביל terms_of_service חובה. הערך שמוגדר מציין שהמשתמש אישר או דחה את התנאים וההגבלות של התאמה ללקוחות.

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

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

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

ב-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.
developer-token request header אין דוח מקביל לא נדרש קוד מפתח ל-Data Manager API.
login-customer-id request header login_account מגדירים את account_id למספר הלקוח של החשבון שמשמש לכניסה. מגדירים את account_type לערך GOOGLE_ADS אם חשבון הכניסה הוא חשבון Google Ads, או לערך DATA_PARTNER אם חשבון הכניסה הוא חשבון של שותף נתונים.
linked-customer-id request header 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. צריך להגדיר את השדה הזה אם שולחים חברים בקהל לכמה קהלים בבקשה אחת.

שדות פעולה

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

OfflineUserDataJobOperation (Google Ads API) ‫IngestionService method (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, כששולחים פרטים ליצירת קשר, מזהים לנייד או מזהים משתמשים, משתמשים ב-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

חובה. ההגדרה היא formatted and hashed 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_data ל-a MobileData עם רשומה ב-mobile_ids לכל מזהה.

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

ב-Google Ads API, מוסיפים נפרד UserIdentifier עם mobile_id לכל מזהה לנייד של משתמש מקהל היעד. ב-Data Manager API, מוסיפים single MobileData עם mobile_ids שמוגדר לרשימה של כל המזהים לניידים של משתמש מקהל היעד.

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 אין מקבילה.
הקודם
שלבים לשדרוג