Upload Audiens Customer Match

Anda dapat membuat audiens Customer Match menggunakan informasi kontak pelanggan yang diupload atau ID perangkat seluler menggunakan Display & Video 360 API. Halaman ini menjelaskan cara membuat audiens Customer Match awal dan menambahkan data pelanggan baru ke audiens yang ada menggunakan Display & Video 360 API.

Peringatan: Pastikan fitur upload data telah disetujui untuk partner induk audiens yang diusulkan dengan mencoba membuat audiens Customer Match terlebih dahulu berdasarkan pengiklan yang relevan di UI. Jika upload data belum diaktifkan, upaya untuk membuat atau memperbarui audiens Customer Match akan menampilkan error. Pengguna dengan akses tingkat partner dapat meminta persetujuan menggunakan formulir permintaan akses Partner ini.

Menyiapkan data pengguna

Data pengguna yang digunakan untuk mengisi audiens Customer Match bersifat sensitif dan harus disiapkan dengan benar sebelum diupload.

Data sensitif {i>hash <i}

Beberapa audiens Customer Match dibuat menggunakan informasi kontak pelanggan yang sensitif. Display & Video 360 mengharuskan data sensitif di-hash menggunakan algoritma SHA256 sebelum diupload. Kolom data berikut harus di-hash sebelum diupload:

• Nama depan
• Nama belakang
• Alamat email
• Nomor telepon

Kode pos dan kode negara tidak boleh di-hash sebelum diupload. Mencoba mengupload data pelanggan tanpa hash akan menghasilkan error.

Sebelum melakukan hashing pada data, pastikan kondisi berikut:

• Setiap spasi kosong harus dihapus dari nilai nama depan, nama belakang, dan alamat email.
• Semua nilai harus ditulis dalam huruf kecil.
• Semua nomor telepon harus diformat menggunakan format E.164 dan menyertakan kode panggilan negara.

Menetapkan izin pengguna

Saat mengupload data pengguna, gunakan kolom consent di objek ContactInfoList atau MobileDeviceIdList yang disediakan untuk meneruskan sinyal izin yang diberikan oleh pengguna yang disertakan.

Menetapkan salah satu kolom dalam objek Consent ke CONSENT_STATUS_DENIED akan menghasilkan error.

Peringatan: Anda harus mengirim sinyal izin saat mengupload anggota audiens Customer Match Wilayah Ekonomi Eropa (EEA) untuk mematuhi Kebijakan Izin Pengguna Uni Eropa dan menggunakan data pengguna EEA untuk mengisi audiens Customer Match.

Sinyal izin ditetapkan untuk semua pengguna yang ditambahkan dalam satu permintaan firstAndThirdPartyAudiences.create atau firstAndThirdPartyAudiences.editCustomerMatchMembers. Pengguna dengan sinyal izin yang berbeda harus diupload dalam permintaan terpisah.

Membuat audiens Customer Match

Audiens Customer Match dapat dibuat menggunakan metode firstAndThirdPartyAudiences.create. Audiens harus dideklarasikan sebagai audiens pihak pertama dan harus memiliki audienceType dari CUSTOMER_MATCH_CONTACT_INFO atau CUSTOMER_MATCH_DEVICE_ID. Data Customer Match harus disediakan menggunakan kolom yang sesuai dalam kolom union members.

Catatan: Kolom membershipDurationDays diperlukan saat membuat audiens Customer Match. Durasi keanggotaan tak terbatas dapat diaktifkan dengan menetapkan nilai kolom ke 10000.

Berikut adalah contoh cara membuat informasi kontak baru dari audiens Customer Match dengan durasi keanggotaan tidak terbatas menggunakan daftar nomor telepon yang di-hash yang disediakan:

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

Memperbarui keanggotaan audiens Customer Match

Jika telah mengidentifikasi pelanggan lain yang ingin ditargetkan, perlu memperpanjang keanggotaan audiens yang ada pada pelanggan, atau ingin menghapus pelanggan dari audiens, Anda dapat memperbarui data pelanggan dari audiens Customer Match yang ada dengan metode firstAndThirdPartyAudiences.editCustomerMatchMembers. Anda dapat menambahkan pelanggan ke daftar menggunakan kolom union added_members dan menghapus pelanggan dari daftar dengan kolom union removed_members.

Satu permintaan firstAndThirdPartyAudiences.editCustomerMatchMembers hanya dapat menambahkan atau menghapus anggota dari daftar. Satu permintaan yang mencoba melakukan keduanya akan menghasilkan error INVALID_ARGUMENT.

Catatan: Kolom metadata informasi kontak dan audiens Customer Match ID perangkat, seperti displayName atau membershipDurationDays, dapat diperbarui menggunakan metode firstAndThirdPartyAudiences.patch.

Berikut adalah contoh cara menambahkan satu pelanggan sebagai anggota ke audiens informasi kontak yang ada di Customer Match menggunakan data alamat surat yang diberikan:

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