از نگاشت‌های فیلد برای ارتقا دادن هر مرحله از گردش کار «تطابق مشتری» از Google Ads API به Data Manager API استفاده کنید:
نگاشت‌های فیلد مدیریت مخاطبان حاوی نگاشت‌های فیلد برای ایجاد، به‌روزرسانی، و بازیابی مخاطبان است.
نگاشت‌های فیلد انتقال داده شامل نگاشت‌های فیلد برای افزودن یا برداشتن اعضای مخاطب است.
اصالت‌سنجی
Data Manager API به اعتبارنامه‌هایی با دامنه‌ای متفاوت از Google Ads 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»، هنگام ایجاد مخاطب «مطابقت مشتری»، باید فیلد crm_based_user_list را روی
CrmBasedUserListInfo تنظیم کنید.
در «میانای برنامه‌سازی کاربردی مدیر داده»، با تنظیم فیلد 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 است.
شناسه‌های تلفن همراه
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 است. -
key_spaceرا رویIOSیاANDROIDتنظیم کنید. Data Manager API به این مقدار نیاز دارد. این با «میانای برنامه‌سازی کاربردی Google Ads» متفاوت است، جایی که فضای کلید ازapp_idاستنباط می‌شود. -
app_idرا روی رشته‌ای تنظیم کنید که برنامه تلفن همراهی را که داده‌ها از آن جمع‌آوری شده است به‌طور یکتا شناسایی می‌کند. از همان قالبی استفاده کنید که برایapp_idدر «میانای برنامه‌سازی کاربردی Google Ads» استفاده می‌کنید.
-
شناسه‌های کاربر
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 است.
نام‌های منبع
قالب نام منبع «میانای برنامه‌سازی کاربردی مدیر داده» با قالب نام منبع Google Ads API متفاوت است.
- Google Ads API
در Google Ads API، نام منبع
UserListاز این قالب استفاده می‌کند:customers/{customer_id}/userLists/{user_list_id}- میانای برنامه‌سازی کاربردی مدیر داده‌ها
در «میانای برنامه‌سازی کاربردی مدیر داده»، نام منبع
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 درستی‌سنجی نشود،
«میانای برنامه‌سازی کاربردی مدیر داده» کل درخواست را رد می‌کند. خطاهای پردازش را
بااستفاده از تشخیص خرابی بازیابی کنید.
|
enable_warnings |
معادل ندارد | «میانای برنامه‌سازی کاربردی مدیر داده» هشدارها را در پاسخ گزارش نمی‌کند. درحال بازیابی هشدارهای پردازش بااستفاده از عیب‌یابی‌ها. |
validate_only |
validate_only |
|
operations |
audience_members |
فهرست اعضای مخاطب برای افزودن یا برداشتن. برای جزئیات، بخش فیلدهای عملیات را ببینید. |
| معادل ندارد | terms_of_service |
الزامی. تنظیم شود تا نشان دهد کاربر شرایط خدمات «تطابق مشتری» را پذیرفته یا رد کرده است. |
فیلدهای مشتری و مخاطب
Google Ads API فقط از بارگذاری اعضای مخاطب در یک مخاطب
در هر کار پشتیبانی می‌کند.علاوه‌براین، سرصفحه درخواست developer-token الزامی است و شما
سرصفحه‌های درخواست login-customer-id و linked-customer-id را برای سناریوهای درستی‌سنجی مختلف تنظیم می‌کنید.
«میانای برنامه‌سازی کاربردی مدیر داده» از ارسال اعضای مخاطب برای چندین مخاطب در
یک
درخواست پشتیبانی می‌کند.
Data Manager API به کد توسعه‌دهنده نیاز ندارد و اطلاعات ورود به سیستم و مشتری پیوندی را بااستفاده از فیلدهای Destination به‌جای سرایندهای درخواست مشخص می‌کنید. برای اطلاعات بیشتر درباره مقصدها،
پیکربندی مقصدها را بررسی کنید.
در «میانای برنامه‌سازی کاربردی Google Ads»، می‌توانید همه اعضای مخاطب را با
تنظیم کردن فیلد remove_all در
OfflineUserDataJobOperation روی true بردارید.
در Data Manager API، با ارسال
RemoveAllAudienceMembersRequest به این هدف می‌رسید.
برای جزئیات، راهنمای حذف همه اعضا را ببینید.
در اینجا نحوه نگاشت فیلدهای «میانای برنامه‌سازی کاربردی Google Ads» برای یک مخاطب
به فیلدهای معادل در Destination آمده است:
| Google Ads API | Destination
(Data Manager API) |
یادداشت‌ها |
|---|---|---|
customer_id درخواست |
operating_account |
account_id را روی شناسه مشتری مخاطب تنظیم کنید. account_type operating_account را روی
GOOGLE_ADS تنظیم کن. |
سرایند درخواست developer-token |
معادل ندارد | برای «میانای برنامه‌سازی کاربردی مدیر داده»، کد توسعه‌دهنده لازم نیست. |
سرایند درخواست 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 |
برای مشخص کردن موافقت عضو مخاطب تنظیم کنید. هر دو میانای برنامه‌سازی کاربردی از شیء برای «میانای برنامه‌سازی کاربردی مدیر داده»، می‌توانید با تنظیم فیلد |
transaction_attribute |
معادل ندارد. | برای «مطابقت مشتری» قابل‌اجرا نیست. |
user_attribute |
معادل ندارد. | برای «مطابقت مشتری» قابل‌اجرا نیست. |
user_identifiers |
|
فیلدی را که با نوع داده‌ای که برای اعضای مخاطب ارسال می‌کنید مطابقت دارد تکمیل کنید. برای جزئیات، فیلدهای شناسه کاربر را ببینید. |
فیلدهای شناسه کاربر
در Google Ads API، چه اطلاعات تماس، شناسه‌های تلفن همراه،
یا شناسه‌های کاربر ارسال کنید، از UserIdentifier استفاده می‌کنید. «میانای برنامه‌سازی کاربردی مدیر داده» از رویکردی متفاوت با فیلدهای مختلف برای هر نوع داده استفاده می‌کند.
در «میانای برنامه‌سازی کاربردی مدیر داده‌ها»، فیلدی را که با نوع داده‌ای که ارسال می‌کنید مطابقت دارد تکمیل کنید:
اطلاعات تماس
اگر از اطلاعات تماس مثل نشانی ایمیل، شماره تلفن، یا
اطلاعات نشانی استفاده می‌کنید، 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 و
AddressInfo در
میانای برنامه‌سازی کاربردی «مدیر داده» ارائه شده است. اگر از اطلاعات تماس برای پر کردن مخاطب «تطابق مشتری» استفاده می‌کنید، از این نگاشت‌ها استفاده کنید.
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
«میانای برنامه‌سازی کاربردی مدیر داده» از افزودن نشانی‌های 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»، برای هر شناسه تلفن همراه عضو مخاطب، جداگانه
|
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»، برای هر شناسه کاربر عضو مخاطب، جداگانه
در «میانای برنامه‌سازی کاربردی مدیر داده»، فیلد |
user_identifier_source |
معادل ندارد. |