REST Resource: advertisers.insertionOrders

Recurso: InsertionOrder

Um único pedido de inserção.

Representação JSON 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "displayName": string,
  "insertionOrderType": enum (InsertionOrderType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "kpi": {
    object (Kpi)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "optimizationObjective": enum (OptimizationObjective)
}
Campos
name

string

Apenas saída. O nome do recurso do pedido de inserção.
advertiserId

string (int64 format)

Apenas saída. O ID exclusivo do anunciante a que o pedido de inserção pertence.
campaignId

string (int64 format)

Obrigatório. Imutável. O ID exclusivo da campanha a que o pedido de inserção pertence.
insertionOrderId

string (int64 format)

Apenas saída. O ID exclusivo do pedido de inserção. Atribuído pelo sistema.
displayName

string

Obrigatório. O nome de exibição do pedido de inserção.

Precisa ser codificado em UTF-8 com um tamanho máximo de 240 bytes.
insertionOrderType

enum (InsertionOrderType)

Opcional. O tipo de pedido de inserção.

Se esse campo não for especificado na criação, o valor padrão será RTB.
entityStatus

enum (EntityStatus)

Obrigatório. Controla se o pedido de inserção pode gastar o orçamento e dar lances no inventário.

  • Para o método insertionOrders.create, somente ENTITY_STATUS_DRAFT é permitido. Para ativar um pedido de inserção, use o método insertionOrders.patch e atualize o status para ENTITY_STATUS_ACTIVE após a criação.
  • Não é possível mudar o status de um pedido de inserção de volta para ENTITY_STATUS_DRAFT.
  • Não é possível definir um pedido de inserção como ENTITY_STATUS_ACTIVE se a campanha principal não estiver ativa.
updateTime

string (Timestamp format)

Apenas saída. O carimbo de data/hora da última atualização do pedido de inserção. Atribuído pelo sistema.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
partnerCosts[]

object (PartnerCost)

Opcional. Os custos do parceiro associados ao pedido de inserção.

Se estiver ausente ou vazio no método insertionOrders.create, o pedido de inserção recém-criado vai herdar os custos do parceiro das configurações dele.
pacing

object (Pacing)

Obrigatório. A configuração de velocidade de gasto do orçamento do pedido de inserção.

pacingType PACING_TYPE_ASAP não é compatível com pacingPeriod PACING_PERIOD_FLIGHT.
frequencyCap

object (FrequencyCap)

Obrigatório. A configuração de limite de frequência do pedido de inserção.
integrationDetails

object (IntegrationDetails)

Opcional. Detalhes adicionais de integração do pedido de inserção.
kpi

object (Kpi)

Obrigatório. O indicador principal de desempenho (KPI) do pedido de inserção.

Isso é representado como "Meta" na interface do Display & Video 360.
budget

object (InsertionOrderBudget)

Obrigatório. As configurações de alocação de orçamento do pedido de inserção.
bidStrategy

object (BiddingStrategy)

Opcional. A estratégia de lances do pedido de inserção. Por padrão, fixedBid é definido.

Se o campo budget automationType estiver definido como INSERTION_ORDER_AUTOMATION_TYPE_BUDGET ou INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET, o pedido de inserção vai impor essa estratégia de lances aos itens de linha. Se uma estratégia de lances imposta não for compatível com a configuração de enableOptimizedTargeting de um item de linha, a configuração de segmentação otimizada será atualizada.
reservationType

enum (ReservationType)

Apenas saída. O tipo de reserva do pedido de inserção.
optimizationObjective

enum (OptimizationObjective)

Obrigatório. O objetivo de otimização do pedido de inserção.

InsertionOrderType

Tipos possíveis de um pedido de inserção.

O tipo de pedido de inserção determina quais configurações e opções são aplicáveis, como o formato dos anúncios ou as opções de segmentação.

Tipos enumerados
INSERTION_ORDER_TYPE_UNSPECIFIED O tipo de pedido de inserção não foi especificado ou é desconhecido.
RTB Lances em tempo real.
OVER_THE_TOP Over-the-top.
OUT_OF_HOME Out-of-home.

IPD

Configurações que controlam o indicador principal de desempenho (KPI) de um pedido de inserção.

Representação JSON 
{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of mutually exclusive fields.
}
Campos
kpiType

enum (KpiType)

Obrigatório. O tipo de KPI.
kpiAlgorithmId

string (int64 format)

Opcional. ID do algoritmo de lances personalizados associado a KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. Esse campo será ignorado se o KPI adequado não for selecionado.
Obrigatório. O valor do KPI. O campo relevante corresponde ao kpi_type. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
kpiAmountMicros

string (int64 format)

O valor da meta, em micros da moeda do anunciante.

Aplicável quando kpiType é um dos seguintes:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Por exemplo: 1500000 representa 1,5 unidade padrão da moeda.
kpiPercentageMicros

string (int64 format)

A representação decimal da porcentagem da meta em micros.

Aplicável quando kpiType é um dos seguintes:

  • KPI_TYPE_CTR
  • KPI_TYPE_VIEWABILITY
  • KPI_TYPE_CLICK_CVR
  • KPI_TYPE_IMPRESSION_CVR
  • KPI_TYPE_VTR
  • KPI_TYPE_AUDIO_COMPLETION_RATE
  • KPI_TYPE_VIDEO_COMPLETION_RATE

Por exemplo: 70000 representa 7% (decimal 0,07).
kpiString

string

Uma string de KPI, que pode estar vazia. Precisa ser codificado em UTF-8 com no máximo 100 caracteres.

Aplicável quando kpiType é KPI_TYPE_OTHER.
Fim dos campos mutuamente exclusivos.

KpiType

Possíveis tipos de indicador principal de desempenho (KPI).

Tipos enumerados
KPI_TYPE_UNSPECIFIED O tipo de KPI não foi especificado ou é desconhecido nesta versão.
KPI_TYPE_CPM O KPI é o CPM (custo por mil impressões).
KPI_TYPE_CPC O KPI é o CPC (custo por clique).
KPI_TYPE_CPA O KPI é o CPA (custo por ação).
KPI_TYPE_CTR O KPI é a porcentagem da taxa de cliques (CTR).
KPI_TYPE_VIEWABILITY O KPI é a porcentagem de visibilidade.
KPI_TYPE_CPIAVC O KPI é o CPIAVC (custo por impressão audível e visível na conclusão).
KPI_TYPE_CPE O KPI é o CPE (custo por engajamento).
KPI_TYPE_CPV O KPI é definido em CPV (custo por visualização).
KPI_TYPE_CLICK_CVR O KPI é a porcentagem da taxa de conversão de cliques (conversões por clique).
KPI_TYPE_IMPRESSION_CVR O KPI é a porcentagem da taxa de conversão de impressões (conversões por impressão).
KPI_TYPE_VCPM O KPI é o vCPM (custo por mil impressões visíveis).
KPI_TYPE_VTR O KPI é a porcentagem da taxa de visualização do YouTube (visualizações do YouTube por impressão).
KPI_TYPE_AUDIO_COMPLETION_RATE O KPI é a porcentagem da taxa de conclusão de áudio (reproduções completas de áudio por impressão).
KPI_TYPE_VIDEO_COMPLETION_RATE O KPI é a porcentagem da taxa de visualizações completas (exibições de vídeos completas por impressão).
KPI_TYPE_CPCL O KPI é definido em CPCL (custo por reprodução completa de áudio).
KPI_TYPE_CPCV O KPI é definido em CPCV (custo por visualização de vídeo concluída).
KPI_TYPE_TOS10 O KPI é definido como a taxa de tempo na tela de mais de 10 segundos (porcentagem de impressões mensuráveis e não puláveis que ficaram na tela por pelo menos 10 segundos).
KPI_TYPE_MAXIMIZE_PACING O KPI está definido para maximizar o impacto da marca enquanto prioriza gastar o orçamento total.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST O KPI é definido como o valor de impressão personalizada dividido pelo custo.
KPI_TYPE_OTHER O KPI é outro valor.

InsertionOrderBudget

Configurações que controlam como o orçamento do pedido de inserção é alocado.

Representação JSON 
{
  "budgetUnit": enum (BudgetUnit),
  "automationType": enum (InsertionOrderAutomationType),
  "budgetSegments": [
    {
      object (InsertionOrderBudgetSegment)
    }
  ]
}
Campos
budgetUnit

enum (BudgetUnit)

Obrigatório. Imutável. A unidade de orçamento especifica se o orçamento é baseado em moeda ou em impressões.
automationType

enum (InsertionOrderAutomationType)

Opcional. O tipo de automação usado para gerenciar o lance e o orçamento do pedido de inserção.

Se esse campo não for especificado na criação, o valor padrão será INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

Obrigatório. A lista de segmentos de orçamento. Use um segmento de orçamento para especificar um orçamento específico para um determinado período da exibição de um pedido de inserção.

InsertionOrderAutomationType

Opções possíveis para automatizar o lance e o orçamento do pedido de inserção.

Tipos enumerados
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED A opção de automação do pedido de inserção não foi especificada ou é desconhecida nesta versão.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Alocação automática de orçamento. Permita que o sistema mude automaticamente o orçamento para os itens de linha próprios para otimizar a performance definida por kpi. Não há automação nas configurações de lance.
INSERTION_ORDER_AUTOMATION_TYPE_NONE Não há automação de lance ou orçamento no nível do pedido de inserção. Os lances e o orçamento precisam ser configurados manualmente no nível do item de linha.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET Permita que o sistema ajuste automaticamente os lances e mude o orçamento para os itens de linha próprios para otimizar a performance definida por bidStrategy.

InsertionOrderBudgetSegment

Configurações que controlam o orçamento de um único segmento de orçamento.

Representação JSON 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
Campos
budgetAmountMicros

string (int64 format)

Obrigatório. O valor do orçamento que o pedido de inserção vai gastar no dateRange especificado. O valor é em micros. Precisa ser maior que 0. Por exemplo, 500000000 representa 500 unidades padrão da moeda.
description

string

Opcional. A descrição do segmento de orçamento. Ele pode ser usado para inserir informações da ordem de compra em cada segmento de orçamento e imprimir essas informações nas faturas.

Ser codificado em UTF-8.
dateRange

object (DateRange)

Obrigatório. As configurações de data de início e término do segmento de orçamento. Eles são resolvidos em relação ao fuso horário do anunciante principal.

  • Ao criar um novo segmento de orçamento, startDate e endDate precisam estar no futuro.
  • Um segmento de orçamento atual com uma startDate no passado tem uma endDate mutável, mas uma startDate imutável.
  • endDate precisa ser startDate ou posterior, ambos antes do ano de 2037.
campaignBudgetId

string (int64 format)

Opcional. O budgetId do orçamento da campanha de que esse segmento de orçamento do pedido de inserção faz parte.

OptimizationObjective

Tipos possíveis de objetivos de otimização.

Tipos enumerados
OPTIMIZATION_OBJECTIVE_UNSPECIFIED O valor do tipo não foi especificado ou é desconhecido nesta versão.
CONVERSION Priorizar impressões que aumentem as vendas e as conversões.
CLICK Priorizar impressões que aumentem o tráfego do site, dos aplicativos e das app stores.
BRAND_AWARENESS Priorizar impressões de qualidade específica.
CUSTOM O objetivo é definido pelo algoritmo de lances personalizados atribuído.
NO_OBJECTIVE O objetivo não está definido. Qualquer KPI ou estratégia de lances pode ser usado.

Métodos

create

 Cria um novo pedido de inserção.

delete

 Exclui um pedido de inserção.

get

 Recebe um pedido de inserção.

list

 Lista os pedidos de inserção de um anunciante.

patch

 Atualiza um pedido de inserção.