A partir de 8 de setembro de 2025, todos os novos itens de linha precisarão declarar se vão veicular anúncios políticos da União Europeia (UE). As APIs do Display & Video 360 e os uploads de SDF que não fornecem declarações vão falhar. Consulte nossa página de suspensões de uso para mais detalhes sobre como atualizar sua integração e fazer essa declaração.

Esta página foi traduzida pela API Cloud Translation.

Segmentação

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

Use 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 em todo o 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 têm suporte apenas a 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 herdados, mas precisam ser definidos em um nível mais baixo.

Herança em recursos do YouTube e parceiros

A herança de segmentação não é refletida nos recursos do YouTube e parceiros na API Display & Video 360. A segmentação herdada por grupos de anúncios não será recuperável no nível AdGroup, e a segmentação do YouTube atribuída a recursos principais não será herdada por recursos filhos.

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 pai e ao anunciante pai.

Segmentação atribuída na criação do item de linha

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

A tentativa de criar ou excluir opções de segmentação atribuídas 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 na criação. Se você precisar recuperar a segmentação atribuída a um item de linha entre 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 "Revendedores e vendedores diretos autorizados".

Não espere uma "segmentação padrão" automática

No Display & Video 360, a segmentação definida no nível da campanha ou do pedido de inserção não é transmitida imediatamente aos itens de linha filhos. Essa segmentação é conhecida como segmentação padrão e é usada como um modelo de segmentação que é aplicado aos itens de linha criados posteriormente na interface.

Na API Display & Video 360, a segmentação padrão não é aplicada automaticamente a itens de linha recém-criados. A criação de itens de linha básicos não copia a segmentação no nível da campanha ou do pedido de inserção. Nesse caso, a segmentação precisa ser aplicada aos itens de linha separadamente usando os métodos criar ou editar em massa da opção de segmentação atribuída.

Métodos especiais podem ser uma exceção. Por exemplo, os itens de linha criados com advertisers.lineItems.generateDefault copiam as configurações do pedido de inserção pai, incluindo a segmentação atribuída. Da mesma forma, os itens de linha criados por duplicação vão receber a mesma segmentação do item de linha original.

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

A segmentação específica para campanhas do YouTube e parceiros não pode ser atualizada 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 do YouTube e parceiros e grupos de anúncios, além de qualquer segmentação dos seguintes tipos:

TARGETING_TYPE_SESSION_POSITION
TARGETING_TYPE_YOUTUBE_CHANNEL
TARGETING_TYPE_YOUTUBE_VIDEO

Essa segmentação pode ser atualizada usando a interface do Display & Video 360 diretamente 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 de público-alvo não segue essa convenção modular, mas é atribuída em um único objeto configurável de detalhes da segmentação 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 para essa opção de grupo de público-alvo, uma vez 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 atribuída ao grupo de público-alvo atual e, em seguida, criando uma nova opção de segmentação por grupo de público-alvo 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 positivamente outros públicos-alvo do 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
    );

Prepare-se para a descontinuação das opções de segmentação

As opções de segmentação não são estáticas, e um pequeno número pode ser descontinuado de tempos em tempos. As opções de segmentação, depois de descontinuadas, não afetam a veiculação de anúncios de um item de linha. Após a descontinuação, essas opções serão destribuídas dos itens de linha existentes, e as solicitações que tentarem recuperar ou atribuir essas opções vão resultar em erros.

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

Consulte a página Suspensão de uso anunciada para saber mais sobre as suspensões de uso anteriores e futuras.

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

A tentativa de atualizar as configurações ou a segmentação atribuída para 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 você quiser atualizar as configurações e a segmentação de um item de linha, coloque a solicitação patch ou bulkUpdate e a solicitação de segmentação relevante na fila para garantir que a segunda solicitação não seja enviada até que a primeira retorne uma resposta.