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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.

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

Java

// Create Customer Match audience object.
FirstPartyAndPartnerAudience customerMatchAudience =
    new FirstPartyAndPartnerAudience()
        .setDisplayName(display-name)
        .setFirstPartyAndPartnerAudienceType(
            "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.
FirstPartyAndPartnerAudience response =
    service
        .firstPartyAndPartnerAudiences()
        .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,
    'firstPartyAndPartnerAudienceType':
        '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.firstPartyAndPartnerAudiences().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-party and partner audience object.
$audience = new Google_Service_DisplayVideo_FirstPartyAndPartnerAudience();
$audience->setDisplayName(display-name);
$audience->setFirstPartyAndPartnerAudienceType(
    '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->firstPartyAndPartnerAudiences->create(
    $audience,
    array('advertiserId' => advertiser-id)
);

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

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

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

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

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

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
        .firstPartyAndPartnerAudiences()
        .editCustomerMatchMembers(
            audience-id,
            editCustomerMatchMembersRequest
        )
        .execute();

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

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.firstPartyAndPartnerAudiences().editCustomerMatchMembers(
    firstPartyAndPartnerAudienceId=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["firstPartyAndPartnerAudienceId"])

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
    ->firstPartyAndPartnerAudiences
    ->editCustomerMatchMembers(
        audience-id,
        $editMemberRequest
    );

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