از نگاشت‌های فیلد برای ارتقا دادن هر مرحله از گردش کار «مطابقت مشتری» از Google Ads API به Data Manager API استفاده کنید:
نگاشت‌های فیلد مدیریت مخاطب حاوی نگاشت‌های فیلد برای ایجاد، به‌روزرسانی، و بازیابی مخاطبان است.
نگاشت‌های فیلد جذب حاوی نگاشت‌های فیلد برای افزودن یا برداشتن اعضای مخاطب است.
اصالت‌سنجی
Data Manager API به اعتبارنامه‌هایی با دامنه متفاوت از Google Ads API نیاز دارد. مراحل موجود در راه‌اندازی دسترسی به 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، نام منبع
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 از
مدل خطای
شکست سریع استفاده می‌کند. اگر هریک از فیلدهای
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 |
بدون معادل | برای Data Manager API به کد توسعه‌دهنده نیازی نیست. |
سرایند درخواست login-customer-id |
login_account |
account_id را روی شناسه مشتری حساب
ورود به سیستم تنظیم کنید. اگر حساب ورود به سیستم حساب Google Ads است، account_type را روی 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. اگر اعضای مخاطب را برای چندین مخاطب در یک درخواست ارسال می‌کنید، این فیلد را تنظیم کنید.
|
فیلدهای عملیات
Data Manager API حاوی روش‌های جداگانه‌ای برای افزودن و برداشتن اعضای مخاطب است. درمقابل،
AddOfflineUserDataJobOperationsRequest در
Google Ads API حاوی فهرستی از operations است که هرکدام از آن‌ها براساس نوع عملیات،
عضوی را اضافه می‌کند، عضوی را برمی‌دارد، یا همه اعضا را برمی‌دارد. در اینجا نگاشت هر نوع عملیات به روش مربوطه آن در 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 |
برای مشخص کردن موافقت عضو مخاطب تنظیم کنید. هر دو میانای برنامه‌سازی کاربردی از شیء برای Data Manager API، می‌توانید با تنظیم فیلد |
transaction_attribute |
معادل ندارد. | برای «مطابقت مشتری» قابل‌اجرا نیست. |
user_attribute |
معادل ندارد. | برای «مطابقت مشتری» قابل‌اجرا نیست. |
user_identifiers |
|
فیلد مربوط به نوع داده‌ای را که برای اعضای مخاطب ارسال می‌کنید پر کنید. برای جزئیات، فیلدهای شناسه کاربر را ببینید. |
فیلدهای شناسه کاربر
در 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 را روی
MobileData با
ورودی در mobile_ids برای هر شناسه تنظیم کنید.
UserIdentifier
(Google Ads API)
|
MobileData
(Data Manager API)
|
یادداشت‌ها |
|---|---|---|
mobile_id |
mobile_ids |
به فهرست
شناسه‌های تلفن همراه
برای عضو مخاطب تنظیم شده است.
در 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 |
معادل ندارد. |