A API Display & Video 360 v3 foi desativada. Migre para a v4.

Segmentação

O gerenciamento da segmentação por recursos é um recurso central da API Display & Video 360. A segmentação pode ser atribuída a vários tipos de recursos e usa vários outros recursos e espaços de ID. Esta página detalha as limitações e as práticas recomendadas para implementar na adoção dos serviços de opções de segmentação atribuídas da API Display & Video 360.

Usar a herança de segmentação

A segmentação atribuída a alguns recursos pode ser herdada pelos recursos filhos. As opções de segmentação herdadas por um recurso filho podem ser recuperadas, mas não editadas no nível do recurso filho. Isso permite que as configurações de brand safety e outras segmentações sejam aplicadas a todo um parceiro ou anunciante.

O caminho de herança pode ser visto no diagrama abaixo:

Diagrama de herança de segmentação

Conforme especificado no diagrama, alguns níveis de segmentação são compatíveis apenas com um subconjunto de tipos de segmentação. Isso significa que algumas opções de segmentação não podem ser definidas em níveis mais altos e herdadas, mas precisam ser definidas em um nível mais baixo.

Herança em recursos do YouTube e parceiros

A herança de segmentação não é refletida para recursos do YouTube e parceiros na API Display & Video 360. A segmentação herdada pelos grupos de anúncios não poderá ser recuperada no nível AdGroup, e a segmentação do YouTube atribuída aos recursos principais não será herdada pelos recursos secundários.

Para recuperar todas as configurações de segmentação funcional de um grupo de anúncios, recupere as opções de segmentação atribuídas ao grupo de anúncios, ao item de linha principal e ao anunciante principal.

Conheça a segmentação atribuída na criação do item de linha

Além das opções de segmentação herdadas, a maioria das segmentações só pode ser atribuída depois que um item de linha é criado. No entanto, há alguns tipos de segmentação que têm um subconjunto padrão de valores atribuídos aos itens de linha na criação deles. Esses tipos de segmentação são:

Tentar criar opções de segmentação atribuídas que já existem ou excluir opções que não existem retorna um erro. Por isso, recomendamos que você conheça o conjunto completo de segmentação atribuído aos seus itens de linha no momento da criação. Se você precisar recuperar a segmentação atribuída a um item de linha em todos os tipos de segmentação, use advertisers.lineItems.bulkListAssignedTargetingOptions.

Além disso, algumas configurações são definidas por padrão quando nenhuma opção de segmentação desse tipo é atribuída ao recurso. Por exemplo, se um recurso não tiver uma opção de segmentação TARGETING_TYPE_AUTHORIZED_SELLER_STATUS definida, isso significa que ele está usando o status "Vendedores e revendedores diretos autorizados".

Não é possível modificar a segmentação do YouTube e parceiros

Não é possível atualizar a segmentação especificamente para campanhas do YouTube e parceiros usando a API Display & Video 360.

A segmentação do YouTube e parceiros consiste em toda a segmentação atribuída diretamente a itens de linha e grupos de anúncios do YouTube e parceiros, bem como qualquer segmentação dos seguintes tipos:

TARGETING_TYPE_SESSION_POSITION
TARGETING_TYPE_YOUTUBE_CHANNEL
TARGETING_TYPE_YOUTUBE_VIDEO

Essa segmentação pode ser atualizada diretamente na interface do Display & Video 360 ou fazendo upload de um arquivo de dados estruturados.

Atribuir a segmentação por público-alvo com uma única opção

As opções de segmentação para a maioria dos tipos são atribuídas individualmente. A segmentação por grupo de público-alvo não segue essa convenção modular. Em vez disso, ela é atribuída em um único objeto configurável detalhes da segmentação por grupo de público-alvo que lista os IDs dos públicos-alvo a serem incluídos e excluídos ao veicular anúncios. O assignedTargetingOptionId dessa opção de grupo de público-alvo, depois de atribuído, é sempre "audienceGroup".

Isso significa que qualquer mudança na segmentação por grupo de público-alvo precisa ser feita primeiro excluindo a opção de segmentação por grupo de público-alvo atribuída e depois criando uma nova opção com as mudanças desejadas. Isso pode ser feito em uma única solicitação usando advertisers.lineItems.bulkEditAssignedTargetingOptions.

Confira um exemplo de como atualizar a segmentação por público-alvo para segmentar outros públicos do Google de forma positiva:

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

Esteja preparado para a descontinuação das opções de segmentação

As opções de segmentação não são estáticas, e algumas podem ser descontinuadas de tempos em tempos. Depois de descontinuadas, as opções de segmentação não afetam a veiculação de anúncios de um item de linha. Após a descontinuação, essas opções serão removidas dos itens de linha e das solicitações atuais que tentarem recuperar ou atribuir essas opções, o que vai resultar em erros.

Para evitar esses erros, recomendamos que você verifique regularmente os IDs das opções de segmentação armazenadas. Para conservar a cota, recomendamos que você armazene em cache IDs usados regularmente. No entanto, armazenar IDs significa que você pode não perceber que uma opção de segmentação foi descontinuada. Por isso, use regularmente targetingOptions.targetingTypes.get para recuperar todos os IDs de opção de segmentação armazenados e confirmar se eles ainda são compatíveis com o Display & Video 360.

Consulte nossa página Descontinuações anunciadas para saber mais sobre as descontinuações significativas anteriores e futuras.

Não faça solicitações simultâneas atualizando o mesmo item de linha

A tentativa de atualizar as configurações ou a segmentação atribuída de um único item de linha usando várias solicitações simultâneas vai retornar um erro. As solicitações aplicáveis incluem:

Se você precisar adicionar ou remover várias opções de segmentação atribuídas para um único item de linha ao mesmo tempo, use uma única solicitação advertisers.lineItems.bulkEditAssignedTargetingOptions. Se quiser atualizar as configurações e a segmentação de um item de linha, coloque na fila a solicitação patch ou bulkUpdate e a solicitação de segmentação relevante para garantir que a segunda não seja enviada até que a primeira retorne uma resposta.

Segmentação Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.