Objetivo de tráfego para o estabelecimento - API de Marketing - Documentação

Posicionamentos

Disponível para Facebook no celular e no computador (feed, stories e marketplace) e Instagram (feed, stories, reels, feed do perfil, página inicial do Explorar, reels do perfil).

Otimização da veiculação

Otimização de alcance – disponível a todos os anunciantes com acesso a essa API. Otimiza para alcance diário único e exibe "Impressões" como a métrica padrão em relatórios do Gerenciador de Anúncios.

Como criar anúncios de catálogo Advantage+

Para criar anúncios de catálogo Advantage+ com esse objetivo, a Página precisa usar as Localizações no Facebook.

Requisitos

As campanhas precisam definir objective como STORE_VISITS.
Nas campanhas, é preciso que promoted_object esteja definido como o <PARENT_PAGE_ID> correspondente.
O promoted_object e o targeting do conjunto de anúncios precisam conter um place_page_set_id de um <PAGE_SET_ID>.
A optimization_goal do conjunto de anúncios precisa ser definida como REACH.
O billing_event do conjunto de anúncios deve ser IMPRESSIONS.

Passo 1. criar um `PageSet`

O Facebook usa PageSet para fazer o direcionamento de anúncios e como o objeto promovido no seu anúncio.

Para criar um PageSet, faça o seguinte:

Colete localizações de estabelecimentos, isto é, Páginas do Facebook para cada loja física e as localizações da sua empresa principal. Sua empresa principal é conhecida como Página principal.
Crie uma estrutura JSON de localizações que represente todas as suas localizações.
Crie o PageSet com a estrutura JSON de localizações.

Coletar todas as localizações de estabelecimentos

O <PARENT_PAGE_ID> é a identificação da Página principal de todas as suas localizações de estabelecimentos. Ele recupera todas as Páginas e localizações de estabelecimentos que pertencem a uma Página principal e retorna a longitude e a latitude de cada localização:

curl -X GET \
  -d 'fields="location{latitude,longitude},is_permanently_closed"' \
  -d 'limit=30000' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PARENT_PAGE_ID>/locations

Exemplo de saída

{
    "data": [
        {
            "location": {
                "latitude": 29.173384,
                "longitude": 48.098807
            },
            "is_permanently_closed": false,
            "id": "1788030244802584"
        },
        {
            "location": {
                "latitude": 29.303635,
                "longitude": 47.937725
            },
            "is_permanently_closed": false,
            "id": "261533444245300"
        },
        {
            "location": {
                "latitude": 29.302303,
                "longitude": 47.933178
            },
            "is_permanently_closed": false,
            "id": "179435399132774"
        },
        {
            "location": {
                "latitude": 29.302591,
                "longitude": 47.931801
            },
            "is_permanently_closed": false,
            "id": "1790317704582144"
        }
    ],
    "paging": {
        "cursors": {
            "before": "MTc4ODAzMDI0NDgwMjU4NAZDZD",
            "after": "MTA4MTU4NjU5NjA5MDA4"
        }
    }
}

Criar uma estrutura JSON de localizações

Reveja cada entrada nos resultados retornados para garantir que todas as localizações estejam abertas para funcionamento. Para fazer isso, verifique o campo is_permanently_closed.

Obtenha o raio estimado usando duas solicitações GET para conseguir os parâmetros radius e distance_unit. Como alternativa, é possível fazer uma chamada de API em lote para gerar os valores abaixo.

Solicitações individuais

Para fazer essa solicitação, use a latitude e a longitude dos resultados JSON retornados para a Página principal. Isso retornará o raio estimado de cada localização.

curl -X GET \
  -d 'type="adradiussuggestion"' \
  -d 'latitude=51.5152253' \
  -d 'longitude=-0.1423029' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/search/

Solicitações em lote

Também é possível agrupar diversas solicitações em uma só.

curl \
  -F "access_token=<ACCESS_TOKEN>" \
  -F "include_headers=false" \
  -F "batch=[
    {
      \"method\": \"GET\",
      \"relative_url\": \"/<API_VERSION>/search?type=adradiussuggestion&amp;latitude=29.173384&amp;longitude=48.098807\"
    },
    {
      \"method\": \"GET\",
      \"relative_url\": \"/<API_VERSION>/search?type=adradiussuggestion&amp;latitude=29.303635&amp;longitude=47.937725\"
    }
  ]" \
  "https://graph.facebook.com"

Última estrutura JSON de localizações

Use os parâmetros radius e distance_unit obtidos nas chamadas anteriores e o <CHILD_LOCATION_ID> de cada localização como o page_id para criar a última estrutura JSON de localizações.

[
    {
      "page_id": 1788030244802584,
      "radius": 1,
      "distance_unit": "mile"
    },
    {
      "page_id": 261533444245300,
      "radius": 1,
      "distance_unit": "mile"
    }
]

Criar o `Pageset` com a estrutura JSON de localizações

No momento, o ponto de extremidade PageSet está disponível apenas aos parceiros na lista de permissão. Entre em contato com seu representante do Facebook para obter acesso.

Agora você pode criar um PageSet com as informações da estrutura JSON de localizações.

O número máximo de localizações que podem ser usadas em um PageSet é 10 mil.

Solicitações assíncronas

Você pode fazer uma solicitação assíncrona para criar seu PageSet. Dessa forma, será possível criar PageSets grandes, com mais de 1.000 localizações, sem atingir o tempo limite. Recomendamos usar solicitações assíncronas quando for necessário criar um Pageset com mais de 50 localizações.

Solicitação

curl -X POST \
  -d 'name=<AD_SET_NAME>' \
  -d 'parent_page=<PARENT_PAGE_ID>' \
  -d 'pages=[{"page_id":<CHILD_PAGE_ID>}]' \
  -d 'metadata={"audience":{"size":<AUDIENCE_SIZE>}}' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets_async/

Observação: é possível usar /ad_place_page_sets para solicitações síncronas, mas é necessário utilizar solicitações assíncronas quando houver mais de 50 localizações.

O formato dos parâmetros é o mesmo utilizado com as solicitações assíncronas.

No PageSet, use o campo metadata para especificar um raio fixo por localização para a veiculação de anúncio ou para alcançar determinado tamanho de público. Caso você selecione a última opção, o Facebook calculará automaticamente um raio por localização para alcançar esse número de contas da Central de Contas.

Neste exemplo, o campo metadata foi definido como um tamanho de audience desejado. Consulte metadata para raios. Isso retorna um ID de ad_place_page_set_async_request.

{
  "id": "405738580111111"
}

Depois, você pode consultar essa ID com a permissão ads_read para obter a ID de PageSet.

curl -i -X GET \
 "https://graph.facebook.com/<API_VERSION>/405738580111111?access_token=ACCESS_TOKEN"

Exemplo de saída

{
  "id": "405738580111111", 
  "place_page_set": {
    "id": "555555791481678",
    "name": "test_ad_set"
  },
  "progress": 1
}

O progress varia de 0.0 a 1. 1 indica que a solicitação foi concluída e um PageSet foi criado.

Como usar `metadata` para raios

O campo metadata informa ao Facebook se você quer usar um raio fixo para as localizações ou se prefere o cálculo automático dos raios por localização com base no tamanho do público.

Solicitação

Para especificar um raio fixo usando uma solicitação síncrona:

curl -X POST \
  -d 'name=<PAGE_SET_NAME>' \
  -d 'parent_page=<PARENT_PAGE_ID>' \
  -d 'pages=[{"page_id":<CHILD_PAGE_ID>}]' \
  -d 'metadata={"fixed_radius":{"value":5,"distance_unit":"mile"}}' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets/

Assim, você indica ao Facebook para veicular o anúncio a pessoas dentro de um raio de 5 milhas de todas as localizações de PageSet.

Exemplo de saída

{
  "id": "1618547271777777"
}

Observação: o campo metadata deve ser definido como fixed_radius ou audience.

Se você usar fixed_radius, será preciso indicar distance_unit e value:

{
  "fixed_radius": {
     "distance_unit": "<distance_unit>",
     "value": <distance>
  }
}

Se você usar audience, será preciso indicar size, mas max_radius será opcional

Nota: esta operação só funciona com ad_place_page_sets_async

 {
  "audience": {
     "size": <audience_size>,
     "max_radius": { // optional
       "distance_unit": "<distance_unit>",
       "value": <distance>
     }
  }
}

Boas práticas para metadata

Também é necessário fornecer locations. Porém, não especifique um raio. Por outro lado, se você usar o parâmetro locations e informar raios, não faça isso para metadata.
A distance_unit deve estar em mile ou kilometer e o value deve estar entre 0.7 e 50 para mile ou entre 1 e 80 para kilometer.
O parâmetro size em audience corresponde ao número de contas da Central de Contas no raio, desde que o raio tenha entre 1 e 80 quilômetros de comprimento. Se você fornecer um max_radius, calcularemos valores entre 1 e max_radius no raio real.
Caso especifique audience para metadata, será necessário fazer sua solicitação com o ponto de extremidade assíncrono (ad_account_ID/ad_place_page_set_async).

Solicitações síncronas

Ainda é possível usar solicitações síncronas para criar um PageSet.

curl -X POST \
  -d "name=<PAGESET_NAME>" \
  -d "parent_page=<PARENT_PAGE_ID>" \
  -d "pages=<LOCATIONS_JSON_STRUCTURE>" \
  -d "access_token=<ACCESS_TOKEN>" \
 https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets

Essa operação retorna uma ID de PageSet para uso posterior.

Exemplo de saída

{
  "id": <PAGE_SET_ID>
}

Caso o número de páginas seja grande demais para uma chamada de cURL, você pode criar um arquivo de texto com a estrutura JSON das localizações e indicá-lo no atributo pages com -F "pages=<locations_json_structure.txt".

Etapa 2: criar uma campanha

Crie uma campanha de anúncios com o objetivo definido como STORE_VISITS e a identificação da Página principal como o objeto promovido.

Consulte a referência sobre campanha de anúncios.

Etapa 3: criar um conjunto de anúncios

Crie um conjunto para o anúncio. Consulte as referências sobre conjunto de anúncios, especificações de direcionamento e localizações de Página.

No momento da veiculação, o Facebook invalida as localizações de direcionamento dos anúncios que estiverem a mais de 50 milhas da localização de Página mais próxima, conhecida como Página local.

curl \
  -F 'name=Store Visits Ad Set' \
  -F 'promoted_object={"place_page_set_id":"<PAGE_SET_ID>"}' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'is_autobid=true' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F "targeting={
    'age_min' : <MIN_AGE>,
    'age_max' : <MAX_AGE>,
    'place_page_set_ids': ['<PAGE_SET_ID>'],
    'device_platforms': ['mobile','desktop'],
    'facebook_positions': ['feed']
   }" \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

Direcionamento geográfico

Também é possível fazer o direcionamento por geo_locations nas campanhas de tráfego para o estabelecimento.

Observação: para esse objetivo, você pode usar apenas geo_locations ou place_page_set_ids no direcionamento de conjuntos de anúncios.

Aceitamos todos os tipos de direcionamento por geo_location para direcionamento e posicionamento avançados, inclusive por países, cidades e códigos postais. Além disso, você pode selecionar location_types, como recent, home ou travel_in.

Também será necessário fornecer place_page_set_id no promoted_object. O PageSet precisa ser um conjunto de Páginas sem localizações explícitas. Consulte Como criar o PageSet com a estrutura JSON de localizações para criar o PageSet. Porém, não encaminhe as Páginas de parâmetro nesse caso.

Primeiro, crie um PageSet para depois fornecê-lo em um objeto promovido:

curl -X POST \
  -d "name=My geo targeting page set" \
  -d "parent_page=<PARENT_PAGE_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets/

Observação: não há necessidade de fornecer o parâmetro pages como você faria normalmente.

Depois, crie um conjunto de anúncios com o objetivo de tráfego para o estabelecimento com direcionamento por geo_locations:

curl \
  -F 'name=Store Traffic Ad Set' \
  -F 'promoted_object={"place_page_set_id":"<PAGE_SET_ID>"}' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'is_autobid=true' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F "targeting={
    'geo_locations': {"countries":["US"],"location_types": ["home"]}, 
    'device_platforms': ['mobile','desktop'],
    'facebook_positions': ['feed']
  }" \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

De forma automática, veiculamos os anúncios para a loja mais próxima à pessoa que visualizar seu anúncio.

Etapa 4: fornecer um criativo do anúncio

Você pode inserir criativos de forma dinâmica com base na localização de uma pessoa. Personalize o criativo por meio de um conjunto de espaços reservados de modelo. No momento da veiculação, o Facebook substituirá esses espaços nos anúncios pelos dados da localização de Página mais próxima.

Espaços reservados disponíveis:

{{page.hours.today}}
{{page.location.city}}
{{page.location.region}}
{{page.location.postcode}}
{{page.location.street_address}}
{{page.name}}
{{page.phone_number}}

O campo dynamic_ad_voice permite que você controle a voz do anúncio:

Se dynamic_ad_voice for definida como DYNAMIC, o nome da Página e a foto de perfil na sua publicação de anúncio virão da localização de Página mais próxima.
Se dynamic_ad_voice for definida como STORY_OWNER, o nome da Página e a foto de perfil na sua publicação de anúncio virão da localização da Página principal.

Chamada para ação

Também é possível adicionar de forma dinâmica botões de chamada para ação (CTA, pelas iniciais em inglês) com base na localização de uma pessoa:

Ao usar GET_DIRECTIONS ou CALL_NOW, o campo value da CTA não é obrigatório. Os usuários serão direcionados automaticamente à localização mais próxima ou deverão ligar para o telefone mais próximo.
MESSAGE_PAGE é permitida somente se dynamic_ad_voice for definida como STORY_OWNER. As mensagens serão entregues à Página principal.
Campo opcional. Caso não seja especificado para anúncios individuais, exibiremos um botão Like Page.

Consulte a referência sobre o criativo do anúncio para saber mais.

Tipo de dynamic_ad_voice Tipo de call_to_action

Tipo de `dynamic_ad_voice`	Tipo de `call_to_action`
`DYNAMIC`	`CALL_NOW` `GET_DIRECTIONS`
`STORY_OWNER`	`CALL_NOW` `GET_DIRECTIONS` `LEARN_MORE` `MESSAGE_PAGE` `ORDER_NOW` `SHOP_NOW`

DYNAMIC

CALL_NOW

GET_DIRECTIONS

STORY_OWNER

CALL_NOW

GET_DIRECTIONS

LEARN_MORE

MESSAGE_PAGE

ORDER_NOW

SHOP_NOW

Exemplos

Forneça um criativo do anúncio usando a cidade e o nome da Página dinâmica:

curl \
  -F 'dynamic_ad_voice=DYNAMIC' \
  -F 'object_story_spec={ 
    "page_id": "<PARENT_PAGE_ID>", 
    "template_data": { 
      "description": "Ad Description", 
      "link": "<URL>", 
      "message": "Ad Message for {{page.location.city}}", 
      "name": "{{page.name}}", 
      "picture": "<IMAGE_URL>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

Criativo do anúncio com cartão de mapa

Para usar um cartão de mapa, adicione uma estrutura place_data como anexo no campo child_attachments do criativo do anúncio.

No exemplo, o mapa com um link do localizador de lojas no Facebook é o segundo item na matriz child_attachments. É necessário fornecer pelo menos um item além do cartão de mapa.

curl \
  -F 'dynamic_ad_voice=DYNAMIC' \
  -F 'object_story_spec={ 
    "page_id": "<PARENT_PAGE_ID>", 
    "template_data": { 
      "description": "Ad Description", 
      "link": "<URL>", 
      "message": "Ad Message for {{page.location.city}}", 
      "name": "{{page.name}}", 
      "child_attachments":[
        {
          "description": "Come visit us!",
          "link": "http://yourweburl.com",
          "name": "{{page.location.street_address}} - {{page.location.city}}",
          "call_to_action": {
            "type":"GET_DIRECTIONS"
          },
        },
        {
          "link": "https://fb.com/store_locator",
          "name": "Check out our stores.",
          "place_data": {
            "type":"DYNAMIC"
          },
        }
      ]
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

Destino do link do localizador de lojas

Ao criar um anúncio, se você definir link como "https://fb.com/store_locator", o destino do link do anúncio será o localizador de lojas.

Etapa 5: criar um anúncio

Crie um anúncio da seguinte forma:

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

Para criar anúncios de tráfego para o estabelecimento, a Página e a conta de anúncios devem ter aprovação para usar a mensuração de visitas ao estabelecimento. Caso contrário, um erro parecido com Reach estimate isn't available because 'store_visits' isn't a valid action type será exibido.

Mensuração de visitas ao estabelecimento

As visitas ao estabelecimento são uma métrica baseada nos dados de usuários que habilitaram os serviços de localização. Além de mensurar as visitas, ela otimiza o objetivo de tráfego para o estabelecimento. Essa mensuração está disponível apenas para campanhas com o objetivo de tráfego para o estabelecimento.

As visitas ao estabelecimento se baseiam nos cliques e nas visualizações de anúncios que usam o objetivo de tráfego para o estabelecimento. Trata-se do número estimado das visitas às lojas de um anunciante por contas da Central de Contas que viram ou clicaram nos anúncios de cada estabelecimento. Você pode configurar a janela de atribuição e personalizá-la com base nos cliques e nas visualizações de 1, 7 ou 28 dias. A atribuição padrão da conta de anúncios será aplicada, a não ser que você personalize a configuração. Consulte a documentação da janela de atribuição da API de Insights.

Os recursos se relacionam aos relatórios dos itens a seguir:

Visitas ao estabelecimento – o número de visitas estimadas à sua loja como resultado dos anúncios.
Custo por visita ao estabelecimento – o custo médio de cada visita estimada às suas lojas como resultado dos anúncios.

Com o Gerenciador de Anúncios

Consulte as colunas em ENGAGEMENT: ACTIONS. As colunas aparecem na interface de geração de relatórios para visitas ao estabelecimento e o custo por visita ao estabelecimento.

Observação: os dados de visita ao estabelecimento estão disponíveis apenas para lojas que a equipe do Facebook confirmou como mensuráveis para uma campanha.

Com a API de Insights

É possível obter dados sobre as visitas ao estabelecimento com a API de Insights. Fornecemos os campos adicionais cost_per_store_visit_action e store_visit_actions nas chamadas de insights gerais. Consulte a referência sobre insights.

Parâmetros

Campo Descrição

Campo	Descrição
`point_estimate` int32	The point prediction of the value Padrão

point_estimate

int32

The point prediction of the value

Padrão

Posicionamentos

Otimização da veiculação

Como criar anúncios de catálogo Advantage+

Requisitos

Passo 1. criar um PageSet

Coletar todas as localizações de estabelecimentos

Criar uma estrutura JSON de localizações

Solicitações individuais

Solicitações em lote

Última estrutura JSON de localizações

Criar o Pageset com a estrutura JSON de localizações

Solicitações assíncronas

Como usar metadata para raios

Solicitações síncronas

Etapa 2: criar uma campanha

Etapa 3: criar um conjunto de anúncios

Direcionamento geográfico

Etapa 4: fornecer um criativo do anúncio

Chamada para ação

Exemplos

Criativo do anúncio com cartão de mapa

Destino do link do localizador de lojas

Etapa 5: criar um anúncio

Mensuração de visitas ao estabelecimento

Com o Gerenciador de Anúncios

Com a API de Insights

Parâmetros

Passo 1. criar um `PageSet`

Criar o `Pageset` com a estrutura JSON de localizações

Como usar `metadata` para raios