الاستهداف

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

استخدام الاستهداف الوراثي

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

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

الرسم البياني لاكتساب الاستهداف

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

مصادر الاكتساب في YouTube والشركاء

لا يظهر اكتساب الاستهداف في موارد YouTube والشركاء في "مساحة العرض والفيديو 360 API ". لن تتمكّن من استرداد الاستهداف المكتسَب من المجموعات الإعلانية على مستوى AdGroup ولن تكتسب الموارد الفرعية استهداف YouTube المخصّص للموارد الرئيسية.

لاسترداد جميع إعدادات الاستهداف الوظيفية لمجموعة إعلانية، يجب استرداد خيارات الاستهداف المعينة للمجموعة الإعلانية، والعنصر الرئيسي، والمعلن الرئيسي.

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

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

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

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

لا تتوقع "الاستهداف التلقائي" التلقائي

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

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

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

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

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

يتألف استهداف 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 بانتظام لاسترداد جميع أرقام تعريف خيارات الاستهداف المخزّنة للتأكّد من أنّها لا تزال متوافقة مع "مساحة العرض والفيديو 360".

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

عدم إجراء الطلبات المتزامنة لتحديث العنصر نفسه

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

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