الجماهير المستهدفة

إنّ الاستهداف المجمّع لمعظم أنواع الاستهداف هو نتيجة لموارد AssignedTargetingOption متعدّدة. ضمن نوع الاستهداف، قد يحدِّد كل خيار استهداف مخصّص قيمة مختلفة، على سبيل المثال، متصفّح فردي TARGETING_TYPE_BROWSER. إذا كنت تريد أن يستهدف موردك متصفّحًا إضافيًا، يمكنك إجراء ذلك من خلال إنشاء خيار استهداف جديد مخصّص ل TARGETING_TYPE_BROWSER ضمن هذا المورد. وبالمثل، إذا لم تعُد تريد استهداف متصفّح معيّن، يمكنك حذف خيار الاستهداف المخصّص المرتبط به.

لا يتّبع استهداف مجموعات الجمهور هذه الاتفاقية المكوّنة من وحدات. بدلاً من ذلك، يتمّ منح كلّ معرّفات الجمهور المشارِكة في استهداف أحد الموارد لهذا المورد من خلال AssignedTargetingOption واحد من النوع TARGETING_TYPE_AUDIENCE_GROUP. ستؤدي محاولات تعيين خيارات استهداف مخصّصة لعدّة مجموعات جمهور إلى مورد إلى عرض خطأ. توضّح هذه الصفحة بالتفصيل المنطق الذي يحدّد خيار الاستهداف المحدّد هذا، وتشرح كيفية تعديل استهداف مجموعة الجمهور الحالية بشكلٍ صحيح.

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

يحتوي خيار الاستهداف المخصّص لمجموعة جمهور واحدة على عنصر AudienceGroupAssignedTargetingOptionsDetails المكوّن من قوائم معرّفات الجمهور، المعروفة باسم مجموعات الجمهور، لتضمينها واستبعادها عند عرض الإعلانات. إنّ الاستهداف المجمّع للخيار المخصّص للاستهداف هو نتيجة العمليات المنطقية التالية:

• تجمع عناصر مجموعات الجمهور الفردية من جميع الأنواع الجماهير المضمّنة فيها باستخدام دالة UNION.
• إنّ الحقل includedFirstPartyAndPartnerAudienceGroups الذي يتألّف من قائمة بعناصر FirstPartyAndPartnerAudienceGroup، يجمع مجموعات الجمهور حسب INTERSECTION.
• يتم دمج جميع حقول مجموعات الجمهور التي تحتوي على البادئة "مضمّنة"، والتي تمثّل قوائم مستخدمين أو شرائح من قوائم المستخدمين لاستهدافها بشكل إيجابي، باستخدام دالة UNION.
• يتم دمج جميع حقول مجموعات الجمهور المستبعَدة باستخدام UNION وCOMPLEMENT، ويتم دمج النتيجة مع الاستهداف الإيجابي باستخدام INTERSECTION.

من الناحية العملية، يعني ذلك أنّ العبارة الناتجة AudienceGroupAssignedTargetingOptionsDetails ستستهدف مستخدمًا في حال استيفاء الشرطَين التاليَين:

1. ينتمي المستخدِم إلى كل مجموعة جمهور في قائمة includedFirstPartyAndPartnerAudienceGroups أو ينتمي إلى مجموعة واحدة على الأقل من includedGoogleAudienceGroup أو includedCustomListGroup أو includedCombinedAudienceGroup.
2. لا يندرج المستخدم ضمن الفئة excludedFirstPartyAndPartnerAudienceGroup أو excludedGoogleAudienceGroup.

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

لتعديل استهداف مجموعة الجمهور لعنصر في الصفحة، يجب حذف خيار الاستهداف المخصّص الحالي، إن توفّر، ثمّ إنشاء خيار استهداف مخصّص جديد مع التغييرات المطلوبة. ويمكن إجراء ذلك في طلب واحد باستخدام advertisers.lineItems.bulkEditAssignedTargetingOptions .

ملاحظة: سيتم دائمًا منح خيار استهداف تمّ تعيينه لمجموعة جمهور قيمة assignedTargetingOptionId من "audienceGroup".

في ما يلي مثال على كيفية تعديل استهداف الجمهور الحالي لعنصر سطر من خلال استرداد أي استهداف حالي لمجموعة جمهور، ثم تقديم طلب تعديل مجمّع:

Java

long advertiserId = advertiser-id;
long lineItemId = line-item-id
List<Long> addedGoogleAudienceIds =
    Arrays.asList(google-audience-id-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 list request.
BulkEditAssignedTargetingOptionsResponse response =
    service.advertisers().lineItems()
        .bulkEditAssignedTargetingOptions(
            advertiserId,
            requestContent).execute();

// Print the line item IDs that successfully updated.
if (response.getUpdatedLineItemIds() != null && !response.getUpdatedLineItemIds().isEmpty()) {
  System.out.printf(
      "Targeting configurations for the following line item IDs were updated: %s.\n",
      Arrays.toString(response.getUpdatedLineItemIds().toArray()));
}

// Print the line item IDs the failed to update.
if (response.getFailedLineItemIds() != null && !response.getFailedLineItemIds().isEmpty()) {
  System.out.printf(
      "Targeting configurations for the following line item IDs failed to update: %s.\n",
      Arrays.toString(response.getFailedLineItemIds().toArray()));

  // Print errors thrown for failed updates.
  System.out.println("The failed updates were caused by the following errors:");
  for (Status error : response.getErrors()) {
    System.out.printf("Error Code: %s, Message: %s\n", error.getCode(), error.getMessage());
  }
}

Python

advertiser_id = advertiser-id
line_item_id = line-item-id
added_google_audiences = [google-audience-id-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:
  print("Targeting configurations for the following line item IDs were updated: %s"
        % response['updatedLineItemIds'])

# Print the line item IDs the failed to update.
if 'failedLineItemIds' in response:
  print("Targeting configurations for the following line item IDs failed to update: %s"
        % response['failedLineItemIds'])
  if 'errors' in response:
    print("The failed updates were caused by the following errors:")
    for error in response["errors"]:
      print("Error code: %s, Message: %s" % (error["code"], error["message"]))

PHP

$advertiserId = advertiser-id;
$lineItemId = line-item-id;
$addedGoogleAudienceIds = array(google-audience-id-to-add,...);

// Convert list of Google Audience IDs into list of Google Audience
// settings.
$newGoogleAudienceSettings = array();
foreach ($addedGoogleAudienceIds as $googleAudienceId) {
    $newSetting =
        new Google_Service_DisplayVideo_GoogleAudienceTargetingSetting();
    $newSetting->setGoogleAudienceId($googleAudienceId);
    $newGoogleAudienceSettings[] = $newSetting;
}

// Create a bulk edit request.
$requestBody =
    new Google_Service_DisplayVideo_BulkEditAssignedTargetingOptionsRequest();
$requestBody->setLineItemIds([$lineItemId]);

$audienceGroupDeleteRequests = array();

try {
    // Retrieve existing audience group targeting.
    $existingAudienceGroupTargetingOption = $service
        ->advertisers_lineItems_targetingTypes_assignedTargetingOptions
        ->get(
            $advertiserId,
            $lineItemId,
            'TARGETING_TYPE_AUDIENCE_GROUP',
            'audienceGroup'
        );

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

    // Build and add delete request for existing audience group
    // targeting.
    $deleteAudienceGroupAssignedTargetingIds = array();
    $deleteAudienceGroupAssignedTargetingIds[] = "audienceGroup";

    $audienceGroupDeleteRequest =
        new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest();
    $audienceGroupDeleteRequest
        ->setTargetingType('TARGETING_TYPE_AUDIENCE_GROUP');
    $audienceGroupDeleteRequest
        ->setAssignedTargetingOptionIds(
            $deleteAudienceGroupAssignedTargetingIds
        );
    $audienceGroupDeleteRequests[] = $audienceGroupDeleteRequest;
} catch (\Exception $e) {
    $updatedAudienceGroupDetails =
        new Google_Service_DisplayVideo_AudienceGroupAssignedTargetingOptionDetails();
}

// Set delete requests in edit request.
$requestBody->setDeleteRequests($audienceGroupDeleteRequests);

// Construct new group of Google Audiences to include in targeting.
$updatedIncludedGoogleAudienceGroup = $updatedAudienceGroupDetails
    ->getIncludedGoogleAudienceGroup();

if (!empty($updatedIncludedGoogleAudienceGroup)) {
    // Get existing settings.
    $updatedGoogleAudienceSettings =
    $updatedIncludedGoogleAudienceGroup->getSettings();

    // Add new Google Audiences to existing list.
    $updatedGoogleAudienceSettings = array_merge(
        $updatedGoogleAudienceSettings,
        $newGoogleAudienceSettings
    );

    // Set updated Google Audience list.
    $updatedIncludedGoogleAudienceGroup
        ->setSettings($updatedGoogleAudienceSettings);
} else {
    // Create new Google Audience group.
    $updatedIncludedGoogleAudienceGroup =
        new Google_Service_DisplayVideo_GoogleAudienceGroup();

    // Set list of new Google Audiences for targeting.
    $updatedIncludedGoogleAudienceGroup
        ->setSettings($newGoogleAudienceSettings);
}

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

// Create new targeting option to assign.
$newAudienceGroupTargeting =
    new Google_Service_DisplayVideo_AssignedTargetingOption();
$newAudienceGroupTargeting
    ->setAudienceGroupDetails($updatedAudienceGroupDetails);

// Build audience group targeting create request and add to list of
// create requests.
$createAudienceGroupAssignedTargetingOptions = array();
$createAudienceGroupAssignedTargetingOptions[] =
    $newAudienceGroupTargeting;
$createAudienceGroupTargetingRequest =
    new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest();
$createAudienceGroupTargetingRequest->setTargetingType(
    "TARGETING_TYPE_AUDIENCE_GROUP"
);
$createAudienceGroupTargetingRequest->setAssignedTargetingOptions(
    $createAudienceGroupAssignedTargetingOptions
);
$createRequests[] = $createAudienceGroupTargetingRequest;

// Set create requests in edit request.
$requestBody->setCreateRequests($createRequests);

// Call the API, editing the assigned targeting options for the
// identified line item.
$response = $service
    ->advertisers_lineItems
    ->bulkEditAssignedTargetingOptions(
        $advertiserId,
        $requestBody
    );

// Print the line item IDs the successfully updated.
if (!empty($response->getUpdatedLineItemIds())) {
    printf('Targeting configurations for the following line item IDs were updated:\n');
    foreach ($response->getUpdatedLineItemIds() as $id) {
        printf('%s\n', $id);
    }
}

// Print the line item IDs the failed to update.
if (!empty($response->getFailedLineItemIds())) {
    print('Targeting configurations for the following line item IDs failed to update:\n');
    foreach ($response->getFailedLineItemIds() as $id) {
        printf('%s\n', $id);
    }
    print('The failed updates were caused by the following errors:\n');
    foreach ($response->getErrors() as $error) {
        printf('Error Code: %s, Message: %s\n', $error->getCode(), $error->getMessage());
    }
}

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

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

يتمّ ضبط الاستهداف المحسّن على مستوى العنصر، ويمكن ضبطه من خلال حقل targetingExpansion في مورد LineItem.