الاستهداف

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

الاستفادة من اكتساب الاستهداف

يمكن أن ترث موارد الأبناء الاستهداف الذي تمّ تعيينه لبعض الموارد. يمكن استرداد خيارات الاستهداف المُكتسَبة من مورد فرعي، ولكن لا يمكن تعديلها على مستوى المورد الفرعي. يتيح ذلك فرض إعدادات أمان العلامة التجارية وغيرها من إعدادات الاستهداف على مستوى حساب الشريك أو المعلِن بالكامل.

يمكن الاطّلاع على مسار اكتساب السمة في المخطّط البياني أدناه:

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

مراجع حول اكتساب حقوق الملكية في YouTube والشركاء

لا يظهر اكتساب الاستهداف لموارد YouTube والشركاء في Display & Video 360 API. لن يكون الاستهداف المكتسَب من المجموعات الإعلانية قابلاً للاسترجاع على مستوى AdGroup، ولن تكتسِب الموارد الفرعية استهداف YouTube المخصّص للموارد الرئيسية.

لاسترداد جميع إعدادات الاستهداف الوظيفي لمجموعة إعلانية، عليك retrieving options targeting assigned for the Group ad، item الرئيسي، وadvertiser الرئيسي.

الانتباه إلى الاستهداف المحدّد عند إنشاء العنصر

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

• TARGETING_TYPE_DEVICE_TYPE
• TARGETING_TYPE_EXCHANGE
• TARGETING_TYPE_ON_SCREEN_POSITION

تؤدي محاولة إنشاء خيارات استهداف حالية أو حذف خيارات غير حالية تمّ تعيينها إلى ظهور خطأ، لذا ننصحك بالاطّلاع على مجموعة الاستهداف الكاملة التي يتمّ تعيينها لعناصرك عند إنشائها. إذا كنت بحاجة إلى استرداد الاستهداف المحدّد لعنصر في قائمة الإعلانات على مستوى أنواع الاستهداف، استخدِم advertisers.lineItems.bulkListAssignedTargetingOptions.

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

لا تتوقّع أن يتمّ استخدام "الاستهداف التلقائي" تلقائيًا.

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

في Display & Video 360 API، لا يتم تطبيق الاستهداف التلقائي تلقائيًا على العناصر التي تم إنشاؤها حديثًا. لا يؤدي إنشاء العناصر الأساسية إلى نسخ أي استهداف على مستوى الحملة أو مستوى طلب الإدراج. في هذه الحالة، يجب تطبيق الاستهداف على العناصر بشكل منفصل من خلال خيار الاستهداف المخصّص باستخدام طريقتَي الإنشاء أو التعديل المجمّع.

تحذير: في الإصدار 4 من Display & Video 360 API، لم يعُد بالإمكان retrieving أو إدارة الاستهداف على مستوى الحملة وطلب الإدراج.

يمكن أن تكون الطرق الخاصة استثناءً. على سبيل المثال، إنّ العناصر التي تم إنشاؤها من خلال advertisers.lineItems.generateDefault تنسخ الإعدادات من طلب الإدراج الرئيسي، بما في ذلك الاستهداف المحدّد. وبالمثل، سيتمّ منح العناصر التي تمّ إنشاؤها من خلال النسخ الاستهداف نفسه المستخدَم في العنصر الأصلي.

لا يمكن تعديل استهداف YouTube والشركاء

لا يمكن تعديل الاستهداف المخصّص لحملات YouTube والشركاء باستخدام واجهة برمجة التطبيقات في "مساحة العرض والفيديو 360".

يتألّف استهداف YouTube والشركاء من جميع الاستهدافات التي تمّ تعيينها مباشرةً لعناصر YouTube والشركاء والمجموعات الإعلانية، بالإضافة إلى أيّ استهداف لأنواع الاستهداف التالية:

• TARGETING_TYPE_SESSION_POSITION
• TARGETING_TYPE_YOUTUBE_CHANNEL
• TARGETING_TYPE_YOUTUBE_VIDEO

يمكن تعديل هذا الاستهداف باستخدام واجهة مستخدِم "مساحة العرض والفيديو 360" مباشرةً أو من خلال تحميل ملف بيانات منظَّمة.

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

يتم تحديد خيارات الاستهداف لمعظم أنواع الاستهداف بشكلٍ فردي. لا يتّبع استهداف شرائح الجمهور المجمّعة هذا الأسلوب المُركّب، بل يتمّ تحديده بدلاً من ذلك في عنصر واحد قابل للضبط تفاصيل استهداف شرائح الجمهور المجمّعة يسرد أرقام تعريف شرائح الجمهور المطلوب تضمينها واستبعادها عند عرض الإعلانات. بعد تحديده، يكون الخيار assignedTargetingOptionId لخيار مجموعة الجمهور هذا هو "audienceGroup" دائمًا.

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

في ما يلي مثال على كيفية تعديل استهداف الجمهور من أجل استهداف شرائح جمهور إضافية في Google بشكل إيجابي:

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.
BulkEditLineItemAssignedTargetingOptionsRequest requestContent =
    new BulkEditLineItemAssignedTargetingOptionsRequest();
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 (GoogleJsonResponseException 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.
BulkEditLineItemAssignedTargetingOptionsResponse response =
    service.advertisers().lineItems()
        .bulkEditLineItemAssignedTargetingOptions(
            advertiserId,
            lineItemId,
            requestContent).execute();

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}
 )

# 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()

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 = {
   'deleteRequests': [
       {
         'targetingType': "TARGETING_TYPE_AUDIENCE_GROUP",
         'assignedTargetingOptionIds': [
           "audienceGroup"
         ]
       }
   ],
   'createRequests': [
       {
           'targetingType': "TARGETING_TYPE_AUDIENCE_GROUP",
           'assignedTargetingOptions': [
               {'audienceGroupDetails': updated_audience_group_details}
           ]
       }
   ]
}

# Update the audience targeting
updated_audience_targeting = service.advertisers().lineItems(
).bulkEditLineItemAssignedTargetingOptions(
   advertiserId=advertiser_id,
   lineItemId=line_item_id,
   body=bulk_edit_request
).execute()

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_BulkEditLineItemAssignedTargetingOptionsRequest();

$audienceGroupDeleteRequests = array();

try {
    // Retrieve existing audience group targeting.
    $existingAudienceGroupTargetingOption = $this
        ->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 = $this
    ->service
    ->advertisers_lineItems
    ->bulkEditLineItemAssignedTargetingOptions(
        $advertiserId,
        $lineItemId,
        $requestBody
    );

الاستعداد لإيقاف خيارات الاستهداف نهائيًا

إنّ خيارات الاستهداف ليست ثابتة، وقد يتم إيقاف عدد صغير منها نهائيًا من وقتٍ لآخر. بعد إيقاف خيارات الاستهداف نهائيًا، لا تؤثّر في عرض الإعلانات لعنصر عرض معيّن. بعد الإيقاف النهائي، سيتم إلغاء تخصيص هذه الخيارات من عناصر السطر الحالية، وستؤدي الطلبات التي تحاول استرداد هذه الخيارات أو تخصيصها إلى ظهور أخطاء.

لتجنُّب هذه الأخطاء، ننصحك بالتحقّق بانتظام من أرقام تعريف خيارات الاستهداف المُخزَّنة. للحفاظ على الحصة، ننصح بتخزين ملف تعريف المشروعات المستخدَمة بانتظام. ومع ذلك، فإنّ تخزين أرقام التعريف يعني أنّه قد لا تدرك أنّه تم إيقاف خيار استهداف نهائيًا. لهذا السبب، يجب استخدام targetingOptions.targetingTypes.get بانتظام ل retrieving retrieve all stored targeting option IDs to confirm that they are still supported by Display & Video 360.

يُرجى الاطّلاع على صفحة الميزات التي سيتم إيقافها نهائيًا للحصول على تفاصيل حول الخطوات المهمة التي تم اتخاذها في السابق والتي سيتم اتخاذها في المستقبل لإيقاف ميزات معيّنة نهائيًا.

لا تُقدِّم طلبات متزامنة لتعديل العنصر نفسه.

ستؤدي محاولة تعديل الإعدادات أو الاستهداف المحدّد لعنصر واحد في الإعلان باستخدام طلبات متعدّدة متزامنة إلى ظهور خطأ. تشمل الطلبات السارية ما يلي:

• advertisers.lineItems.bulkEditAssignedTargetingOptions
• advertisers.lineItems.bulkUpdate
• advertisers.lineItems.patch
• advertisers.lineItems.targetingTypes.assignedTargetingOptions.create
• advertisers.lineItems.targetingTypes.assignedTargetingOptions.delete

إذا كنت بحاجة إلى إضافة أو إزالة خيارات استهداف مخصّصة متعددة لجدول ملف شخصي واحد في الوقت نفسه، يجب استخدام طلب واحد advertisers.lineItems.bulkEditAssignedTargetingOptions. إذا كنت تريد تعديل إعدادات العنصر ومستهدَفه، أضِف طلب patch أو bulkUpdate وطلب الاستهداف ذي الصلة إلى "قائمة الانتظار" لضمان عدم إرسال الطلب الثاني إلى أن يُرسِل الطلب الأول ردًا.