Version 2.11

API de Marketing

Lançada em 7 de novembro de 2017 | Disponível até 7 de agosto de 2018 | Publicação de blog

• Novos recursos
• Alterações disruptivas
• Itens que se tornaram obsoletos
• Itens que já se tornaram obsoletos

Novos recursos

Novo design da API do Gerenciador de Negócios

Agora, temos um novo relacionamento que representa clientes e agências. No passado, não tínhamos user. Gerenciávamos o acesso e os convites para uma empresa e os seus ativos por meio de bid/userpermissions, o que causava problemas de desempenho. Os destaques da nova API incluem o seguinte:

• Usuário no escopo da empresa: o novo usuário fica atrelado e tem permissões no escopo de uma empresa específica. Ele pode gerenciar o próprio perfil, as permissões e o acesso a ativos associados à empresa.
• Convites: convide pessoas para acessar uma empresa por meio de novos pontos de extremidade. Neles, é possível verificar e atualizar o status dos convites a usuários.
• Categorias de ativos: divida diferentes tipos de ativos em categorias e estabeleça pontos de extremidade para cada uma delas. Com isso, é mais fácil dividir os resultados em páginas para ler ativos. Isso também reduz os problemas de desempenho ao gerenciar milhares de ativos de uma empresa. Nesse novo design, adicionamos diversos pontos de extremidade.

Para acessar os usuários em uma empresa:

• BUSINESS_ID/business_users
• BUSINESS_ID/system_users
• BUSINESS_ID/pending_users

Para acessar os ativos atribuídos a usuários:

• BUSINESS_USER_ID/assigned_pages
• BUSINESS_USER_ID/assigned_ad_accounts
• BUSINESS_USER_ID/assigned_product_catalogs
• SYSTEM_USER_ID/assigned_pages
• SYSTEM_USER_ID/assigned_ad_accounts
• SYSTEM_USER_ID/assigned_product_catalogs
• PENDING_USER_ID/assigned_pages
• PENDING_USER_ID/assigned_ad_accounts
• PENDING_USER_ID/assigned_product_catalogs

Para acessar as páginas da empresa:

• BUSINESS_ID/owned_pages: para obter a lista de Páginas pertencentes à empresa
• BUSINESS_ID/client_pages: para obter a lista de Páginas pertencentes a clientes da empresa
• BUSINESS_ID/pending_owned_pages: para obter a lista de Páginas pertencentes à empresa que estão aguardando aprovação
• BUSINESS_ID/pending_client_pages: para obter a lista de Páginas pertencentes a clientes da empresa e aguardando aprovação

Para acessar as contas de anúncios da empresa:

• BUSINESS_ID/owned_ad_accounts: para obter a lista de contas de anúncios pertencentes à empresa
• BUSINESS_ID/client_ad_accounts: para obter a lista de contas de anúncios pertencentes a clientes da empresa
• BUSINESS_ID/pending_owned_ad_accounts: para obter a lista de contas de anúncios pertencentes à empresa que estão aguardando aprovação
• BUSINESS_ID/pending_client_ad_accounts: para obter a lista de contas de anúncios pertencentes a clientes da empresa e aguardando aprovação

Para acessar catálogos de produtos da empresa

• BUSINESS_ID/owned_product_catalogs: para obter a lista de catálogos de produtos pertencentes à empresa
• BUSINESS_ID/client_product_catalogs: para obter a lista de catálogos de produtos pertencentes a clientes da empresa

Para acessar os apps da empresa:

• BUSINESS_ID/owned_apps: para obter a lista de apps pertencentes à empresa
• BUSINESS_ID/client_apps: para obter a lista de apps pertencentes a clientes da empresa
• BUSINESS_ID/pending_client_apps: para obter a lista de apps pertencentes a clientes da empresa e aguardando aprovação

Para obter mais informações, consulte API do Gerenciador de Negócios, Usuários do sistema, Gerenciamento de ativos comerciais e Melhores práticas.

Anúncios em carrossel, localização em tempo real

Agora, é possível criar anúncios em carrossel com um anexo que mostre a localização em tempo real. Adicionamos as opções type=REALTIME e location_source_id = PAGE_ID em place_data para AD_CREATIVE_ID/object_story_spec. Isso está disponível no campo object_story_spec em:

• POST /AD_ACCOUNT_ID/adcreatives
• GET CREATIVE_ID

Visitas ao estabelecimento, direcionamento por localização

Agora, é possível fazer o direcionamento em áreas geográficas que ultrapassam o raio do seu estabelecimento físico. Adicionamos o parâmetro geo_locations no campo targeting_specs ao criar um conjunto de anúncios com o objetivo de visita ao estabelecimento. Com disponibilidade limitada. Consulte o seu representante do Facebook para ter acesso. Consulte Objetivo de tráfego para o estabelecimento.

• POST AD_ACCOUNT_ID/adsets tem a nova opção.
• Compatível com todas as áreas geográficas em Locations, exceto com o direcionamento por country_groups e tipo de localização travel_in.
• Consulte Store Visits para criar anúncios com o objetivo STORE_VISITS (disponível com frequência limitada).

Conjunto de anúncios, tipos de destino

Isso reflete o tipo de destino ao qual o anúncio está vinculado; ou seja, onde a pessoa vai quando clica em um anúncio ou uma chamada para ação. Assim, é fornecido um tipo de destino consistente para todos os anúncios em um conjunto, de forma que contenham somente tipos diferentes de criativo. Consulte Tipo de destino do conjunto de anúncios.

• Adicionamos destination_type para conjuntos de anúncios.
• Disponível em /ADSET_ID.

Indicador-chave de desempenho

Adicionamos o novo campo kpi_type a AD_ACCOUNT_ID/CAMPAIGN_ID, que descreve o tipo do indicador-chave de desempenho a ser rastreado na campanha ou no objetivo do anúncio. Para ver dados de insights por kpi_type no kpi_results, faça estas chamadas:

• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights

Para mais informações, consulte Campaign.

Alterações disruptivas

Gerenciamento de anúncios

• Invalidar direcionamento de anúnciosright_hand_column: o direcionamento de anúncios nessa posição com criativos inválidos para right_hand_column em AD_ACCOUNT_ID/adsets retorna um erro. Não permitimos o posicionamento somente em right_hand_column com vídeo ou coleção nem no formato dos anúncios do canvas. Para o posicionamento somente em right_hand_column, você pode usar somente formatos de imagem única e carrossel.

• AlteradoGET VERSION/RF_PREDICTION_ID/pause_periods: para retornar Array (não String) e facilitar o processamento.

API do Gerenciador de Negócios

• Campos renomeados: o campo admin_system_user foi renomeado como admin, e system_user como employee. Isso afeta as seguintes bordas:

  • /{business-id}/userpermissions
  • /{business-id}/system_users

Itens que se tornaram obsoletos

Gerenciamento de anúncios

Otimizações de VIDEO_VIEWS obsoletas: as campanhas com o objetivo VIDEO_VIEWS não podem mais usar CLICKS, IMPRESSIONS, PAGE_ENGAGEMENT, POST_ENGAGEMENT ou REACH como metas de otimização:

• Um erro será retornado se você criar conjuntos de anúncios com essas metas de otimização.
• Se você duplicar conjuntos de anúncios com a meta de otimização REACH, eles serão convertidos automaticamente para a meta VIDEO_VIEWS.
• Um erro será retornado se você duplicar conjuntos de anúncios com a meta de otimização CLICKS, IMPRESSIONS, PAGE_ENGAGEMENT ou POST_ENGAGEMENT. Isso porque, ao criar ou duplicar o anúncio em um conjunto existente, ocorre a tentativa de reutilizar uma dessas metas.

Estas são as bordas afetadas pela alteração:

• POST ACCOUNT_ID/adsets
• POST AD_ACCOUNT_ID/ads
• POST CAMPAIGN_ID/copies
• POST ADSET_ID/copies
• POST AD_ID/copies

reach obsoleto: como um optimization_goal para o objetivo de reconhecimento da marca. Removido para /adset. Disponível somente para a otimização de lembrança do anúncio. Isso evita confusões quando as pessoas usam o alcance como um objetivo dedicado.

Otimização BRAND_AWARENESS obsoleta: substituída por AD_RECALL_LIFT. Isso reflete um modelo de veiculação de anúncios novo e mais eficiente. A nova meta de otimização é compatível com criativos mistos, como anúncios estáticos e de vídeo no mesmo conjunto e lance manual. BRAND_AWARENESS não está mais disponível em:

• POST /ADSET_ID
• GET /ADSET_ID
• POST /AD_ACCOUNT_ID/adsets

frequency_cap obsoleto: incluindo os campos lifetime_frequency_cap e frequency_cap_reset_period em:

• POST AD_ACCOUNT_ID/adsets
• GET /ADSET_ID
• POST /ADSET_ID

Em vez disso, use frequency_control_specs.

Custo por ação POST_ENGAGEMENT obsoleto: não é mais possível usar POST_ENGAGEMENT como billing_event nesse objetivo. Isso alinha melhor a veiculação de anúncios e a mensuração. O ponto de extremidade /AD_SET_ID é impactado.

Insights e mensuração de anúncios

video_15_sec_watched_actions obsoleto em:

• GET AD_ACCOUNT_ID/insights
• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights
• POST AD_ACCOUNT_ID/insights
• POST CAMPAIGN_ID/insights
• POST ADSET_ID/insights
• POST AD_ID/insights

recurrence_value obsoleto: na API de Mensuração Avançada. O campo também ficou conhecido na API de Atlas como programação do relatório. Ele foi substituído por recurrence_values. Consulte Advanced Measurement.

Gerenciamento de negócios

Estes pontos de extremidade ficaram obsoletos no novo design da API do Gerenciador de Negócios:

• BUSINESS_ID/userpermissions
• BUSINESS_ID/business_persona
• business_persona_id

Estes pontos de extremidade para gerenciar ativos ficaram obsoletos:

• BUSINESS_ID/pages
• BUSINESS_ID/adaccounts
• BUSINESS_ID/product_catalogs
• BUSINESS_ID/apps

Para acessar os ativos, use BUSINESS_ID/owned_ASSET ou BUSINESS_ID/client_ASSET.

Estes pontos de extremidade para gerenciar ativos pertencentes a outra empresa ficaram obsoletos:

• BUSINESS_ID/assigned_ad_accounts
• BUSINESS_ID/assigned_pages
• BUSINESS_ID/assigned_product_catalogs

Em vez disso, use BUSINESS_USER_ID/assigned_ASSET.

Itens que já se tornaram obsoletos

Os itens obsoletos são aplicáveis a todas as versões da API e entrarão em vigor em 14 de novembro de 2017.

Anúncios de evento e com link

A criação e a edição de anúncios de evento ou com link que não estejam conectados a uma página válida ficaram obsoletas. O formato a seguir não é mais válido e retorna um erro.

Estas assinaturas ficarão obsoletas:

• Anúncios de evento

  • Objetivo: EVENT_RESPONSES
  • Campos de criativo: body, object_id
• Anúncios com link

  • Objetivo: LINK_CLICKS
  • Campos de criativo: title, body, object_url (image_file ou image_hash)

Assinaturas compatíveis

• Anúncios de evento

  • Objetivo: EVENT_RESPONSES
  • Campos de criativo: object_story_id ou object_story_spec
• Anúncios com link

  • Objetivo: LINK_CLICKS
  • Campos de criativo: object_story_id ou object_story_spec

Os anúncios de evento ou com link já criados continuarão em veiculação. Porém, não será possível alterar o criativo nem criar novos anúncios depois que a alteração entrar em vigor; caso contrário, você receberá erros. Consulte Anúncios locais e de evento e Ad.