ディスプレイ&ビデオ 360 API を使用して、アップロードした顧客の連絡先情報またはモバイル デバイス ID を使用してカスタマー マッチ オーディエンスを作成できます。このページでは、ディスプレイ&ビデオ 360 API を使用して最初のカスタマー マッチ オーディエンスを作成し、既存のオーディエンスに新しい顧客データを追加する方法について説明します。
ユーザーデータを準備する
カスタマー マッチ オーディエンスの作成に使用されるユーザーデータは機密情報であるため、アップロードする前に適切に準備する必要があります。
機密データをハッシュ化する
一部のカスタマー マッチ オーディエンスは、機密性の高い顧客の連絡先情報を使用して作成されます。ディスプレイ&ビデオ 360 では、アップロードする前にセンシティブ データを SHA256 アルゴリズムでハッシュ化する必要があります。次のデータフィールドは、アップロード前にハッシュ化する必要があります。
- 名
- 姓
- メールアドレス
- 電話番号
郵便番号と国コードは、アップロード前にハッシュ化しないでください。ハッシュ化されていない顧客データをアップロードしようとすると、エラーが発生します。
データをハッシュする前に、次の条件を確認してください。
- 名前、姓、メールアドレスの値から空白文字を削除する必要があります。
- 値はすべて小文字にする必要があります。
- すべての電話番号は E.164 形式で指定し、国番号を含める必要があります。
ユーザーの同意を設定する
ユーザーデータをアップロードする際は、指定された ContactInfoList
オブジェクトまたは MobileDeviceIdList
オブジェクトの consent
フィールドを使用して、含まれるユーザーが許可した同意のシグナルを渡します。
Consent
オブジェクトのいずれかのフィールドを CONSENT_STATUS_DENIED
に設定すると、エラーが発生します。
同意シグナルは、1 回の firstAndThirdPartyAudiences.create
リクエストまたは firstAndThirdPartyAudiences.editCustomerMatchMembers
リクエストで追加されたすべてのユーザーに設定されます。同意シグナルが異なるユーザーは、個別のリクエストでアップロードする必要があります。
カスタマー マッチ オーディエンスを作成する
カスタマー マッチ オーディエンスは、firstAndThirdPartyAudiences.create
メソッドを使用して作成できます。オーディエンスは自社オーディエンスとして宣言され、CUSTOMER_MATCH_CONTACT_INFO
または CUSTOMER_MATCH_DEVICE_ID
の audienceType
が必要です。カスタマー マッチ データは、結合フィールド members
内の適切なフィールドを使用して指定する必要があります。
ハッシュ化された電話番号のリストを使用して、メンバーシップ期間が 540 日の新しい連絡先情報のカスタマー マッチ オーディエンスを作成する方法の例を次に示します。
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(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. 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': 540, '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(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->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
結合フィールドを使用してリストから顧客を削除できます。
1 回の firstAndThirdPartyAudiences.editCustomerMatchMembers
リクエストでリストから追加または削除できるのはメンバーのみです。両方を実行しようとする単一のリクエストは、INVALID_ARGUMENT
エラーになります。
提供された郵送先住所データを使用して、既存の連絡先情報カスタマー マッチ オーディエンスに 1 人の顧客をメンバーとして追加する方法の例を次に示します。
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'] );