تعيينات الحقول

استخدِم عمليات ربط الحقول لترقية كل خطوة من خطوات سير عمل "مطابقة العملاء" من 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"، أو على 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

يتم ضبط هذا الحقل لتحديد الموافقة الخاصة بأحد أفراد الجمهور.

تستخدم كلتا واجهتَي برمجة التطبيقات عنصر 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 على MobileData مع إدخال في mobile_ids لكل معرّف.

UserIdentifier (Google Ads API) MobileData (Data Manager API) ملاحظات
mobile_id mobile_ids يجب ضبطها على قائمة المعرّفات على الأجهزة الجوّالة للمستخدِم المستهدف.

في Google Ads API، يمكنك إضافة معرّف منفصل UserIdentifier مع mobile_id لكل معرّف جهاز جوّال خاص بأحد أفراد شريحة الجمهور. في Data Manager API، أضِف معرّفًا 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 ما مِن مكافئ.
السابق
خطوات الترقية