Kierowanie

Zarządzanie kierowaniem na zasoby to podstawowa funkcja interfejsu Display & Video 360 API. Kierowanie można przypisać do wielu typów zasobów i wykorzystuje ono wiele innych zasobów oraz przestrzeni identyfikatorów. Na tej stronie znajdziesz szczegółowe informacje o ograniczeniach, na które należy zwrócić uwagę, oraz sprawdzone metody, które warto wdrożyć podczas korzystania z usług interfejsu Display & Video 360 API Assigned Targeting Options.

Korzystanie z dziedziczenia kierowania

Kierowanie przypisane do niektórych zasobów może być dziedziczone przez ich zasoby podrzędne. Opcje kierowania odziedziczone przez zasób podrzędny można pobrać, ale nie można ich edytować na poziomie zasobu podrzędnego. Dzięki temu ustawienia bezpieczeństwa marki i inne ustawienia kierowania są egzekwowane w przypadku całego partnera lub reklamodawcy.

Ścieżkę dziedziczenia widać na poniższym diagramie:

Diagram dziedziczenia kierowania

Jak widać na diagramie, niektóre poziomy kierowania obsługują tylko podzbiór typów kierowania. Oznacza to, że niektórych opcji kierowania nie można ustawić na wyższych poziomach i odziedziczyć, ale trzeba je ustawić na niższym poziomie.

Dziedziczenie w zasobach YouTube i sieci partnerów

W Display & Video 360 API nie jest odzwierciedlane dziedziczenie kierowania w przypadku zasobów YouTube i sieci partnerów. Kierowanie odziedziczone przez grupy reklam nie będzie możliwe do pobrania na poziomie AdGroup, a kierowanie na YouTube przypisane do zasobów nadrzędnych nie będzie dziedziczone przez zasoby podrzędne.

Aby pobrać wszystkie ustawienia kierowania funkcjonalnego dla grupy reklam, pobierz przypisane opcje kierowania dla grupy reklam, nadrzędnego elementu zamówienia i nadrzędnego reklamodawcy.

Pamiętaj o kierowaniu przypisanym podczas tworzenia elementu zamówienia

Większość opcji kierowania (z wyjątkiem opcji odziedziczonych) można przypisać dopiero po utworzeniu elementu zamówienia. Istnieje jednak kilka typów kierowania, które mają domyślny podzbiór wartości przypisanych do elementów zamówienia podczas ich tworzenia. Te typy kierowania to:

Próba utworzenia istniejących lub usunięcia nieistniejących przypisanych opcji kierowania zwraca błąd, dlatego zalecamy zapoznanie się z pełnym zestawem opcji kierowania przypisanych do elementów zamówienia podczas ich tworzenia. Jeśli chcesz pobrać kierowanie przypisane do elementu zamówienia w różnych typach kierowania, użyj advertisers.lineItems.bulkListAssignedTargetingOptions.

Niektóre ustawienia są też domyślnie włączone, gdy do zasobu nie jest przypisana żadna opcja kierowania danego typu. Jeśli na przykład zasób nie ma zdefiniowanej opcji kierowania TARGETING_TYPE_AUTHORIZED_SELLER_STATUS, oznacza to, że korzysta on ze stanu „Autoryzowani sprzedawcy bezpośredni i sprzedawcy”.

Nie można modyfikować kierowania na YouTube i sieć partnerów wideo Google

Kierowania w kampaniach w YouTube i sieci partnerów nie można aktualizować za pomocą interfejsu Display & Video 360 API.

Kierowanie w YouTube i sieci partnerów obejmuje całe kierowanie przypisane bezpośrednio do elementów zamówienia typu YouTube i sieć partnerów oraz grup reklam, a także kierowanie według tych typów:

  • TARGETING_TYPE_SESSION_POSITION
  • TARGETING_TYPE_YOUTUBE_CHANNEL
  • TARGETING_TYPE_YOUTUBE_VIDEO

To kierowanie można zaktualizować bezpośrednio w interfejsie Display & Video 360 lub przez przesłanie pliku uporządkowanych danych.

Przypisywanie kierowania na odbiorców za pomocą jednej opcji

Opcje kierowania w przypadku większości typów kierowania są przypisywane indywidualnie. Kierowanie na grupy odbiorców nie jest zgodne z tą konwencją modułową, ale jest przypisywane w ramach jednego konfigurowalnego obiektu szczegółów kierowania na grupy odbiorców, który zawiera identyfikatory odbiorców do uwzględnienia i wykluczenia podczas wyświetlania reklam. W przypadku tej opcji grupy odbiorców assignedTargetingOptionId po przypisaniu zawsze ma wartość „audienceGroup”.

Oznacza to, że wszelkie zmiany kierowania na grupy odbiorców muszą być wprowadzane przez usunięcie istniejącej opcji kierowania na przypisaną grupę odbiorców, a następnie utworzenie nowej opcji kierowania na grupę odbiorców z odpowiednimi zmianami. Można to zrobić w jednym żądaniu za pomocą advertisers.lineItems.bulkEditAssignedTargetingOptions.

Oto przykład aktualizacji kierowania na odbiorców, która umożliwia kierowanie na dodatkowe grupy odbiorców 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
    );

Przygotuj się na wycofanie opcji kierowania

Opcje kierowania nie są statyczne i od czasu do czasu niektóre z nich mogą zostać wycofane. Wycofane opcje kierowania nie mają wpływu na wyświetlanie reklam w elemencie zamówienia. Po wycofaniu te opcje zostaną odłączone od dotychczasowych elementów zamówienia, a żądania, które będą próbować je pobrać lub przypisać, będą powodować błędy.

Aby uniknąć tych błędów, zalecamy regularne sprawdzanie zapisanych identyfikatorów opcji kierowania. Aby oszczędzać limit, zalecamy buforowanie często używanych identyfikatorów. Przechowywanie identyfikatorów oznacza jednak, że możesz nie zauważyć, że opcja kierowania została wycofana. Z tego powodu należy regularnie używać metody targetingOptions.targetingTypes.get, aby pobierać wszystkie zapisane identyfikatory opcji kierowania i sprawdzać, czy są one nadal obsługiwane przez Display & Video 360.

Szczegółowe informacje o ważnych wycofanych i planowanych zmianach znajdziesz na stronie Ogłoszone wycofania.

Nie wysyłaj równoczesnych żądań aktualizujących ten sam element zamówienia

Próba zaktualizowania ustawień lub przypisanego kierowania w przypadku pojedynczego elementu zamówienia za pomocą wielu jednoczesnych żądań spowoduje wyświetlenie błędu. Dotyczy to m.in. tych żądań:

Jeśli chcesz jednocześnie dodać lub usunąć wiele przypisanych opcji kierowania w przypadku jednego elementu zamówienia, użyj jednego żądania advertisers.lineItems.bulkEditAssignedTargetingOptions. Jeśli chcesz zaktualizować ustawienia i kierowanie elementu zamówienia, umieść w kolejce żądanie patch lub bulkUpdate oraz odpowiednie żądanie kierowania, aby mieć pewność, że drugie żądanie nie zostanie wysłane, dopóki pierwsze nie zwróci odpowiedzi.