REST Resource: firstAndThirdPartyAudiences

المرجع: FirstAndrdParty Audience

تصِف قائمة مستخدمين من الطرف الأول أو الثالث المُستخدمة للاستهداف. يتم إنشاء شرائح جمهور الطرف الأول عن طريق استخدام بيانات العميل. يوفر موفرو بيانات تابعون لجهات خارجية شرائح جمهور الجهات الخارجية، ولا يمكن ترخيصها إلا للعملاء.

تمثيل JSON 
{
  "name": string,
  "firstAndThirdPartyAudienceId": string,
  "displayName": string,
  "description": string,
  "firstAndThirdPartyAudienceType": enum (FirstAndThirdPartyAudienceType),
  "audienceType": enum (AudienceType),
  "audienceSource": enum (AudienceSource),
  "membershipDurationDays": string,
  "displayAudienceSize": string,
  "activeDisplayAudienceSize": string,
  "youtubeAudienceSize": string,
  "gmailAudienceSize": string,
  "displayMobileAppAudienceSize": string,
  "displayMobileWebAudienceSize": string,
  "displayDesktopAudienceSize": string,
  "appId": string,

  // Union field members can be only one of the following:
  "contactInfoList": {
    object (ContactInfoList)
  },
  "mobileDeviceIdList": {
    object (MobileDeviceIdList)
  }
  // End of list of possible types for union field members.
}
الحقول
name

string

النتائج فقط. اسم المورد لجمهور الطرف الأول والطرف الثالث.
firstAndThirdPartyAudienceId

string (int64 format)

النتائج فقط. المعرّف الفريد لشريحة الجمهور التابعة للطرف الأول والجهة الخارجية. تم تعيينه من قِبل النظام.
displayName

string

الاسم المعروض لجمهور الطرف الأول والطرف الثالث.
description

string

تمثّل هذه السمة الوصف الذي يقدّمه المستخدم للجمهور.

لا يسري هذا الإعداد إلا على شرائح جمهور الطرف الأول.
firstAndThirdPartyAudienceType

enum (FirstAndThirdPartyAudienceType)

ما إذا كان الجمهور شريحة جمهور جديدة أم تابعة لجهة خارجية
audienceType

enum (AudienceType)

نوع الجمهور.
audienceSource

enum (AudienceSource)

النتائج فقط. مصدر الجمهور.
membershipDurationDays

string (int64 format)

المدة بالأيام التي يظل فيها الإدخال ضمن الجمهور بعد الحدث المؤهَّل. وإذا لم يكن للجمهور تاريخ انتهاء صلاحية، اضبط قيمة هذا الحقل على 10, 000. وبخلاف ذلك، يجب أن تكون قيمة المجموعة أكبر من 0 وأقل من أو تساوي 540.

لا يسري هذا الإعداد إلا على شرائح جمهور الطرف الأول.

يجب ملء هذا الحقل في حال استخدام إحدى قيم audienceType التالية:

  • CUSTOMER_MATCH_CONTACT_INFO
  • CUSTOMER_MATCH_DEVICE_ID
displayAudienceSize

string (int64 format)

النتائج فقط. حجم الجمهور المقدّر للشبكة الإعلانية.

إذا كان الحجم أقل من 1000، سيتم إخفاء الرقم وسيتم إرجاع الرقم 0 لأسباب تتعلق بالخصوصية. وإلا سيتم تقريب الرقم إلى رقمين مهمين.

تم إرجاعها فقط في طلب GET.
activeDisplayAudienceSize

string (int64 format)

النتائج فقط. حجم الجمهور المقدّر للشبكة الإعلانية في الشهر الماضي.

إذا كان الحجم أقل من 1000، سيتم إخفاء الرقم وسيتم إرجاع الرقم 0 لأسباب تتعلق بالخصوصية. وإلا سيتم تقريب الرقم إلى رقمين مهمين.

تم إرجاعها فقط في طلب GET.
youtubeAudienceSize

string (int64 format)

النتائج فقط. حجم الجمهور المقدّر لشبكة YouTube

إذا كان الحجم أقل من 1000، سيتم إخفاء الرقم وسيتم إرجاع الرقم 0 لأسباب تتعلق بالخصوصية. وإلا سيتم تقريب الرقم إلى رقمين مهمين.

لا يسري هذا الإعداد إلا على شرائح جمهور الطرف الأول.

تم إرجاعها فقط في طلب GET.
gmailAudienceSize

string (int64 format)

النتائج فقط. حجم الجمهور المقدّر لشبكة Gmail.

إذا كان الحجم أقل من 1000، سيتم إخفاء الرقم وسيتم إرجاع الرقم 0 لأسباب تتعلق بالخصوصية. وإلا سيتم تقريب الرقم إلى رقمين مهمين.

لا يسري هذا الإعداد إلا على شرائح جمهور الطرف الأول.

تم إرجاعها فقط في طلب GET.
displayMobileAppAudienceSize

string (int64 format)

النتائج فقط. حجم جمهور التطبيق المتوافق مع الأجهزة الجوّالة المقدّر في الشبكة الإعلانية.

إذا كان الحجم أقل من 1000، سيتم إخفاء الرقم وسيتم إرجاع الرقم 0 لأسباب تتعلق بالخصوصية. وإلا سيتم تقريب الرقم إلى رقمين مهمين.

لا يسري هذا الإعداد إلا على شرائح جمهور الطرف الأول.

تم إرجاعها فقط في طلب GET.
displayMobileWebAudienceSize

string (int64 format)

النتائج فقط. حجم جمهور الويب على الأجهزة الجوّالة المقدّر في "الشبكة الإعلانية".

إذا كان الحجم أقل من 1000، سيتم إخفاء الرقم وسيتم إرجاع الرقم 0 لأسباب تتعلق بالخصوصية. وإلا سيتم تقريب الرقم إلى رقمين مهمين.

لا يسري هذا الإعداد إلا على شرائح جمهور الطرف الأول.

تم إرجاعها فقط في طلب GET.
displayDesktopAudienceSize

string (int64 format)

النتائج فقط. حجم الجمهور المقدّر لأجهزة الكمبيوتر المكتبي في "الشبكة الإعلانية".

إذا كان الحجم أقل من 1000، سيتم إخفاء الرقم وسيتم إرجاع الرقم 0 لأسباب تتعلق بالخصوصية. وإلا سيتم تقريب الرقم إلى رقمين مهمين.

لا يسري هذا الإعداد إلا على شرائح جمهور الطرف الأول.

تم إرجاعها فقط في طلب GET.
appId

string

يتطابق appId مع نوع mobileDeviceId = الذي يتم تحميله.

ينطبق فقط على audienceType CUSTOMER_MATCH_DEVICE_ID
حقل الاتحاد members الأعضاء الأوليون لجمهور "مطابقة العملاء". يمكن أن يكون الحقل "members" واحدًا فقط مما يلي:
contactInfoList

object (ContactInfoList)

الإدخال فقط. قائمة بمعلومات الاتصال لتحديد الأفراد الأوليين من الجمهور.

ينطبق فقط على audienceType CUSTOMER_MATCH_CONTACT_INFO
mobileDeviceIdList

object (MobileDeviceIdList)

الإدخال فقط. قائمة بأرقام تعريف الأجهزة الجوّالة لتحديد أعضاء الجمهور الأولي.

ينطبق فقط على audienceType CUSTOMER_MATCH_DEVICE_ID

FirstAndThirdPartyAudienceType

الأنواع المحتملة لمورد الجمهور الأول والتابع لجهة خارجية.

عمليات التعداد
FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_UNSPECIFIED القيمة التلقائية عندما يكون النوع غير محدد أو غير معروف.
FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY يشير ذلك المصطلح إلى جمهور يتم إنشاؤه من خلال استخدام بيانات العميل.
FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_THIRD_PARTY شريحة الجمهور التي يوفّرها موفرو بيانات الأطراف الثالثة

AudienceType

أنواع شرائح الجمهور المحتملة.

عمليات التعداد
AUDIENCE_TYPE_UNSPECIFIED القيمة التلقائية عندما يكون النوع غير محدد أو غير معروف.
CUSTOMER_MATCH_CONTACT_INFO تم إنشاء الجمهور من خلال مطابقة العملاء بمعلومات الاتصال المعروفة.
CUSTOMER_MATCH_DEVICE_ID تم إنشاء الجمهور من خلال مطابقة العملاء بأرقام تعريف الأجهزة الجوّالة المعروفة.
CUSTOMER_MATCH_USER_ID تم إنشاء شريحة الجمهور من خلال مطابقة العملاء بأرقام تعريف المستخدمين المعروفة.
ACTIVITY_BASED

تم إنشاء شريحة الجمهور استنادًا إلى نشاط الحملة.
FREQUENCY_CAP

تم إنشاء شريحة الجمهور استنادًا إلى استبعاد عدد مرات الظهور التي تم عرضها فيها.
TAG_BASED تم إنشاء شريحة الجمهور استنادًا إلى المتغيّرات المخصّصة الملحقة بوحدة البكسل.
YOUTUBE_USERS تم إنشاء شريحة الجمهور استنادًا إلى التفاعلات السابقة مع الفيديوهات أو الإعلانات على YouTube أو قناة YouTube.
LICENSED نوع فرعي من نوع جمهور تابع لجهة خارجية.

AudienceSource

مصادر البيانات عن الجمهور المحتملة

عمليات التعداد
AUDIENCE_SOURCE_UNSPECIFIED قيمة تلقائية عندما يكون مصدر البيانات عن الجمهور غير محدّد أو عندما يكون غير معروف.
DISPLAY_VIDEO_360 تم إنشاؤها من "مساحة العرض والفيديو 360".
CAMPAIGN_MANAGER تم إنشاؤها من "مدير الحملة 360".
AD_MANAGER تم إنشاؤها من "مدير إعلانات Google".
SEARCH_ADS_360 تم إنشاؤها من "إعلانات شبكة البحث 360".
YOUTUBE تم إنشاؤها من YouTube.
ADS_DATA_HUB تم إنشاؤها من Ads Data Hub.

ContactInfoList

رسالة التفاف لقائمة معلومات الاتصال التي تحدد أعضاء جمهور مطابقة العملاء.

تمثيل JSON 
{
  "contactInfos": [
    {
      object (ContactInfo)
    }
  ],
  "consent": {
    object (Consent)
  }
}
الحقول
contactInfos[]

object (ContactInfo)

قائمة بكائنات "معلومات الاتصال" التي تحدّد أعضاء جمهور "مطابقة العملاء" يجب ألا يزيد عدد الأعضاء بعد تقسيم معلومات الاتصال عن 500,000.
consent

object (Consent)

الإدخال فقط. إعداد الموافقة للمستخدمين في contactInfos.

وفي حال ترك هذا الحقل بدون ضبط، يعني ذلك أنّه لم يتم تحديد الموافقة.

في حال ضبط الحقل adUserData أو adPersonalization على CONSENT_STATUS_DENIED، سيعرض الطلب رسالة خطأ.

ContactInfo

معلومات الاتصال التي تحدّد فردًا من جمهور "مطابقة العملاء"

تمثيل JSON 
{
  "hashedEmails": [
    string
  ],
  "hashedPhoneNumbers": [
    string
  ],
  "zipCodes": [
    string
  ],
  "hashedFirstName": string,
  "hashedLastName": string,
  "countryCode": string
}
الحقول
hashedEmails[]

string

قائمة تتضمّن عنوان البريد الإلكتروني المجزّأ باستخدام خوارزمية SHA256 للعضو. قبل التجزئة، أزِل المسافات البيضاء بالكامل وتأكَّد من أنّ السلسلة كلها بأحرف صغيرة.
hashedPhoneNumbers[]

string

قائمة بأرقام هواتف العضو المجزّأة باستخدام خوارزمية SHA256 قبل التجزئة، يجب أن تكون جميع أرقام الهواتف من خلال تنسيق E.164 وأن تتضمّن رمز الاتصال بالبلد.
zipCodes[]

string

قائمة بالرموز البريدية للعضو.

يجب أيضًا ضبطه باستخدام الحقول التالية:
hashedFirstName

string

تمّت تجزئة الاسم الأول للعضو باستخدام خوارزمية SHA256. قبل التجزئة، أزِل المسافات البيضاء بالكامل وتأكَّد من أنّ السلسلة كلها بأحرف صغيرة.

يجب أيضًا ضبطه باستخدام الحقول التالية:
hashedLastName

string

تتم تجزئة اسم العائلة للعضو باستخدام خوارزمية SHA256. قبل التجزئة، أزِل المسافات البيضاء بالكامل وتأكَّد من أنّ السلسلة كلها بأحرف صغيرة.

يجب أيضًا ضبطه باستخدام الحقول التالية:
countryCode

string

رمز بلد العضو

يجب أيضًا ضبطه باستخدام الحقول التالية:

ConsentStatus

حالة الموافقة

عمليات التعداد
CONSENT_STATUS_UNSPECIFIED لم يتم تحديد قيمة النوع أو غير معروفة في هذا الإصدار.
CONSENT_STATUS_GRANTED تم منح الموافقة.
CONSENT_STATUS_DENIED الموافقة مرفوضة.

MobileDeviceIdList

رسالة التفاف لقائمة من أرقام تعريف الأجهزة الجوّالة التي تحدّد أعضاء جمهور مطابقة العملاء.

تمثيل JSON 
{
  "mobileDeviceIds": [
    string
  ],
  "consent": {
    object (Consent)
  }
}
الحقول
mobileDeviceIds[]

string

قائمة بأرقام تعريف الأجهزة الجوّالة التي تحدّد أعضاء جمهور مطابقة العملاء. يجب ألا يزيد حجم mobileDeviceId عن 500,000.
consent

object (Consent)

الإدخال فقط. إعداد الموافقة للمستخدمين في mobileDeviceIds.

وفي حال ترك هذا الحقل بدون ضبط، يعني ذلك أنّه لم يتم تحديد الموافقة.

في حال ضبط الحقل adUserData أو adPersonalization على CONSENT_STATUS_DENIED، سيعرض الطلب رسالة خطأ.

الطُرق

create

 ينشئ FirstAndrdParty Audience

editCustomerMatchMembers

 تُعدِّل قائمة الأعضاء لشريحة جمهور "مطابقة العملاء".

get

 الحصول على جمهور للطرف الأول وجهة خارجية

list

 يسرد شرائح الجمهور الأولى وشرائح الجمهور التابعة لجهة خارجية.

patch

 لتعديل بيانات FirstAndrdParty Audience حالية