本頁面由 Cloud Translation API 翻譯而成。

上傳目標客戶比對目標對象

您可以使用 Display & Video 360 API，使用您上傳的客戶聯絡資訊或行動裝置 ID 建立目標客戶比對目標對象。本頁說明如何使用 Display & Video 360 API 建立初始目標客戶比對目標對象，並將新的客戶資料附加至現有目標對象。

準備使用者資料

用於填入「目標顧客比對」目標對象的使用者資料屬於機密性質，且必須在上傳前做好妥善準備。

雜湊處理機密資料

有些目標客戶比對目標對像是根據敏感顧客聯絡資訊建立。Display & Video 360 規定機密資料在使用 SHA256 演算法進行雜湊處理後，才能上傳。下列資料欄位在上傳前必須經過雜湊處理：

名字
姓氏
電子郵件地址
電話號碼

郵遞區號和國家/地區代碼不得在上傳前經過雜湊處理。如果嘗試上傳未經雜湊處理的顧客數位資料，就會發生錯誤。

雜湊處理資料前，請確認符合下列條件：

姓氏、名字和電子郵件地址值中的所有空白字元都必須移除。
所有值都必須使用小寫。
所有電話號碼的格式都必須採用 E.164 格式，並包含國家/地區代碼。

設定使用者同意聲明

上傳使用者資料時，請使用所提供 ContactInfoList 或 MobileDeviceIdList 物件中的 consent 欄位，傳遞納入使用者所授予的同意聲明信號。

將 Consent 物件中的任一欄位設為 CONSENT_STATUS_DENIED 會導致錯誤。

系統會為在單一 firstAndThirdPartyAudiences.create 或 firstAndThirdPartyAudiences.editCustomerMatchMembers 要求中新增的所有使用者設定同意聲明信號。具有不同同意聲明信號的使用者必須以不同的要求上傳。

建立目標顧客比對目標對象

您可以使用 firstAndThirdPartyAudiences.create 方法建立目標客戶比對目標對象。目標對象必須宣告為第一方目標對象，且具有 CUSTOMER_MATCH_CONTACT_INFO 或 CUSTOMER_MATCH_DEVICE_ID 的 audienceType。您必須使用聯集欄位 members 中的適當欄位，提供目標顧客比對資料。

以下範例說明如何使用系統提供的雜湊電話號碼清單，建立新的聯絡資訊「目標客戶比對」目標對象，並設定不限效期的再行銷效期：

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 錯誤。

以下範例說明如何使用提供的郵寄地址資料，將單一客戶新增為目標顧客比對目標對象的現有聯絡資訊：

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

指定目標對象