استهداف قائمة المستخدمين

تتيح لك ميزة استهداف قائمة المستخدمين استهداف مجموعة من شرائح الجمهور. يمكن أن تكون جميع شرائح الجمهور المستهدَفة من أنواع مختلفة.

ملاحظة: راجِع دليل مفاهيم شرائح الجمهور للحصول على مزيد من المعلومات حول كل نوع من أنواع شرائح الجمهور.

يتم استهداف جميع شرائح الجمهور باستخدام خيار استهداف واحد محدّد من النوع TARGETING_TYPE_AUDIENCE_GROUP.

منطق استهداف الجمهور

يحتوي خيار استهداف الجمهور المعيّن على عنصر تفاصيل استهداف الجمهور. استهداف الجمهور هو النتيجة المجمّعة لحقول عنصر التفاصيل. تستند هذه النتيجة إلى المنطق التالي:

• كل عنصر من عناصر مجموعة الجمهور هو قائمة بجميع شرائح الجمهور التي تمّ دمجها باستخدام UNION.
• يحتوي الحقل includedFirstPartyAndPartnerAudienceGroups على قائمة بمجموعات الجمهور. تجمع هذه الاستراتيجية بين مجموعات الجمهور من خلال التقاطع.
• تمثّل جميع الحقول التي تتضمّن البادئة "included" قوائم المستخدمين التي سيتم استهدافها. يتم دمج هذه النتائج باستخدام UNION. وينتج عن ذلك قائمة بالمستخدمين الذين سيتم تضمينهم في الاستهداف.
• تمثّل جميع الحقول التي تتضمّن البادئة "excluded" قوائم المستخدمين المطلوب استبعادهم من الاستهداف. يتم دمجها باستخدام UNION. وينتج عن ذلك قائمة بالمستخدمين الذين سيتم استبعادهم من الاستهداف.
• سيتم استهداف جميع المستخدمين المضمّنين غير المدرَجين في قائمة المستخدمين المستبعَدين. في حال استبعاد قوائم المستخدمين فقط، سيتم استهداف جميع المستخدمين باستثناء المستخدمين المستبعَدين.

يعني ذلك عمليًا أمرين. أولاً، لن يتم استهداف المستخدم إذا كان مدرَجًا في شريحة جمهور في حقل "مستبعَد". ثانيًا، سيتم استهداف المستخدم إذا كان أي مما يلي صحيحًا:

• تتوفّر هذه السمة في شريحة جمهور ضمن كل مجموعة جمهور في includedFirstPartyAndPartnerAudienceGroups.
• أن تكون موجودة في أي شريحة جمهور في أي حقل آخر "مضمّن".
• لم يتم ضبط أي حقل "مضمّن".

تعديل استهداف الجمهور

يستخدم استهداف قوائم المستخدِمين خيار استهداف محدّدًا مع قيمة المعرّف "audienceGroup". لضبط استهداف الجمهور، عليك اتّباع الخطوات التالية:

1. استرداد أي قائمة مستخدمين حالية تمّ تعيين خيار الاستهداف لها
2. أنشئ عنصرًا جديدًا لخيار الاستهداف المُحدّد. في حال توفّر استهداف حالي، يجب أن يستند هذا العنصر إلى الاستهداف الحالي، مع أي تغييرات مطلوبة.
3. احذف أي خيار استهداف حالي تم تعيينه، إذا لزم الأمر.
4. أنشئ خيار استهداف جديدًا تم تعيينه.

ويمكن إجراء ذلك باستخدام الطريقتَين list وbulkEditAssignedTargetingOptions.

في ما يلي كيفية تعديل استهداف الجمهور لبند إعلاني:

جافا

// Provide the ID of the parent advertiser.
long advertiserId = advertiser-id;

// Provide the ID of the line item whose targeting will be updated.
long lineItemId = line-item-id;

// Provide a list of Google Audience IDs to add to line item targeting.
List<Long> addedGoogleAudienceIds = google-audience-ids-to-add;

// Build Google Audience targeting settings objects to add to audience
// targeting.
ArrayList<GoogleAudienceTargetingSetting> newGoogleAudienceSettings =
    new ArrayList<GoogleAudienceTargetingSetting>();

// Convert list of Google Audience IDs into list of settings.
for (Long googleAudienceId : addedGoogleAudienceIds) {
  newGoogleAudienceSettings.add(
      new GoogleAudienceTargetingSetting().setGoogleAudienceId(googleAudienceId));
}

// Create relevant bulk edit request objects.
BulkEditAssignedTargetingOptionsRequest requestContent =
    new BulkEditAssignedTargetingOptionsRequest();
requestContent.setLineItemIds(Arrays.asList(lineItemId));

AudienceGroupAssignedTargetingOptionDetails updatedAudienceGroupDetails;
ArrayList<DeleteAssignedTargetingOptionsRequest> audienceGroupDeleteRequests =
    new ArrayList<DeleteAssignedTargetingOptionsRequest>();

try {
  // Retrieve existing audience group targeting.
  AssignedTargetingOption existingAudienceGroupTargetingOption =
      service
          .advertisers()
          .lineItems()
          .targetingTypes()
          .assignedTargetingOptions()
          .get(advertiserId, lineItemId, "TARGETING_TYPE_AUDIENCE_GROUP", "audienceGroup")
          .execute();

  // Extract existing audience group targeting details.
  updatedAudienceGroupDetails = existingAudienceGroupTargetingOption.getAudienceGroupDetails();

  // Build and add delete request for existing audience group targeting.
  ArrayList<String> deleteAudienceGroupAssignedTargetingIds = new ArrayList<String>();
  deleteAudienceGroupAssignedTargetingIds.add("audienceGroup");

  audienceGroupDeleteRequests.add(
      new DeleteAssignedTargetingOptionsRequest()
          .setTargetingType("TARGETING_TYPE_AUDIENCE_GROUP")
          .setAssignedTargetingOptionIds(deleteAudienceGroupAssignedTargetingIds));
} catch (Exception e) {
  updatedAudienceGroupDetails = new AudienceGroupAssignedTargetingOptionDetails();
}

// Set delete requests in edit request.
requestContent.setDeleteRequests(audienceGroupDeleteRequests);

// Construct new group of Google Audiences to include in targeting.
GoogleAudienceGroup updatedIncludedGoogleAudienceGroup =
    updatedAudienceGroupDetails.getIncludedGoogleAudienceGroup();
if (updatedIncludedGoogleAudienceGroup != null) {
  List<GoogleAudienceTargetingSetting> updatedGoogleAudienceSettings =
      updatedIncludedGoogleAudienceGroup.getSettings();
  updatedGoogleAudienceSettings.addAll(newGoogleAudienceSettings);
  updatedIncludedGoogleAudienceGroup.setSettings(updatedGoogleAudienceSettings);
} else {
  updatedIncludedGoogleAudienceGroup = new GoogleAudienceGroup();
  updatedIncludedGoogleAudienceGroup.setSettings(newGoogleAudienceSettings);
}

// Add new Google Audience group to audience group targeting details.
updatedAudienceGroupDetails.setIncludedGoogleAudienceGroup(updatedIncludedGoogleAudienceGroup);

// Create new targeting option to assign.
AssignedTargetingOption newAudienceGroupTargeting = new AssignedTargetingOption();
newAudienceGroupTargeting.setAudienceGroupDetails(updatedAudienceGroupDetails);

// Build audience group targeting create request and add to list of create
// requests.
ArrayList<AssignedTargetingOption> createAudienceGroupAssignedTargetingOptions =
    new ArrayList<AssignedTargetingOption>();
createAudienceGroupAssignedTargetingOptions.add(newAudienceGroupTargeting);
ArrayList<CreateAssignedTargetingOptionsRequest> targetingCreateRequests =
    new ArrayList<CreateAssignedTargetingOptionsRequest>();
targetingCreateRequests.add(
    new CreateAssignedTargetingOptionsRequest()
        .setTargetingType("TARGETING_TYPE_AUDIENCE_GROUP")
        .setAssignedTargetingOptions(createAudienceGroupAssignedTargetingOptions));

// Set create requests in edit request.
requestContent.setCreateRequests(targetingCreateRequests);

// Configure and execute the bulk edit request.
BulkEditAssignedTargetingOptionsResponse response =
    service
        .advertisers()
        .lineItems()
        .bulkEditAssignedTargetingOptions(advertiserId, requestContent)
        .execute();

// Display API response information.
if (response.getUpdatedLineItemIds() != null && !response.getUpdatedLineItemIds().isEmpty()) {
  System.out.printf(
      "Targeting configurations for %s were successfully updated.%n",
      response.getUpdatedLineItemIds().get(0));
}
if (response.getFailedLineItemIds() != null && !response.getFailedLineItemIds().isEmpty()) {
  System.out.printf(
      "Targeting configurations for %s failed to update.%n",
      response.getFailedLineItemIds().get(0));
}
if (response.getErrors() != null && !response.getErrors().isEmpty()) {
  System.out.println("The failed updates were caused by the following errors:");
  for (Status error : response.getErrors()) {
    System.out.printf("Code %s: %s%n", error.getCode(), error.getMessage());
  }
} else {
  System.out.println("No successful or failed updates were reported.");
}

Python

# Provide the ID of the parent advertiser.
advertiser_id = advertiser-id

# Provide the ID of the line item whose targeting will be updated.
line_item_id = line-item-id

# Provide a list of Google Audience IDs to add to line item targeting.
added_google_audiences = google-audience-ids-to-add

# Build Google Audience targeting settings objects to create.
new_google_audience_targeting_settings = []
for google_audience_id in added_google_audiences:
  new_google_audience_targeting_settings.append(
      {'googleAudienceId': google_audience_id}
  )

try:
  # Retrieve any existing line item audience targeting.
  retrieved_audience_targeting = (
      service.advertisers()
      .lineItems()
      .targetingTypes()
      .assignedTargetingOptions()
      .get(
          advertiserId=advertiser_id,
          lineItemId=line_item_id,
          targetingType='TARGETING_TYPE_AUDIENCE_GROUP',
          assignedTargetingOptionId='audienceGroup',
      )
      .execute()
  )
except Exception:
  print(
      'Error retrieving existing audience targeting. Assuming no '
      'existing audience targeting.'
  )
  retrieved_audience_targeting = {}
updated_audience_group_details = {}

# Copy over any existing audience targeting.
if 'audienceGroupDetails' in retrieved_audience_targeting:
  updated_audience_group_details = retrieved_audience_targeting[
      'audienceGroupDetails'
  ]

# Append the new Google Audience IDs to any existing positive Google
# audience targeting.
if 'includedGoogleAudienceGroup' in updated_audience_group_details:
  updated_audience_group_details['includedGoogleAudienceGroup'][
      'settings'
  ].extend(new_google_audience_targeting_settings)
else:
  updated_audience_group_details['includedGoogleAudienceGroup'] = {
      'settings': new_google_audience_targeting_settings
  }

# Build bulk edit request.
bulk_edit_request = {
    'lineItemIds': [line_item_id],
    'deleteRequests': [{
        'targetingType': 'TARGETING_TYPE_AUDIENCE_GROUP',
        'assignedTargetingOptionIds': ['audienceGroup'],
    }],
    'createRequests': [{
        'targetingType': 'TARGETING_TYPE_AUDIENCE_GROUP',
        'assignedTargetingOptions': [
            {'audienceGroupDetails': updated_audience_group_details}
        ],
    }],
}

# Update the audience targeting
response = (
    service.advertisers()
    .lineItems()
    .bulkEditAssignedTargetingOptions(
        advertiserId=advertiser_id, body=bulk_edit_request
    )
    .execute()
)

# Print the line item IDs the successfully updated.
if 'updatedLineItemIds' in response:
  for id in response['updatedLineItemIds']:
    print(
        f'Line Item ID {id} has been updated to target the following '
        f'Google Audiences: {added_google_audiences}.'
    )

# Print the line item IDs that failed to update.
if 'failedLineItemIds' in response:
  for id in response['failedLineItemIds']:
    print(f'Could not update the audience targeting for Line Item ID {id}')
  if 'errors' in response:
    print('The updates failed due to the following errors:')
    for error in response['errors']:
      print(f'Error code: {error["code"]}, Message: {error["message"]}')

PHP

// Provide the ID of the parent advertiser.
$advertiserId = advertiser-id;

// Provide the ID of the line item whose targeting will be updated.
$lineItemId = line-item-id;

// Provide a list of Google Audience IDs to add to line item targeting.
$addedGoogleAudienceIds = array($audienceId);

// Build Google audience targeting setting objects to add.
$newGoogleAudienceTargetingSettings = array();
foreach ($addedGoogleAudienceIds as $googleAudienceId) {
    $googleAudienceSetting =
        new Google_Service_DisplayVideo_GoogleAudienceTargetingSetting();
    $googleAudienceSetting->setGoogleAudienceId($googleAudienceId);
    $newGoogleAudienceTargetingSettings[] = $googleAudienceSetting;
}

// Build bulk edit request.
$bulkEditRequest = new Google_Service_DisplayVideo_BulkEditAssignedTargetingOptionsRequest();
$bulkEditRequest->setLineItemIds(array($lineItemId));

// Call the API, retrieving the existing audience targeting for the
// line item.
try {
    $existingAudienceGroupTargetingOption = $this
        ->service
        ->advertisers_lineItems_targetingTypes_assignedTargetingOptions
        ->get(
            $advertiserId,
            $lineItemId,
            AppendAudienceAssignedTargetingOption::AUDIENCE_TARGETING_TYPE,
            AppendAudienceAssignedTargetingOption::AUDIENCE_TARGETING_OPTION_ID
        );

    $updatedAudienceGroupDetails = $existingAudienceGroupTargetingOption->getAudienceGroupDetails();

    $deleteAudienceGroupAssignedTargetingIds = array(AppendAudienceAssignedTargetingOption::AUDIENCE_TARGETING_OPTION_ID);
    $audienceTargetingDeleteRequest = new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest();
    $audienceTargetingDeleteRequest->setTargetingType(AppendAudienceAssignedTargetingOption::AUDIENCE_TARGETING_TYPE);
    $audienceTargetingDeleteRequest->setAssignedTargetingOptionIds($deleteAudienceGroupAssignedTargetingIds);
    $bulkEditRequest->setDeleteRequests(array($audienceTargetingDeleteRequest));
} catch (\Exception $e) {
    $updatedAudienceGroupDetails = new Google_Service_DisplayVideo_AudienceGroupAssignedTargetingOptionDetails();
}

// Build new targeting object with updated list of Google Audience IDs.
$updatedIncludedGoogleAudienceGroup = new Google_Service_DisplayVideo_GoogleAudienceGroup();
if (!empty($updatedAudienceGroupDetails->getIncludedGoogleAudienceGroup())) {
    $updatedIncludedGoogleAudienceGroup
        ->setSettings(
            array_merge(
                $updatedAudienceGroupDetails
                    ->getIncludedGoogleAudienceGroup()
                    ->getSettings(),
                $newGoogleAudienceTargetingSettings
            )
        );
} else {
    $updatedIncludedGoogleAudienceGroup->setSettings($newGoogleAudienceTargetingSettings);
}
$updatedAudienceGroupDetails->setIncludedGoogleAudienceGroup($updatedIncludedGoogleAudienceGroup);

$newAudienceAssignedTargetingOption = new Google_Service_DisplayVideo_AssignedTargetingOption();
$newAudienceAssignedTargetingOption->setAudienceGroupDetails($updatedAudienceGroupDetails);

$createAudienceTargetingRequest = new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest();
$createAudienceTargetingRequest->setTargetingType(AppendAudienceAssignedTargetingOption::AUDIENCE_TARGETING_TYPE);
$createAudienceTargetingRequest->setAssignedTargetingOptions(array($newAudienceAssignedTargetingOption));
$bulkEditRequest->setCreateRequests(array($createAudienceTargetingRequest));

// Call the API, replacing the audience assigned targeting option for the
// line item.
try {
    $response = $this
        ->service
        ->advertisers_lineItems
        ->bulkEditAssignedTargetingOptions(
            $advertiserId,
            $bulkEditRequest
        );
} catch (\Exception $e) {
    $this->renderError($e);
    return;
}

// Print information returned by the bulk edit request.
// List updated line item IDs.
if (empty($response->getUpdatedLineItemIds())) {
    print '<p>No line items were successfully updated.</p>';
} else {
    print '<p>The targeting of the following line item IDs were '
        . 'updated:</p><ul>';
    foreach ($response->getUpdatedLineItemIds() as $id) {
        printf('<li>%s</li>',$id);
    }
    print '</ul>';
}

// List line item IDs that failed to update.
if (empty($response->getFailedLineItemIds())) {
    print '<p>No line items failed to update.</p>';
} else {
    print '<p>The targeting of the following line item IDs failed to '
        . 'update:</p><ul>';
    foreach ($response->getFailedLineItemIds() as $id) {
        printf('<li>%s</li>',$id);
    }
    print '</ul>';
}

// List the errors thrown when the targeting was updated.
if (empty($response->getErrors())) {
    print '<p>No errors were thrown.</p>';
} else {
    print '<p>The following errors were thrown when attempting to '
        . 'update the targeting:</p><ul>';
    foreach ($response->getErrors() as $error) {
        printf(
            '<li>%s: %s</li>',
            $error->getCode(),
            $error->getMessage()
        );
    }
    print '</ul>';
}

تحسين استهداف الجمهور

يمكن أن تتوسّع "مساحة العرض والفيديو 360" إلى ما هو أبعد من مدى وصول شرائح الجمهور المحدّدة لتصل إلى مستخدمين جدد ومناسبين من خلال ميزة "الاستهداف المحسّن".

اضبط الاستهداف المحسّن لبند إعلان باستخدام الحقل targetingExpansion في تفاصيل الإعلان.