כדי לשדרג כל שלב בתהליך העבודה של ההתאמה ללקוחות מ-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)
|
הערות |
|---|---|---|
|
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 משתמשים באובייקט ב-Data Manager API, אפשר גם להגדיר הסכמה לכל המשתמשים מקהל היעד בבקשה על ידי הגדרת השדה |
transaction_attribute |
אין מקבילה. | לא רלוונטי להתאמה ללקוחות. |
user_attribute |
אין מקבילה. | לא רלוונטי להתאמה ללקוחות. |
user_identifiers |
|
מאכלסים את השדה שתואם לסוג הנתונים ששולחים לגבי המשתמשים מקהל היעד. פרטים נוספים זמינים במאמר בנושא שדות של מזהי משתמשים. |
שדות של מזהי משתמשים
ב-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, מוסיפים נפרד
|
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, מוסיפים נפרד
ב-Data Manager API, מגדירים את השדה |
user_identifier_source |
אין מקבילה. |