העלאה של קהלים בהתאמה ללקוחות

אתם יכולים ליצור קהלים בהתאמה ללקוחות באמצעות פרטים ליצירת קשר של לקוחות שהועלו או מזהי מכשירים ניידים באמצעות Display & Video 360 API. בדף הזה מוסבר איך ליצור קהל ראשוני של התאמה ללקוחות ולהוסיף נתוני לקוחות חדשים לקהל הקיים באמצעות Display & Video 360 API.

הכנת נתוני משתמשים

נתוני המשתמשים שמשמש לאכלוס קהלים בהתאמה ללקוחות הם מידע רגיש, וצריך להכין אותם כראוי לפני ההעלאה.

גיבוב (hash) של מידע אישי רגיש

חלק מהקהלים עם התאמה ללקוחות נוצרים באמצעות פרטים רגישים ליצירת קשר עם הלקוחות. מערכת Display & Video 360 דורשת שנתונים רגישים יעברו גיבוב באמצעות האלגוריתם SHA256 לפני ההעלאה. צריך לבצע גיבוב של שדות הנתונים הבאים לפני ההעלאה:

  • שם פרטי
  • שם משפחה
  • כתובות אימייל
  • מספרי טלפון

אין לבצע גיבוב של מיקודים ושל קודי מדינות לפני ההעלאה. ניסיון להעלות נתוני לקוחות ללא גיבוב יוביל לשגיאה.

לפני גיבוב הנתונים, צריך לוודא את התנאים הבאים:

  • צריך להסיר רווחים לבנים מהערכים של השם הפרטי, שם המשפחה וכתובת האימייל.
  • כל הערכים חייבים להיות באותיות קטנות.
  • הפורמט של כל מספרי הטלפון צריך להיות פורמט E.164, והם צריכים לכלול את קידומת המדינה.

כשאתם מעלים נתוני משתמשים, אתם צריכים להשתמש בשדות consent באובייקטים ContactInfoList או MobileDeviceIdList שסיפקתם כדי להעביר אותות של הסכמה שהמשתמשים הכלולים הביעו.

הגדרת אחד מהשדות באובייקט Consent לערך CONSENT_STATUS_DENIED תוביל לשגיאה.

אותות ההסכמה מוגדרים לכל המשתמשים שנוספו בבקשה אחת של firstAndThirdPartyAudiences.create או של firstAndThirdPartyAudiences.editCustomerMatchMembers. צריך להעלות משתמשים עם אותות הסכמה שונים בבקשות נפרדות.

יצירת קהל מסוג 'התאמה ללקוחות'

אפשר ליצור קהל בהתאמה ללקוחות באמצעות השיטה firstAndThirdPartyAudiences.create. הקהל צריך להיות מוגדר כקהל מאינטראקציה ישירה (First-Party), וaudienceType שלו צריך להיות CUSTOMER_MATCH_CONTACT_INFO או CUSTOMER_MATCH_DEVICE_ID. צריך לספק את נתוני ההתאמה ללקוחות באמצעות השדה המתאים בשדה האיחוד 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.

אפשר להוסיף או להסיר רשימות של חברים רק בבקשה אחת של 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']
);