API de Marketing

Primeiros passos

Siga os passos a seguir para criar seu primeiro anúncio com a API de Marketing.

Antes de começar

Conheça a Graph API e a estrutura da campanha de anúncios do Facebook. Assim que estiver com tudo pronto para fazer chamadas, você precisará do seguinte:

Depois disso, você pode começar. Lembre-se de consultar as boas práticas gerais para o uso da API de Marketing.

Etapa 1: criar uma campanha

Comece o processo com a criação de um novo objeto de campanha da classe Campaign. Neste momento, você precisa definir um objetivo para os anúncios que será a meta principal da campanha. Recomendamos que você crie inicialmente uma campanha PAUSED para não haver cobrança durante o teste.

curl -X POST \
  -F 'name="My campaign"' \
  -F 'objective="OUTCOME_TRAFFIC"' \
  -F 'status="PAUSED"' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/campaigns

Se o processo for realizado com sucesso, retornaremos um ID para a campanha de anúncios recém-criada. Lembre-se de salvar esse ID. Também é possível verificar se a campanha foi criada no Gerenciador de Anúncios.

Recursos:

Etapa 2: definir o direcionamento

Documentos de referência

Antes de criar os conjuntos de anúncios, é preciso definir seu público-alvo. Na próxima etapa, você criará um conjunto de anúncios e especificará os atributos do seu público.

Há muitas opções de direcionamento. Neste exemplo, usamos a pesquisa de direcionamento para encontrar valores predefinidos que podem ser usados para configurar um público.

Primeiro, vamos procurar países disponíveis que têm a palavra "united" ("unidos"):

curl -G \
  -d 'location_types=["country"]' \
  -d 'type=adgeolocation' \
  -d 'q=united' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Depois, podemos buscar interesses com a palavra "movie" ("filme"):

curl -G \
  -d 'type=adinterest' \
  -d 'q=movie' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Com base nos valores retornados nas chamadas acima, sabemos que é possível criar um público de pessoas nos Estados Unidos ("United States") que se interessam por filmes ("movies"). A especificação de direcionamento fica assim:

targeting={ 
    "geo_locations": {"countries":["US"]}, 
    "interests": [{id: 6003139266461, 'name': 'Movies'}]
}

Etapa 3: criar um conjunto de anúncios e definir orçamento, cobrança, otimização e duração

Um conjunto de anúncios é um grupo de anúncios com o mesmo orçamento diário ou total, além de programação, cobrança, otimização e dados de direcionamento. Nesta etapa, você precisa criar um objeto da classe AdSet e especificar o seguinte:

  • Duração – por quanto tempo seus anúncios serão veiculados. Use start_time e end_time na definição.
  • Orçamento – quanto você deseja gastar. Use daily_budget ou lifetime_budget.
  • Otimização – o resultado que você quer alcançar com seu anúncio. Use optimization_goal na configuração.
  • Cobrança – como você quer pagar. Use billing_event.
  • Lance – o valor que você atribuiu à ocorrência do evento de otimização. Use o campo bid_amount.
  • Direcionamento – use a especificação de direcionamento criada na Etapa 2.

Para criar o conjunto de anúncios, você também precisa da identificação da campanha de anúncios salva na Etapa 1:

curl \
  -F 'name=My Ad Set' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={"geo_locations": {"countries":["US"]}, "interests": [{id: 6003139266461, "name": "Movies"}]}' \
  -F 'start_time=2024-10-06T04:45:17+0000' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

Recomendamos criar um conjunto de anúncios com o status PAUSED para evitar cobranças durante o teste.

Etapa 4: fornecer um criativo do anúncio

Documentos de referência

Nesta etapa, você usará o objeto AdCreative para fornecer os elementos visuais do anúncio. As informações que devem ser fornecidas variam conforme o objetivo, mas os atributos mais comuns são os seguintes:

  • Imagens e vídeos
  • Título e descrição
  • Links
  • Botões de chamada para ação

Talvez seja necessário fornecer campos avançados, dependendo do seu objetivo. Por exemplo, é preciso fornecer uma URL da App Store no caso de anúncios de app para iOS.

Você pode definir o criativo como independente ou como parte de um conjunto de anúncios. Em ambos os casos, ele será armazenado na biblioteca de criativos da sua conta para uso em anúncios.

Exemplo

O exemplo a seguir mostra como fornecer uma imagem e criar o objeto AdCreative.

Primeiro, crie um objeto AdImage a partir de um arquivo de imagem:

curl \
  -F 'filename=@<IMAGE_PATH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/adimages

Depois, use o hash da imagem para criar o AdCreative:

curl -X POST \
  -F 'name="Sample Creative"' \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "link_data": {
         "image_hash": "<IMAGE_HASH>",
         "link": "https://facebook.com/<PAGE_ID>",
         "message": "try it out"
       }
     }' \
  -F 'degrees_of_freedom_spec={
      "creative_features_spec": {
        "standard_enhancements": {
          "enroll_status": "OPT_IN"
        }
      }
    }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

Acesse a Biblioteca de mídia no Gerenciador de Anúncios para verificar o carregamento da imagem.

No momento, o AdCreative com seu link ainda não está visível no Gerenciador de Anúncios. Esse dado será exibido depois que você programar o anúncio. É possível depurar o criativo do anúncio com o Explorador da Graph API e especificar os campos que você quer ler:

GET /{my-creative-id} HTTP/1.1
Host: graph.facebook.com/?fields=object_story_spec

Etapa 5: programar a veiculação

Por fim, crie seu objeto de anúncio para vincular AdCreative e AdSet. Para evitar fazer um pedido instantaneamente, defina o status do Ad como paused.

curl -X POST \
  -F 'name="My Ad"' \
  -F 'adset_id="&lt;AD_SET_ID&gt;"' \
  -F 'creative={
       "creative_id": "<CREATIVE_ID>"
     }' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/ads

Verifique se o anúncio existe no Gerenciador de Anúncios. Clique na campanha recém-criada, no conjunto de anúncios e no anúncio.

Depois que se acostumar a programar anúncios com a API, defina o status como active. Primeiro, o anúncio passará pela análise e terá o status PENDING_REVIEW. Após a conclusão da análise, o anúncio voltará a ter o status ACTIVE.

Como copiar anúncios

Como alternativa, você pode copiar um anúncio, ativo ou campanha existente. Isso ajuda a duplicar rapidamente uma campanha para alterar as configurações ou criar grupos de teste para saber mais sobre o desempenho. Para obter mais detalhes, consulte: