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

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

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

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

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

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

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

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

يجب عدم تجزئة الرموز البريدية ورموز البلدان قبل التحميل. تؤدي محاولة تحميل بيانات العملاء غير المُجزّأة إلى حدوث خطأ.

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

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

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

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

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

تحذير: يجب إرسال إشارات الموافقة عند تحميل أعضاء جمهور "مطابقة العملاء" في المنطقة الاقتصادية الأوروبية (EEA) للتقيّد بسياسة موافقة المستخدم في الاتحاد الأوروبي واستخدام بيانات المستخدم في المنطقة الاقتصادية الأوروبية لتعبئة شرائح جمهور "مطابقة العملاء".

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

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

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

ملاحظة: يجب ملء الحقل membershipDurationDays عند إنشاء شرائح جمهور "مطابقة العملاء". يمكن تفعيل مدة عضوية غير محدودة من خلال ضبط قيمة الحقل على 10000.

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

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(10000L);

// 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': 10000,
    '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(10000);

// 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.

ملاحظة: يمكن تعديل حقول البيانات الوصفية لمعلومات الاتصال وشرائح جمهور "مطابقة العملاء" لرقم تعريف الجهاز، مثل displayName أو membershipDurationDays، باستخدام طريقة firstAndThirdPartyAudiences.patch.

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

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']
);