מיפוי שדות

משתמשים במיפוי השדות כדי לשדרג כל שלב בתהליך העבודה של התאמה ללקוחות מ-Google Ads API ל-Data Manager 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 לIngestAudienceMembersRequest המקביל ב-Data Manager API.

שדות של בקשות

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) הערות
  • customer_id שדה
  • השדה customer_match_user_list_metadata של OfflineUserDataJob
  • כותרת הבקשה developer-token
  • כותרת הבקשה login-customer_id
  • כותרת הבקשה 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 לא תומך בכשל חלקי. אם אחד מהשדות של 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 במקום באמצעות כותרות של בקשות. מידע נוסף על יעדים זמין במאמר הגדרת יעדים.

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

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

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

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

ההגדרה היא שם המשפחה בפורמט מגובב. אפשר גם להצפין את שם המשפחה שעבר גיבוב.
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 אין מקבילה.
הקודם
שלבים לשדרוג