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 mà bạn tải lên bằng Display & Video 360 API. Trang này mô tả cách tạo đối tượng So khớp khách hàng ban đầu và thêm dữ liệu khách hàng mới vào đối tượng hiện có bằng Display & Video 360 API.

Cảnh báo: Xác minh rằng đối tác của bạn đáp ứng các yêu cầu để sử dụng dữ liệu tải lên của tính năng so khớp khách hàng như nêu trong chính sách của chúng tôi. Nếu đối tác của bạn không đáp ứng các yêu cầu, thì mọi nỗ lực tạo hoặc cập nhật đối tượng So khớp khách hàng sẽ trả về lỗi.

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

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

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ạn phải 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 nên băm mã bưu chính và mã quốc gia trước khi tải lên. Việc cố gắng tải dữ liệu khách hàng chưa băm lên sẽ dẫn đến lỗi.

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 các giá trị tên, họ và địa chỉ email.
• Tất cả các giá trị đều phải là chữ thường.
• Tất cả số điện thoại phải được định dạng bằng định dạng E.164 và có mã 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 tín hiệu về sự đồng ý mà người dùng đã cấp.

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 các tín hiệu đồng ý khi tải thành viên đối tượng So khớp khách hàng ở Khu vực kinh tế Châu Âu (EEA) lên để 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 sẵn thông tin cho đố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 firstPartyAndPartnerAudiences.create hoặc firstPartyAndPartnerAudiences.editCustomerMatchMembers. Bạn phải tải người dùng có các tín hiệu đồng ý khác nhau 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 firstPartyAndPartnerAudiences.create. Đối tượng phải được khai báo là đối tượng của 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 cách sử dụng trường thích hợp trong trường hợp nhất members.

Lưu ý: Bạn phải điền trường membershipDurationDays khi tạo đối tượng So khớp khách hàng. Hội viên cá nhân sẽ hết hạn sau khoảng thời gian đã nêu nếu không được tải lại lên đối tượng bằng firstPartyAndPartnerAudiences.editCustomerMatchMembers.

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

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

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

Nếu đã xác định thêm những khách hàng mà bạn muốn nhắm đến, cần gia hạn tư cách 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 một đối tượng, bạn có thể cập nhật dữ liệu khách hàng của một đối tượng So khớp khách hàng hiện có bằng phương thức firstPartyAndPartnerAudiences.editCustomerMatchMembers. Bạn có thể thêm khách hàng vào danh sách bằng cách sử dụng trường kết hợp added_members và xoá khách hàng khỏi danh sách bằng trường kết hợp removed_members.

Một yêu cầu firstPartyAndPartnerAudiences.editCustomerMatchMembers duy nhất chỉ có thể thêm hoặc xoá thành viên khỏi một danh sách. Một yêu cầu duy nhất cố gắng thực hiện cả hai thao tác 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 của thông tin liên hệ và đối tượng Khớp khách hàng theo mã thiết bị, chẳng hạn như displayName hoặc membershipDurationDays, bằng phương thức firstPartyAndPartnerAudiences.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 đối tượng So khớp khách hàng hiện có có thông tin liên hệ 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
        .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']
);