Graph API

Versão 3.1

Lançado em 26 de julho de 2018 | Disponível até 27 de outubro de 2020 | Publicação do blog

Geral

Estas alterações se aplicam à v3.1 e a versões posteriores e serão aplicadas a todas as versões no dia 24 de outubro de 2018.

Todos os pontos de extremidade da Graph API agora retornam todas as estruturas vazias como {}, e todas as listas vazias como [].

Live API

Estas alterações se aplicam a versões posteriores à v3.1 e serão aplicadas a todas as versões no dia 24 de outubro de 2018.

O parâmetro type foi descontinuado para as seguintes bordas. Ele foi substituído por um novo parâmetro source.

  • /event/live_videos
  • /group/live_videos
  • /official_events/live_videos
  • /page/live_videos
  • /user/live_videos

O novo parâmetro source pode aceitar um dos dois valores possíveis: target e owner. A consulta à borda /live_videos de um nó com source=target retorna vídeos ao vivo transmitidos para esse nó, enquanto a consulta a source=owner retorna vídeos ao vivo transmitidos por esse nó.

Os nós de eventos e grupos somente aceitam consultas target, e algumas consultas target poderão falhar se você não tiver permissão para visualizar o nó de destino.

API de Marketing

Lançado em 26 julho de 2018 | Disponível até 14 de maio de 2019 | Publicação de blog

Gerenciamento de anúncios

  • Categorias de direcionamento baseadas em comportamento - Nós descontinuamos algumas opções de direcionamentos baseados em comportamentos usadas em behaviors. Se você tentar criar anúncios com alguma dessas categorias, obterá o erro The category you selected is no longer available. Para verificar as categorias válidas disponíveis para direcionamento, use a Pesquisa de direcionamento.

  • ObsoletoPAGE_ENGAGEMENTcomooptimization_goal – PAGE_ENGAGEMENT tornou-se obsoleto como um optimization_goal para campanhas de anúncios. A partir da versão v3.1, não é mais possível criar, atualizar ou duplicar campanhas de anúncios com optimization_goal definido como PAGE_ENGAGEMENT. Se você tiver campanhas de anúncios existentes e que foram criadas antes da versão v3.1, ainda será possível veicular essas campanhas com essa configuração. Você também ainda pode usar PAGE_ENGAGEMENT como um detalhamento da API de Informações para os dados em campanhas de anúncios existentes usando este optimization_goal.

  • Anúncios de curtida na Página de imagem única sem publicação estão obsoletos – A partir da versão v3.1, não é mais possível criar Anúncios de curtida na Página de imagem única sem uma publicação da Página. Em vez disso, você deve criar um Anúncio de curtida na Página com uma publicação. Veja Criativo, posicionamento e prévias, Como criar anúncios de curtida na Página.

  • Fim da recuperação de anúncios de cadastro por Webhooks para o nível de desenvolvimento – Nós não enviaremos mais dados coletados em formulários de Anúncios de Cadastro por meio de webhooks para aplicativos no Modo de Desenvolvimento. Essa alteração começará a ser aplicada no dia 1º de fevereiro de 2019.

    • Se você assinar as atualizações na v3.1, não enviaremos nenhuma a menos que seu aplicativo esteja em produção e no Modo Publicado.

    • Se você criar um novo aplicativo depois que a v3.1 estiver disponível, não enviaremos nenhuma atualização, a menos que seu aplicativo esteja em produção e no Modo Publicado.

    • Se você tiver um aplicativo existente, ele precisará estar no Modo Publicado até 1º de fevereiro de 2019. Até essa data, você continuará a receber atualizações no Modo de Desenvolvimento.

    Para ver mais informações sobre os modos do aplicativo e os níveis de acesso da API de Marketing, consulte Nova estrutura para o acesso da API de Marketing e API de Marketing, Acesso e autenticação.

Informações e mensuração de anúncios

  • cost_per_store_visit e store_visits foram renomeados para a API de Informações como cost_per_store_visit_actions e store_visit_actions. Isso afeta:

    • GET {adaccount-id}/insights,

    • GET {campaign-id}/insights,

    • GET {adset-id}/insights,

    • GET {ad-id}/insights,

    • POST {adaccount-id}/insights,

    • POST {campaign-id}/insights,

    • POST {adset-id}/insights e

    • POST {ad-id}/insights.

    Para ver informações sobre as métricas recém-nomeadas, veja Visitas ao estabelecimento, Mensuração. Observe que a API de Visitas ao Estabelecimento e a documentação relacionada estão disponíveis de forma limitada. Fale com o seu representante do Facebook para obter acesso.

API do Gerenciador de Negócios

Na v3.1, apresentamos um novo conceito de permissões baseadas em tarefa para substituir a atual permissão baseada em função. Isso afeta o acesso a contas de anúncios gerenciadas pela API do Gerenciador de Negócios e Páginas. O acesso baseado em função às contas de anúncios e Páginas ainda está disponível, mas se tornará obsoleto no futuro. Isso afeta as seguintes funções e oferece as tarefas equivalentes para as contas de anúncios:

Função Tarefas Descrição

ADMIN

['MANAGE', 'ADVERTISE', 'ANALYZE']

Gerencie todos os aspectos das campanhas de anúncios, relatórios, cobrança e permissões da conta de anúncios.

GENERAL_USER

['ADVERTISE', 'ANALYZE']

Crie anúncios usando a forma de pagamento associada à conta de anúncios. Gere relatórios.

GENERAL_USER

['ANALYZE']

Gere relatórios.

Isso substitui as seguintes funções na API do Gerenciador de Negócios com estas tarefas:

Função Tarefas

MANAGER

['MANAGE', 'CREATE_CONTENT', 'MODERATE', 'ADVERTISE', 'ANALYZE']

CONTENT_CREATOR

['CREATE_CONTENT', 'MODERATE', 'ADVERTISE', 'ANALYZE']

MODERATOR

['MODERATE', 'ADVERTISE', 'ANALYZE']

ADVERTISER

['ADVERTISE', 'ANALYZE']

INSIGHTS_ANALYST

['ANALYZE']

Para o gerenciamento do Pixel do Facebook, isso afeta estas funções e introduz novas tarefas:

Função Tarefas

PIXEL_EDITOR

['EDIT', 'ANALYZE']

PIXEL_ANALYST

['ANALYZE']

Como parte desta alteração, os seguintes campos da API de Gerenciamento de Negócios se tornarão obsoletos e serão substituídos pelos seguintes:

Área Obsoleto Novo campo

GET {adaccount-id}/users

permissions, role

tasks

POST {adaccount-id}/users

role, uidRoles, emailRoles

tasks

GET {user-id}/adaccounts

permissions, role

tasks

GET {user-id}/assigned_ad_accounts

role, permitted_role

tasks, permitted_tasks

GET {user-id}/assigned_pages

role, permitted_role

tasks, permitted_tasks

GET {adaccount-id}/assigned_users

role, permitted_role

tasks, permitted_tasks

POST {adaccount-id}/assigned_users

role

tasks

GET {page-id}/assigned_users

role, permitted_role

tasks, permitted_tasks

POST {page-id}/assigned_users

role

tasks

GET {fb-pixel-id}/assigned_users

role, permitted_role

tasks, permitted_tasks

GET {adaccount-id}/userpermissions

role

tasks

POST {adaccount-id}/userpermissions

role

tasks

GET {page-id}/userpermissions

role

tasks

POST {page-id}/userpermissions

role

tasks

GET {business-id}/client_ad_accounts

permitted_role

permitted_tasks

POST {business-id}/client_ad_accounts

permitted_role

permitted_tasks

GET {business-id}/client_pages

permitted_role

permitted_tasks

POST {business-id}/client_pages

permitted_role

permitted_tasks

GET {business-id}/client_pixels

permitted_role

permitted_tasks

GET {adaccount-id}/agencies

permitted_role

permitted_tasks

POST {adaccount-id}/agencies

permitted_role

permitted_tasks

GET {page-id}/agencies

permitted_role

permitted_tasks

POST {page-id}/agencies

permitted_role

permitted_tasks

GET {business-id}/pending_client_pages

permitted_role

permitted_tasks

GET {business-id}/pending_client_ad_accounts

permitted_role

permitted_tasks

Este novo design também afeta a API de Páginas. Consulte Graph API 3.1, API de Páginas, Alterações disruptivas. Para obter a documentação da API do Gerenciador de Negócios, consulte:

Plataforma do Messenger

Para aplicativos criados antes do dia 26 de julho de 2018, essas alterações entrarão em vigor no dia 8 de janeiro de 2019. Para aplicativos criados depois de 26 de julho de 2018, essas alterações entram em vigor imediatamente.

A API de Perfil do Usuário agora somente retorna os campos first_name, last_name e profile_pic por padrão. Os Campos adicionais agora exigem a análise do produto pela guia Plataforma do Messenger do Painel de Aplicativos.

Os campos last_ad_referral e is_payment_enabled foram descontinuados e serão removidos da API no dia 30 de outubro de 2018.

API de Amigos em Comum

Estas alterações se aplicam a versões posteriores à v3.1 e serão aplicadas a todas as versões no dia 24 de outubro de 2018.

A API de Amigos em Comum foi descontinuada no dia 4 de abril de 2018, e os pontos de extremidade descritos abaixo começaram a retornar conjuntos de dados vazios. Os pontos de extremidade agora estão totalmente obsoletos e retornarão um erro.

  • /user-context/all_mutual_friends
  • /user-context/mutual_friends
  • /user-context/three_degree_mutual_friends

API de Páginas

Permissões

As seguintes alterações se aplicam à v3.1 e a versões posteriores, e serão aplicadas a todas as versões no dia 1º de fevereiro de 2019.

A permissão pages_manage_cta agora exige a Análise do Aplicativo para todas as solicitações POST e DELETE. Os aplicativos criados antes do dia 26 de julho de 2018 podem continuar usando essa permissão, mas devem enviá-la para análise antes do dia 1º de fevereiro de 2019 para continuar usando o pages_manage_cta.

Funções administrativas

As seguintes alterações aplicam-se à versão v3.1+.

As Funções administrativas estão sendo descontinuadas e serão substituídas pelas tarefas da Página. Em vez de conceder a um usuário uma função em uma Página, você agora deve conceder ao usuário suas tarefas equivalentes.

FunçãoTarefas equivalentes

Admin

ADVERTISE, ANALYZE, CREATE_CONTENT, MANAGE, MODERATE

Advertiser

ADVERTISE, ANALYZE

Analyst

ANALYZE

Editor

ADVERTISE, ANALYZE, CREATE_CONTENT, MODERATE

Moderator

ADVERTISE, ANALYZE, MODERATE

Até que as permissões baseadas em funções sejam totalmente substituídas por permissões baseadas em tarefas, ao conceder tarefas por meio de /page/roles, você deve conceder todas as tarefas equivalentes de uma função ou a operação POST falhará.

Para comportar essas alterações, os campos perms e role foram descontinuados e substituídos por um novo campo tasks. Isso afeta as seguintes bordas:

  • /me/accounts
  • /page/roles
  • /user/accounts

Consulte o log de alterações da API de Marketing para ver como essas alterações afetam a API de Marketing e a API do Gerenciador de Negócios.

Webhooks

Estas alterações se aplicam a versões posteriores à v3.1 e serão aplicadas a todas as versões no dia 24 de outubro de 2018.

Os seguintes campos do Webhook do Usuário foram descontinuados:

  • pic_big_with_logo
  • pic_small_with_logo
  • pic_square_with_logo
  • pic_with_logo

Os seguintes campos do Webhook do usuário agora usam URLs HTTPS em vez de HTTP.

  • pic
  • pic_big
  • pic_small
  • pic_square
  • picture

Além disso, os URLs desses campos expirarão — isso afeta imediatamente todas as APIs.