API de Marketing

Campanhas de compras Advantage+

As campanhas de compras Advantage+ permitem que anunciantes de comércio eletrônico/varejo direto ao consumidor e marcas melhorem o desempenho, a personalização e a eficiência. Essas campanhas oferecem maior flexibilidade para controlar alavancas como criativo, direcionamento, posicionamentos e orçamento, além de mais oportunidades para otimizar campanhas que geram conversões.

Em vez de veicular várias campanhas com públicos segmentados, as campanhas de compras Advantage+ possibilitam combinar todos seus públicos de um determinado mercado em uma única estrutura de campanha. Esse sistema simplifica os processos de criação e gerenciamento, ao mesmo tempo em que reduz a sobreposição de público.

Configuração manual de campanha em comparação com as campanhas de compras Advantage+

Configuração manual da campanha BAUCampanha de compras Advantage+

Várias campanhas BAU

Substituição de portfólio BAU


Direcionamento manual com 7 alavancas


Segmentação automatizada, automação para aumentar a eficiência da configuração com entrada de 1 país


Alocações de orçamento rigorosas em várias campanhas


Liquidez do orçamento em 1 campanha


Teste de até 50 combinações de criativos


Uso de anúncios dinâmicos e estáticos com até 150 combinações de criativos


Este documento descreve as etapas que você precisa seguir para configurar sua integração de campanhas de compras Advantage+. Você precisará fazer o seguinte:

  1. Definir seus clientes existentes
  2. Criar uma campanha
  3. Verificar a criação da campanha
  4. Criar um conjunto de anúncios
  5. Fornecer um criativo e criar anúncios
  6. Incluir informações de restrição de idade mínima e exclusão geográfica (consulte o documento de referência sobre controles da conta de anúncios)

Saiba mais sobre a otimização para conversão entre canais em campanhas de compras Advantage+.

Etapa 1: definir seus clientes existentes

As campanhas de compras Advantage+ permitem que você defina seus clientes existentes como uma coleção de identificações de públicos personalizados. Clientes existentes são usuários que já estão familiarizados com seu negócio/produto. Depois que essa definição for configurada, você poderá usá-la para segmentar seu orçamento em campanhas de compras Advantage+ a fim de limitar os gastos com clientes existentes. Também forneceremos métricas que mostram o desempenho das suas campanhas nesses diferentes segmentos.

Você pode definir seu anúncio publicando no ponto de extremidade /act_{ad_account_id}. Será preciso incluir o seguinte parâmetro para configurar essa definição:

ParâmetroDescrição

existing_customers

Array<string>

Matriz de identificações de públicos personalizados aos quais a conta de anúncios tem acesso. No momento, estas são as fontes compatíveis com público personalizado: site, atividade do app, lista de clientes, catálogo e atividade offline.


Para saber como criar um público personalizado, consulte esta página.

Exemplo

curl -X POST \
  -F 'existing_customers=[<CUSTOM_AUDIENCE_ID>, <CUSTOM_AUDIENCE_ID>]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>

Para saber como rastrear públicos novos e existentes em ferramentas de rastreamento de terceiros, confira os parâmetros de URL de tipo de público.

Etapa 2: criar uma campanha

Para começar, crie sua campanha de anúncios. Para concluir essa etapa, faça uma solicitação POST para /act_{ad_account_id}/campaigns.

Parâmetros


ParâmetroDescrição

name
string

Obrigatório.
Nome da campanha de compras Advantage+.

objective
enumeração

Obrigatório
Objetivo da campanha. Especifique OUTCOME_SALES para este tipo de anúncio

special_ad_categories

list<Object>

Obrigatório.
Categorias de anúncio especial associadas à campanha de compras Advantage+.

adlabels

list<Object>

Opcional.
Rótulos de anúncios associados à campanha de compras Advantage+.

buying_type
string

Opcional.
As campanhas de compras Advantage+ aceitam apenas o valor AUCTION.

execution_options

list<enum>

Opcional.
Valor padrão: set. Outras opções são:

  • validate_only: quando esta opção for especificada, a chamada de API não realizará a mutação, mas executará as regras de validação em relação aos valores de cada campo.
  • include_recommendations: esta opção não pode ser usada sozinha. Quando ela for utilizada, serão incluídas recomendações para configuração do objeto de anúncio. Uma seção específica para recomendação será incluída na resposta, mas somente se existirem recomendações para tal especificação.

Se a chamada passar no processo de validação ou análise, a resposta será {"success": true}. Caso a chamada não seja aprovada, um erro será retornado com mais detalhes.

smart_promotion_type
enumeração

Obrigatório.
Para especificar que esta é uma campanha de compras Advantage+, o tipo de promoção inteligente deve ser definido como AUTOMATED_SHOPPING_ADS.

status
enumeração

Opcional.
Opções válidas: PAUSED e ACTIVE.


Se o status for PAUSED, todos os respectivos conjuntos de anúncios e anúncios ativos serão pausados e terão status efetivo de CAMPAIGN_PAUSED.

Exemplo de criação de campanha

curl -X POST \
  -F 'name=Advantage+ Shopping Campaign' \
  -F 'objective=OUTCOME_SALES' \
  -F 'status=ACTIVE' \
  -F 'special_ad_categories=[]' \
  -F 'smart_promotion_type=AUTOMATED_SHOPPING_ADS' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/campaigns

Atualização

É possível atualizar uma campanha fazendo uma solicitação POST para /{campaign_id}.

Parâmetros


ParâmetroDescrição

name
string

Nome da campanha de compras Advantage+.

special_ad_categories

list<Object>

Categorias de anúncio especial associadas à campanha de compras Advantage+.

adlabels

list<Object>

Rótulos de anúncios associados à campanha de compras Advantage+.

execution_options

list<enum>

Valor padrão: set. Outras opções são:

  • validate_only: quando esta opção for especificada, a chamada de API não realizará a mutação, mas executará as regras de validação em relação aos valores de cada campo.
  • include_recommendations: esta opção não pode ser usada sozinha. Quando ela for utilizada, serão incluídas recomendações para configuração do objeto de anúncio. Uma seção específica para recomendação será incluída na resposta, mas somente se existirem recomendações para tal especificação.

Se a chamada passar no processo de validação ou análise, a resposta será {"success": true}. Caso a chamada não seja aprovada, um erro será retornado com mais detalhes.

topline_id
string numérica ou número inteiro

Identificação da linha do pedido.

status
enumeração

Você pode usar estes status em uma chamada de API de atualização:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

Se uma campanha de anúncios for definida como PAUSED, os respectivos objetos derivados que estiverem ativos serão pausados e terão um status efetivo de CAMPAIGN_PAUSED.

Exemplo de atualização de campanha

curl -X POST \
  -F 'name=Advantage+ Shopping Update Sample Campaign' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<CAMPAIGN_ID>

Etapa 3: verificar a criação da campanha

Para verificar se você criou a campanha de compras Advantage+ com sucesso, faça uma solicitação GET para /<AD_CAMPAIGN_ID> com o campo smart_promotion_type.

Uma campanha de compras Advantage+ válida retornará o valor do campo AUTOMATED_SHOPPING_ADS.

Exemplo

curl -X GET -G \
  -d 'fields=smart_promotion_type' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<AD_CAMPAIGN_ID>

Resposta

{
  "smart_promotion_type": "AUTOMATED_SHOPPING_ADS",
  "id": <AD_CAMPAIGN_ID>
}

Etapa 4: criar um conjunto de anúncios

Quando a campanha estiver pronta, crie um conjunto de anúncios. Cada campanha de compras Advantage+ pode ter apenas um conjunto de anúncios associado a ela.

Para criar um conjunto de anúncios, faça uma solicitação POST para /act_{ad_account_id}/adsets.

Parâmetros


ParâmetroDescrição

campaign_id
string numérica ou número inteiro

Obrigatório.
Uma campanha de compras Advantage+ válida à qual você quer adicionar o conjunto de anúncios.

name
string

Obrigatório.
Nome da campanha de compras Advantage+.

promoted_object
Objeto

Obrigatório.
O objeto que o conjunto promove em todos os anúncios. Para campanhas de compras Advantage+, forneça o seguinte:

  • pixel_id e
  • custom_event_type: o conjunto de anúncios de compras Advantage+ aceita estes eventos: PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, ADD_TO_WISHLIST, CONTENT_VIEW, COMPLETE_REGISTRATION, DONATE, START_TRIAL, SUBSCRIBE, SEARCH, OTHER.

Saiba mais sobre a otimização para conversão entre canais em campanhas de compras Advantage+.

targeting
Objeto de direcionamento

Obrigatório.
Estrutura de direcionamento de um conjunto de anúncios de compras Advantage+. Só é possível especificar geo_locations.

geo_locations
matriz

Obrigatório.
Usado para limitar o público do conjunto de anúncios.

daily_budget
int64

Opcional.
Orçamento diário definido na moeda da sua conta, permitido apenas para conjuntos de anúncios com duração (diferença entre end_time e start_time) maior que 24 horas.


daily_budget ou lifetime_budget precisa ser maior que "0".

lifetime_budget
int64

Opcional.
Orçamento total, definido na moeda da sua conta. Se for especificado, será preciso definir também um end_time.


daily_budget ou lifetime_budget precisa ser maior que "0".

end_time
datetime

Obrigatório quando lifetime_budget é especificado.
Ao criar um conjunto de anúncios com um daily_budget, especifique end_time=0 para definir o conjunto como "em andamento", sem data de término. Registro de data e hora UNIX (UTC).


Exemplo: 2015-03-12 23:59:59-07:00 ou 2015-03-12 23:59:59 PDT.

optimization_goal
enumeração

Opcional.
Selecione OFFSITE_CONVERSIONS como meta de otimização para maximizar o número de conversões. Selecione VALUE como meta de otimização se quiser maximizar o valor das conversões. No Gerenciador de Anúncios, exibimos a opção de valor mais alto como sua estratégia de lance.

bid_strategy
enumeração

Opcional

  • LOWEST_COST_WITHOUT_CAP: o Facebook dá um lance automático em seu nome e obtém os resultados de menor custo para você. É possível aumentar automaticamente seu lance efetivo conforme necessário para obter os resultados desejados com base na optimization_goal. Essa é a bid_strategy padrão quando a optimization_goal é definida como OFFSITE_CONVERSION ou VALUE.
  • LOWEST_COST_WITH_MIN_ROAS: especifique a opção de lance para otimização de valor. Você precisa especificar um roas_average_floor, que representa o retorno mínimo desejado sobre o investimento em publicidade. Saiba mais sobre os lances de retorno mínimo sobre o investimento em anúncios.
  • COST_CAP: obtenha o melhor resultado possível enquanto nos esforçamos para manter o custo por ação definido por você. Você deve fornecer um número de limite no campo bid_amount. Observação: a adesão ao limite de custo não é garantida. Saiba mais sobre o limite de custo.

bid_amount

Obrigatório se a bid_strategy for definida como COST_CAP.

bid_constraints
objeto JSON

Opcional

  • optimization_goal precisar ser VALUE.
  • bid_strategy precisa ser LOWEST_COST_WITH_MIN_ROAS.
  • Os lances de retorno mínimo sobre o investimento em publicidade (ROAS) usam bid_constraints para transmitir o "ROAS mínimo", mas não é possível usar essa opção com bid_constraints. Em vez disso, use roas_average_floor. Saiba mais sobre os lances de retorno mínimo sobre o investimento em anúncios.
  • O intervalo válido de roas_average_floor é [100, 10000000], incluso. Isso significa que o intervalo válido de "ROAS mínimo" é [0.01, 1000.0] ou [1%, 100000.0%], incluso.

billing_event
enumeração

Obrigatório.
Um evento de cobrança do conjunto de anúncios. Somente IMPRESSIONS é compatível com campanhas de compras Advantage+.

existing_customer_budget_percentage
número

Opcional.
Especifica a porcentagem máxima do orçamento que pode ser gasta com clientes existentes associados à conta de anúncios. Valores baixos podem levar a custos por conversão mais elevados. Valores válidos: entre "0" e "100".

adlabels

list<Object>

Opcional

Especifica uma lista de rótulos que serão associados ao objeto.

start_time
datetime

Opcional.
A hora de início do conjunto. Registro de data e hora UNIX (UTC).


Exemplo: 2015-03-12 23:59:59-07:00 ou 2015-03-12 23:59:59 PDT.

time_start
datetime

Opcional

Hora de início

time_stop
datetime

Opcional

Hora de encerramento.

attribution_spec

list<JSON Object>

Opcional.
Especificação da atribuição de conversão usada ao atribuir conversões para otimização.

Exemplo de criação do conjunto de anúncios

curl -X POST \
  -F 'name=Advantage+ Shopping Sample Ad Set' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'promoted_object={ "pixel_id": "<PIXEL_ID>", "CUSTOM_EVENT_TYPE": "PURCHASE" }' \
  -F 'daily_budget=<NUM>' \
  -F 'existing_customer_budget_percentage=<NUM>' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'targeting={"geo_locations": {"countries": ["US"]}}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/adsets

Atualização

Para atualizar um conjunto de anúncios, faça uma solicitação POST para /{ad_set_id}.

Parâmetros


ParâmetroDescrição

adlabels

list<Object>

Especifica uma lista de rótulos que serão associados ao objeto. Este campo é opcional.

daily_budget
int64

Orçamento diário definido na moeda da sua conta, permitido apenas para conjuntos de anúncios com duração (diferença entre end_time e start_time) maior que 24 horas.


daily_budget ou lifetime_budget precisa ser maior que "0".

existing_customer_budget_percentage
número

Especifica a porcentagem máxima do orçamento que pode ser gasta com clientes existentes associados à conta de anúncios. Valores baixos podem levar a custos por conversão mais elevados. Valores válidos: entre "0" e "100".

end_time
datetime

Hora de término, obrigatória quando lifetime_budget for especificado.


Exemplo: 2015-03-12 23:59:59-07:00 ou 2015-03-12 23:59:59 PDT.


Ao criar um conjunto de anúncios com um orçamento diário, especifique end_time=0 para definir o conjunto como "em andamento", sem data de término.


Registro de data e hora UNIX (UTC).

execution_options

list<enum>

Valor padrão: set. Outras opções são:

  • validate_only: quando esta opção for especificada, a chamada de API não realizará a mutação, mas executará as regras de validação em relação aos valores de cada campo.
  • include_recommendations: esta opção não pode ser usada sozinha. Quando ela for utilizada, serão incluídas recomendações para configuração do objeto de anúncio. Uma seção específica para recomendação será incluída na resposta, mas somente se existirem recomendações para tal especificação.

Se a chamada passar no processo de validação ou análise, a resposta será {"success": true}. Caso a chamada não seja aprovada, um erro será retornado com mais detalhes.

start_time
datetime

A hora de início do conjunto. Precisa ser fornecida como um registro de data e hora UNIX (UTC).


Exemplo: 2015-03-12 23:59:59-07:00 ou 2015-03-12 23:59:59 PDT.

status
enumeração

Opções disponíveis para atualização:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

Se for definido como PAUSED, todos os respectivos anúncios ativos serão pausados e terão um status efetivo de ADSET_PAUSED.

lifetime_budget
int64

Orçamento total, definido na moeda da sua conta. Se for especificado, será preciso definir também um end_time.


daily_budget ou lifetime_budget precisa ser maior que "0".

time_start
datetime

Hora de início

time_stop
datetime

Hora de encerramento.

targeting
Objeto de direcionamento

Estrutura de direcionamento do conjunto de anúncios. Valores válidos: geo_locations.

geo_locations
matriz

Obrigatório.
Usado para limitar o público do conjunto de anúncios.

attribution_spec

list<JSON Object>

Opcional.
Especificação da atribuição de conversão usada ao atribuir conversões para otimização.

Exemplo de atualização do conjunto de anúncios

curl -X POST \
  -F 'name=Advantage+ Shopping Sample Updated Ad Set' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<AD_SET_ID>

Etapa 5: fornecer um criativo e criar anúncios

Quando o conjunto de anúncios estiver pronto, crie seu anúncio publicando no ponto de extremidade /act_{ad_account_id}/ads. Os seguintes parâmetros podem ser incluídos:

Parâmetros


ParâmetroDescrição

name
string

Obrigatório.
Nome do anúncio.

adset_id
int64

Obrigatório.
Identificação do conjunto de anúncios, necessária na criação.

creative
AdCreative

Obrigatório.
Especificação ou identificação do criativo que será usado pelo anúncio. Campos válidos:

  • object_story_spec
  • product_set_id
  • use_page_actor_override
  • creative_id

Leia mais sobre criativos aqui.


Forneça o criativo neste formato: {"creative_id": <CREATIVE_ID>}.


Ou informe uma especificação de criativo:

{
        "creative": {
          "name": <NAME>, 
          "object_story_spec": <SPEC>,
          "product_set_id": <PRODUCT_SET_ID>
        }
}

status
enumeração

Opcional.
Apenas os status ACTIVE e PAUSED são válidos durante a criação. Durante os testes, é recomendável definir um status PAUSED para os anúncios a fim de evitar gastos acidentais.

adlabels

list<Object>

Opcional.
Rótulos de anúncios associados ao anúncio.

execution_options

list<enum>

Opcional.
Valor padrão: set.

  • validate_only: quando esta opção for especificada, a chamada de API não realizará a mutação, mas executará as regras de validação em relação aos valores de cada campo.
  • synchronous_ad_review: esta opção não deve ser usada sozinha. Deve ser sempre especificada com validate_only. Quando essas opções forem especificadas, a chamada de API realizará validações de integridade de anúncios, que incluem verificação do idioma da mensagem, regra de texto de 20% de imagem e assim por diante, bem como as lógicas de validação.
  • include_recommendations: esta opção não pode ser usada sozinha. Quando ela for utilizada, serão incluídas recomendações para configuração do objeto de anúncio. Uma seção específica para recomendação será incluída na resposta, mas somente se existirem recomendações para tal especificação.

Se a chamada passar no processo de validação ou análise, a resposta será {"success": true}. Caso a chamada não seja aprovada, um erro será retornado com mais detalhes.

Exemplo de criação de anúncio

curl -X POST \
  -F 'name=Advantage+ Shopping campaign Sample Ad' \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={"name": <NAME>, "object_story_spec": <SPEC>}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/ads

Campos do criativo

Para conferir uma lista completa de campos de criativo do anúncio, clique aqui.

CampoDescrição

object_story_spec
AdCreativeObjectStorySpec

Obrigatório.
Use esta opção se quiser criar uma nova publicação sem exibição na Página e transformar a publicação em um anúncio. A identificação da Página e o conteúdo para criar uma nova publicação sem exibição na Página.

use_page_actor_override
AdCreative

Obrigatório.
Ser for true, exibiremos a Página do Facebook associada aos anúncios de compras Advantage+.

Exemplo de geração de criativo

curl -X POST \
  -F 'object_story_spec=<SPEC>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/adcreatives

Atualização

Para atualizar um anúncio, faça uma solicitação POST para /{ad_id}.

Parâmetros


ParâmetroDescrição

name
string

Novo nome do anúncio.

adlabels

list<Object>

Rótulos de anúncios associados ao anúncio.

execution_options

list<enum>

Valor padrão: set. Outras opções são:

  • validate_only: quando esta opção for especificada, a chamada de API não realizará a mutação, mas executará as regras de validação em relação aos valores de cada campo.
  • synchronous_ad_review: esta opção não deve ser usada sozinha. Deve ser sempre especificada com validate_only. Quando essas opções forem especificadas, a chamada de API realizará validações de integridade de anúncios, que incluem verificação do idioma da mensagem, regra de texto de 20% de imagem e assim por diante, bem como as lógicas de validação.
  • include_recommendations: esta opção não pode ser usada sozinha. Quando ela for utilizada, serão incluídas recomendações para configuração do objeto de anúncio. Uma seção específica para recomendação será incluída na resposta, mas somente se existirem recomendações para tal especificação.

Se a chamada passar no processo de validação ou análise, a resposta será {"success": true}. Caso a chamada não seja aprovada, um erro será retornado com mais detalhes.

status
enumeração

As opções são as seguintes:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

Durante os testes, é recomendável definir um status PAUSED para os anúncios a fim de evitar gastos acidentais.

creative
AdCreative

Especificação do criativo do anúncio que deve ser usada pelo anúncio. Campos válidos: object_story_spec, asset_feed_spec e use_page_actor_override, que podem ser visualizados aqui. Leia mais sobre criativos aqui.


Forneça o criativo no seguinte formato:

{
    "creative": {
      "name": <NAME>, 
      "object_story_spec": <SPEC>,
      "product_set_id": <PRODUCT_SET_ID>
    }
}

Exemplo de atualização do anúncio

curl -X POST \
  -F 'name=Advantage+ Shopping campaign Sample Update Ad' \
  -F 'creative={"name": <NAME>, "object_story_spec": <SPEC>}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<AD_ID>

Saiba mais