العرض تم إيقاف الإصدار الثاني من Video 360 API. استخدام الشاشة & الإصدار 3 من Video 360 API بدلاً من ذلك. للحصول على تعليمات حول نقل البيانات من الإصدار 2 إلى الإصدار 3، يُرجى الاطّلاع على دليل نقل البيانات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تحميل جماهير مطابقة العملاء

يمكنك إنشاء شرائح جمهور مطابقة العملاء باستخدام معلومات جهات اتصال العميل التي تم تحميلها أو أرقام تعريف الأجهزة الجوّالة باستخدام واجهة برمجة التطبيقات Display & Video 360 API. توضّح هذه الصفحة كيفية إنشاء شريحة جمهور أوّلية مستندة إلى ميزة "مطابقة العملاء" وإلحاق بيانات عملاء جديدة بشريحة الجمهور الحالية باستخدام واجهة برمجة التطبيقات في "مساحة العرض والفيديو 360".

إعداد بيانات المستخدمين

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

تجزئة البيانات الحسّاسة

يتم إنشاء بعض شرائح الجمهور المستندة إلى "مطابقة العملاء" باستخدام معلومات حساسة تتعلّق بجهات اتصال العملاء. تتطلّب "مساحة العرض والفيديو 360" تجزئة البيانات الحسّاسة باستخدام خوارزمية SHA256 قبل تحميلها. يجب تجزئة حقول البيانات التالية قبل التحميل:

الاسم الأول
اسم العائلة
عناوين البريد الإلكتروني
أرقام الهواتف

يجب عدم تجزئة الرموز البريدية ورموز البلدان قبل تحميلها. تؤدي محاولة تحميل بيانات العملاء غير المشفَّرة إلى ظهور خطأ.

قبل تجزئة البيانات، تأكَّد من استيفاء الشروط التالية:

يجب إزالة أي مسافات بيضاء من قيم الاسم الأول واسم العائلة وعنوان البريد الإلكتروني.
يجب كتابة جميع القيم بأحرف صغيرة.
يجب تنسيق جميع أرقام الهواتف باستخدام تنسيق E.164 ويجب أن تشمل رمز الاتصال بالبلد.

ضبط موافقة المستخدم

عند تحميل بيانات المستخدمين، استخدِم حقول consent في عناصر ContactInfoList أو MobileDeviceIdList المقدَّمة لنقل إشارات الموافقة التي منحها المستخدمون المدرَجون.

يؤدي ضبط أيّ من الحقلين في عنصر Consent على CONSENT_STATUS_DENIED إلى حدوث خطأ.

يتم ضبط إشارات الموافقة لجميع المستخدِمين الذين تمت إضافتهم في طلب واحد firstAndThirdPartyAudiences.create أو firstAndThirdPartyAudiences.editCustomerMatchMembers. يجب تحميل المستخدِمين الذين لديهم إشارات موافقة مختلفة في طلبات مفصّلة.

إنشاء شريحة جمهور من خلال ميزة "مطابقة العملاء"

يمكن إنشاء شريحة جمهور من خلال ميزة "مطابقة العملاء" باستخدام الطريقة firstAndThirdPartyAudiences.create. يجب الإقرار بأنّ الجمهور هو جمهور تابع للطرف الأول، ويجب أن يكون لديه audienceType من CUSTOMER_MATCH_CONTACT_INFO أو CUSTOMER_MATCH_DEVICE_ID. يجب أن يتم تقديم بيانات "مطابقة العملاء" باستخدام الحقل المناسب ضمن حقل الائتلاف members.

في ما يلي مثال على كيفية إنشاء شريحة جمهور جديدة من خلال ميزة "مطابقة العملاء" استنادًا إلى معلومات الاتصال، ومدة اشتراك تبلغ 540 يومًا باستخدام قائمة مقدَّمة من أرقام هواتف مجزّأة:

Java

// Create Customer Match audience object.
FirstAndThirdPartyAudience customerMatchAudience =
    new FirstAndThirdPartyAudience()
        .setDisplayName(display-name)
        .setFirstAndThirdPartyAudienceType(
            "FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY"
        )
        .setAudienceType("CUSTOMER_MATCH_CONTACT_INFO")
        .setMembershipDurationDays(540L);

// Build list of contact information objects.
ContactInfoList contactInfoList = new ContactInfoList();
ArrayList<ContactInfo> contactInfos = new ArrayList<ContactInfo>();
for (String hashedPhoneNumber : list-of-hashed-phone-numbers) {
  ContactInfo contactInfo = new ContactInfo();
  ArrayList<String> phoneNumberList = new ArrayList<String>();
  phoneNumberList.add(hashedPhoneNumber);
  contactInfo.setHashedPhoneNumbers(phoneNumberList);
  contactInfos.add(contactInfo);
}
contactInfoList.setContactInfos(contactInfos);

// Build consent object for passing consent if granted by the end user.
Consent consent =
    new Consent()
        .setAdUserData(ad-user-data-consent)
        .setAdPersonalization(ad-personalization-consent);
ContactInfoList.setConsent(consent);

// Assign contact info list to Customer Match audience.
customerMatchAudience.setContactInfoList(contactInfoList);

// Create Customer Match audience.
FirstAndThirdPartyAudience response =
    service
        .firstAndThirdPartyAudiences()
        .create(customerMatchAudience)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display name of new audience.
System.out.printf(
    "Customer Match audience %s was created.",
    response.getName()
);

Python

# Build list of Contact Info objects
contact_infos = []
for hashed_phone_number in list-of-hashed-phone-numbers:
  contact_infos.append({'hashedPhoneNumbers': [hashed_phone_number]})

# Create a Customer Match first- and third-party audience object.
audience_obj = {
    'displayName': display-name,
    'firstAndThirdPartyAudienceType':
        'FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY',
    'audienceType': 'CUSTOMER_MATCH_CONTACT_INFO',
    'membershipDurationDays': 540,
    'contactInfoList': {
        'contactInfos': [
            contact_infos
        ],
        'consent': {
            'adUserData': ad-user-data-consent,
            'adPersonalization': ad-personalization-consent
        }
    }
}

# Build and execute request.
audience = service.firstAndThirdPartyAudiences().create(
    advertiserId=advertiser-id,
    body=audience_obj
).execute()

# Display name of new audience.
print('Customer Match audience %s was created.' % audience["name"])

PHP

// Create a Customer Match first- and third-party audience object.
$audience = new Google_Service_DisplayVideo_FirstAndThirdPartyAudience();
$audience->setDisplayName(display-name);
$audience->setFirstAndThirdPartyAudienceType(
    'FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY'
);
$audience->setAudienceType('CUSTOMER_MATCH_CONTACT_INFO');
$audience->setMembershipDurationDays(540);

// Build list of contact information objects.
$contactInfoList = new Google_Service_DisplayVideo_ContactInfoList();
$contactInfos = array();
foreach (list-of-hashed-phone-numbers as $hashedPhoneNumber) {
    $contactInfo = new Google_Service_DisplayVideo_ContactInfo();
    $contactInfo->setHashedPhoneNumbers(array($hashedPhoneNumber));
    $contactInfos[] = $contactInfo;
}
$contactInfoList->setContactInfos($contactInfos);

// Build consent object for passing consent if granted by the end user.
$consent = new Google_Service_DisplayVideo_Consent();
$consent->setAdUserData(ad-user-data-consent);
$consent->setAdPersonalization(ad-personalization-consent);
$contactInfoList->setConsent($consent);

// Assign contactInfoList to audience object.
$audience->setContactInfoList($contactInfoList);

// Call the API, creating the audience.
$result = $this->service->firstAndThirdPartyAudiences->create(
    $audience,
    array('advertiserId' => advertiser-id)
);

// Display name of new audience.
printf('Customer Match audience %s was created.', $result['name']);

تعديل عضوية شريحة جمهور "مطابقة العملاء"

إذا حدّدت عملاء إضافيين تريد استهدافهم، أو كنت بحاجة إلى تجديد عضويات العملاء الحالية في شريحة الجمهور، أو أردت إزالة عملاء من شريحة جمهور، يمكنك تعديل بيانات العملاء في شريحة جمهور حالية من "مطابقة العملاء" باستخدام firstAndThirdPartyAudiences.editCustomerMatchMembers الطريقة. يمكنك إضافة عملاء إلى قائمة باستخدام حقل الربط added_members وإزالة عملاء من قائمة باستخدام حقل الربط removed_members.

لا يمكن أن يؤدي طلب واحد firstAndThirdPartyAudiences.editCustomerMatchMembers إلا إلى إضافة أعضاء إلى قائمة أو إزالتهم منها. يؤدي تقديم طلب واحد يحاول تنفيذ كليهما إلى ظهور خطأ INVALID_ARGUMENT.

في ما يلي مثال على كيفية إضافة عميل واحد كعضو في شريحة حالية من جمهور "مطابقة العملاء" استنادًا إلى معلومات الاتصال باستخدام بيانات العنوان البريدي المقدَّمة:

Java

// Create an edit members request object.
EditCustomerMatchMembersRequest editCustomerMatchMembersRequest =
    new EditCustomerMatchMembersRequest()
        .setAdvertiserId(advertiser-id);

// Build contact information object to add to audience.
ContactInfoList contactInfoList = new ContactInfoList();
ArrayList<ContactInfo> contactInfos = new ArrayList<ContactInfo>();
ContactInfo contactInfo =
    new ContactInfo()
        .setHashedFirstName(hashed-customer-first-name)
        .setHashedLastName(hashed-customer-last-name)
        .setZipCodes(customer-zip-codes-list)
        .setCountryCode(customer-country-code);
contactInfos.add(contactInfo);
contactInfoList.setContactInfos(contactInfos);

// Build consent object for passing consent if granted by the end user.
Consent consent =
    new Consent()
        .setAdUserData(ad-user-data-consent)
        .setAdPersonalization(ad-personalization-consent);
ContactInfoList.setConsent(consent);

// Assign contact info list to request body.
editCustomerMatchMembersRequest.setAddedContactInfoList(contactInfoList);

// Edit Customer Match audience membership.
EditCustomerMatchMembersResponse response =
    service
        .firstAndThirdPartyAudiences()
        .editCustomerMatchMembers(
            audience-id,
            editCustomerMatchMembersRequest
        )
        .execute();

// Display ID of updated audience.
System.out.printf(
    "The membership of Customer Match audience ID %s was edited.",
    response.getFirstAndThirdPartyAudienceId()
);

Python

# Create an edit members request object.
edit_member_request_obj = {
    'advertiserId': advertiser-id,
    'addedContactInfoList': {
        'contactInfos': [
            {
                'hashedFirstName': hashed-customer-first-name,
                'hashedLastName': hashed-customer-last-name,
                'countryCode': customer-country-code,
                'zipCodes': customer-zip-codes-list
            }
        ],
        'consent': {
          'adUserData': ad-user-data-consent,
          'adPersonalization': ad-personalization-consent
        }
    }
}

# Build and execute request.
response = service.firstAndThirdPartyAudiences().editCustomerMatchMembers(
    firstAndThirdPartyAudienceId=audience-id,
    body=edit_member_request_obj
).execute()

# Display ID of updated audience.
print('The membership of the Customer Match audience ID %s was updated.'
      % response["firstAndThirdPartyAudienceId"])

PHP

// Create an edit members request object.
$editMemberRequest =
    new Google_Service_DisplayVideo_EditCustomerMatchMembersRequest();
$editMemberRequest->setAdvertiserId(advertiser-id);

// Build contact information object to add to audience.
$contactInfoList = new Google_Service_DisplayVideo_ContactInfoList();
$contactInfos = array();
$contactInfo = new Google_Service_DisplayVideo_ContactInfo();
$contactInfo->setHashedFirstName(hashed-customer-first-name);
$contactInfo->setHashedLastName(hashed-customer-last-name);
$contactInfo->setCountryCode(customer-country-code);
$contactInfo->setZipCodes(array(customer-zip-codes-list));
$contactInfos[] = $contactInfo;
$contactInfoList->setContactInfos($contactInfos);

// Build consent object for passing consent if granted by the end user.
$consent = new Google_Service_DisplayVideo_Consent();
$consent->setAdUserData(ad-user-data-consent);
$consent->setAdPersonalization(ad-personalization-consent);
$contactInfoList->setConsent($consent);

// Assign contactInfoList to edit members request body.
$editMemberRequest->setAddedContactInfoList($contactInfoList);

// Call the API, editing the audience membership.
$response = $this
    ->service
    ->firstAndThirdPartyAudiences
    ->editCustomerMatchMembers(
        audience-id,
        $editMemberRequest
    );

// Display ID of updated audience.
printf(
    'The membership of Customer Match audience ID %s was edited',
    $result['firstAndThirdPartyAudienceId']
);

الجمهور المستهدف‬‏‫