Tải các đối tượng So khớp khách hàng lên

Bạn có thể tạo đối tượng So khớp khách hàng bằng cách sử dụng thông tin liên hệ của khách hàng hoặc mã thiết bị di động được tải lên thông qua API Display & Video 360. Trang này mô tả cách tạo đối tượng So khớp khách hàng ban đầu và nối dữ liệu khách hàng mới vào đối tượng hiện có bằng API Display & Video 360.

Cảnh báo: Hãy xác minh rằng các tính năng tải dữ liệu lên đã được phê duyệt cho đối tác mẹ của đối tượng được đề xuất, trước tiên bằng cách thử tạo đối tượng So khớp khách hàng dưới một nhà quảng cáo phù hợp trong giao diện người dùng. Nếu bạn chưa bật tính năng tải dữ liệu lên, thì hệ thống sẽ báo lỗi nếu bạn cố gắng tạo hoặc cập nhật các đối tượng So khớp khách hàng. Người dùng có quyền truy cập ở cấp đối tác có thể yêu cầu phê duyệt thông qua Biểu mẫu yêu cầu quyền truy cập vào đối tác này.

Chuẩn bị dữ liệu người dùng

Dữ liệu người dùng dùng để điền đối tượng So khớp khách hàng là dữ liệu nhạy cảm, do đó, bạn cần chuẩn bị dữ liệu đúng cách trước khi tải lên.

Hàm băm dữ liệu nhạy cảm

Một số đối tượng So khớp khách hàng được tạo bằng thông tin liên hệ nhạy cảm của khách hàng. Display & Video 360 yêu cầu băm dữ liệu nhạy cảm bằng thuật toán SHA256 trước khi tải lên. Bạn phải băm các trường dữ liệu sau đây trước khi tải lên:

• Tên
• Họ
• Địa chỉ email
• Số điện thoại

Bạn không được băm mã bưu chính và mã quốc gia trước khi tải lên. Bạn sẽ gặp lỗi nếu cố tải dữ liệu khách hàng chưa băm lên.

Trước khi băm dữ liệu, hãy đảm bảo các điều kiện sau:

• Bạn phải xoá mọi khoảng trắng khỏi giá trị tên, họ và địa chỉ email.
• Tất cả giá trị phải được viết thường.
• Tất cả số điện thoại phải được định dạng bằng định dạng E.164 và bao gồm mã gọi quốc gia.

Đặt sự đồng ý của người dùng

Khi tải dữ liệu người dùng lên, hãy sử dụng các trường consent trong các đối tượng ContactInfoList hoặc MobileDeviceIdList được cung cấp để truyền các tín hiệu về sự đồng ý do người dùng được đưa vào.

Việc đặt một trong hai trường trong đối tượng Consent thành CONSENT_STATUS_DENIED sẽ dẫn đến lỗi.

Cảnh báo: Bạn phải gửi tín hiệu về sự đồng ý khi tải các thành viên thuộc đối tượng So khớp khách hàng ở Khu vực kinh tế Châu Âu lên (EEA) để tuân thủ Chính sách về sự đồng ý của người dùng ở Liên minh Châu Âu và sử dụng dữ liệu người dùng ở EEA để điền đối tượng So khớp khách hàng.

Tín hiệu đồng ý được đặt cho tất cả người dùng được thêm vào một yêu cầu firstAndThirdPartyAudiences.create hoặc firstAndThirdPartyAudiences.editCustomerMatchMembers. Bạn phải tải những người dùng có nhiều tín hiệu về sự đồng ý lên trong các yêu cầu riêng biệt.

Tạo đối tượng So khớp khách hàng

Bạn có thể tạo đối tượng So khớp khách hàng bằng phương thức firstAndThirdPartyAudiences.create. Đối tượng phải được khai báo là đối tượng bên thứ nhất và phải có audienceType là CUSTOMER_MATCH_CONTACT_INFO hoặc CUSTOMER_MATCH_DEVICE_ID. Bạn phải cung cấp dữ liệu So khớp khách hàng bằng trường thích hợp trong trường liên kết members.

Lưu ý: Bạn bắt buộc phải sử dụng trường membershipDurationDays khi tạo đối tượng So khớp khách hàng. Bạn có thể bật thời lượng thành viên không giới hạn bằng cách đặt giá trị trường thành 10000.

Dưới đây là ví dụ về cách tạo đối tượng So khớp khách hàng mới cho thông tin liên hệ với thời hạn thành viên không giới hạn bằng cách sử dụng danh sách các số điện thoại băm được cung cấp:

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"])

1.199

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

Cập nhật thành viên của một đối tượng So khớp khách hàng

Nếu đã xác định được thêm khách hàng mà bạn muốn nhắm đến, cần gia hạn gói thành viên đối tượng hiện tại của khách hàng hoặc muốn xoá khách hàng khỏi đối tượng, bạn có thể cập nhật dữ liệu khách hàng của đối tượng So khớp khách hàng hiện tại bằng phương thức firstAndThirdPartyAudiences.editCustomerMatchMembers. Bạn có thể thêm khách hàng vào danh sách bằng trường hợp nhất added_members và xoá khách hàng khỏi danh sách bằng trường hợp nhất removed_members.

Một yêu cầu firstAndThirdPartyAudiences.editCustomerMatchMembers duy nhất chỉ có thể thêm hoặc xoá thành viên khỏi danh sách. Một yêu cầu cố gắng thực hiện cả hai sẽ dẫn đến lỗi INVALID_ARGUMENT.

Lưu ý: Bạn có thể cập nhật các trường siêu dữ liệu về thông tin liên hệ và đối tượng So khớp khách hàng theo mã thiết bị (chẳng hạn như displayName hoặc membershipDurationDays) bằng cách sử dụng phương thức firstAndThirdPartyAudiences.patch.

Dưới đây là ví dụ về cách thêm một khách hàng làm thành viên vào thông tin liên hệ hiện có đối tượng So khớp khách hàng bằng cách sử dụng dữ liệu địa chỉ gửi thư được cung cấp:

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"])

1.199

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