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 recurso e usa vários outros recursos e espaços de ID. Esta página detalha as limitações a observar 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.

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 são recuperáveis, mas não editáveis 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 da 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 são herdadas, mas precisam ser definidas em um nível inferior.

Herança em recursos do YouTube e parceiros

A herança de segmentação não é refletida para os recursos do YouTube e parceiros na API Display & Video 360. A segmentação herdada por grupos de anúncios não poderá ser recuperada no nível AdGroup, e a segmentação do YouTube atribuída aos recursos pai não será herdada pelos 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.

Não se esqueça da segmentação atribuída na criação do item de linha

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

A tentativa de criar ou excluir opções de segmentação atribuídas existentes ou não existentes retorna um erro. Por isso, recomendamos que você esteja ciente de todo o conjunto 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 vários 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 diretos e revendedores autorizados".

Não espere a "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 aplicado a 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 básica de itens de linha não copia nenhuma segmentação no nível da campanha ou do pedido de inserção. Nesse caso, a segmentação desejada precisa ser aplicada aos itens de linha separadamente por meio dos métodos de opção de segmentação atribuída criar ou edição em massa.

Métodos especiais podem ser uma exceção. Por exemplo, os itens de linha criados com o 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 meio da duplicação receberão a mesma segmentação do item de linha original.

A segmentação do YouTube e parceiros não pode ser modificada

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

A segmentação do YouTube e parceiros consiste em toda segmentação atribuída diretamente a itens de linha e grupos de anúncios do YouTube e parceiros, 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.

Atribua 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, mas é atribuída em um único objeto configurável de detalhes da segmentação de grupos de público-alvo que lista os IDs dos públicos-alvo a serem incluídos e excluídos ao veicular anúncios. Depois de atribuída, o assignedTargetingOptionId dessa opção de grupo de público-alvo é sempre "audienceGroup".

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

Veja 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 algumas delas podem ser descontinuadas periodicamente. Após serem 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 deixarão de ser atribuídas aos itens de linha atuais, e as solicitações que tentarem recuperar ou atribuir essas opções resultarão em erros.

Para evitar esses erros, recomendamos verificar regularmente os IDs de opção de segmentação armazenados. Para economizar sua cota, recomendamos que você armazene em cache os IDs usados regularmente. No entanto, armazenar IDs significa que você talvez não perceba que uma opção de segmentação foi descontinuada. Por esse motivo, 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 ver detalhes sobre 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 para um único item de linha usando várias solicitações simultâneas retornará um erro. As solicitações aplicáveis incluem:

Se você precisar adicionar ou remover várias opções de segmentação atribuídas a 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, enfileire a solicitação patch ou bulkUpdate e a solicitação de segmentação relevante para garantir que a segunda solicitação só seja enviada depois que a primeira retornar uma resposta.