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

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

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

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

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

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

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

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

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

לפני הגיבוב של הנתונים, חשוב לוודא את התנאים הבאים:

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

הגדרת הסכמת המשתמש

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

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

אזהרה: צריך לשלוח אותות הסכמה כשמעלים חברים בקהל מסוג 'התאמה ללקוחות' באזור הכלכלי האירופי (EEA) כדי לפעול בהתאם למדיניות Google בנושא הסכמת משתמשים באיחוד האירופי, ולהשתמש בנתוני משתמשים מהאזור הכלכלי האירופי כדי לאכלס קהלים מסוג 'התאמה ללקוחות'.

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

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

ניתן ליצור קהל מסוג 'התאמה ללקוחות' באמצעות השיטה firstAndThirdPartyAudiences.create. צריך להצהיר על הקהל כקהל מאינטראקציה ישירה, והוא חייב לכלול audienceType של CUSTOMER_MATCH_CONTACT_INFO או CUSTOMER_MATCH_DEVICE_ID. כדי לספק את נתוני ההתאמה ללקוחות, צריך להשתמש בשדה המתאים בשדה האיחוד members.

הערה: השדה membershipDurationDays הוא שדה חובה כשיוצרים קהלים מסוג 'התאמה ללקוחות'. אפשר להגדיר משך חברות בלתי מוגבל על ידי הגדרת ערך השדה ל-10,000.

הדוגמה הבאה מראה איך ליצור קהל חדש עם פרטים ליצירת קשר מסוג 'התאמה ללקוחות' עם משך חברות בלתי מוגבל, באמצעות רשימה של מספרי טלפון מגובבים:

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.

הערה: אפשר לעדכן שדות של מטא-נתונים של פרטים של אנשי קשר ושל קהלים מסוג 'התאמה ללקוחות' של מזהי המכשיר, כמו displayName או membershipDurationDays באמצעות השיטה firstAndThirdPartyAudiences.patch.

הדוגמה הבאה מראה איך להוסיף לקוח יחיד כחבר בפרטים ליצירת קשר עם קהל קיים מסוג 'התאמה ללקוחות', באמצעות הנתונים של הכתובת למשלוח דואר שנמסרו:

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