您可以使用 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'] );