Controle de versões

A versão atual da API de Marketing é v21.0.

A plataforma do Facebook tem um modelo de controle de versões principal e um ampliado. Com o controle de versões da API de Marketing, todas as alterações importantes serão lançadas em uma nova versão. As diversas versões das APIs de Marketing ou dos SDKs podem coexistir com funcionalidades diferentes em cada versão.

Os desenvolvedores devem saber com antecedência quando uma API de Marketing ou um SDK sofrerá alterações. Embora haja uma janela de 90 dias para adotar as alterações, a escolha de como e quando passar para a nova versão é sua.

Cronograma de versões

Quando uma nova versão da API de Marketing é lançada, mantemos a compatibilidade com a versão anterior por pelo menos 90 dias. Isso significa que você terá esse período de carência para atualizar sua versão. Durante esses 90 dias, você poderá fazer chamadas para a versão atual e a obsoleta. Depois desse prazo, será necessário atualizar para a nova versão. Ao término do período de carência, a versão obsoleta deixará de funcionar. Depois que uma versão ficar indisponível, as chamadas feitas para ela poderão falhar ou ser atualizadas para a próxima versão disponível.

Por exemplo, a API de Marketing v17.0 foi lançada em 23 de maio de 2023, e a v16.0 expirou em 6 de fevereiro de 2024, fornecendo ao menos 90 dias para fazer a atualização para a nova versão.

Veja um exemplo de cronograma. Talvez não lancemos uma nova versão no final do período de carência de 90 dias da versão anterior. No exemplo, a v16.0 fica obsoleta um pouco antes do lançamento da v18.0:

No caso dos SDKs, uma versão está sempre disponível no estado atual como um pacote para download. Depois do fim de vida útil, o SDK continuará se baseando nas APIs de Marketing ou em métodos que não funcionam mais; por isso, presuma que ele não funcionará mais no fim de vida útil.

Como fazer solicitações de controle de versões

Todos os pontos de extremidade da API de Marketing estão disponíveis por meio de um caminho com controle de versões. Pré-anexe o identificador de versão no início do caminho da solicitação. Por exemplo:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"

Isso funciona para todas as versões, neste formato geral:

https://graph.facebook.com/v{n}/{request-path}

Nele, n é a versão necessária. Confira a lista completa das versões disponíveis no Registro de alterações. Todas as referências da API de Marketing fornecem informações por versão.

Migrações

As migrações são somente para casos especiais, nos quais as alterações que precisam ser feitas não podem entrar no controle de versões. Normalmente, isso ocorrerá se o modelo de dados básicos tiver sido alterado. Migrações aplicam-se a todas as versões.

As migrações que ainda estão em andamento aparecem listadas na nossa página de migrações. As migrações têm uma janela de pelo menos 90 dias, durante a qual você deverá migrar o app. Uma vez iniciada a janela, o comportamento pós-migração se tornará o padrão para os novos apps. Depois, quando a janela de migração tiver sido concluída, o comportamento pré-migração não estará mais disponível.

Como gerenciar migrações por meio da Graph API

As migrações podem ser gerenciadas por meio do campo de migrações do nó /app:

É possível fazer uma chamada de atualização na borda para ativar e desativar migrações.

Como gerenciar migrações por meio do Painel de Apps

Você pode ativar e desativar as migrações disponíveis no Painel de Apps, em Configurações > Migrações. Vale ressaltar que a lista de migrações pode não ser a mesma da imagem abaixo, já que as migrações disponíveis são específicas para cada app, em momentos diferentes. Caso você veja uma migração Use Graph API v2.0 by default, ela será para Graph API somente, não para a API de Marketing.

Ativação temporária de migrações no lado do cliente

Em vez de ativar a migração pelo Painel de Apps ou pela API de Marketing, é possível adicionar uma sinalização especial definindo a migração para chamadas da API de Marketing. A sinalização é chamada de migrations_override e exige que você defina um blob JSON que descreva as migrações a serem ativadas ou desativadas. Por exemplo, se fosse fazer uma chamada bruta, você poderia passar:

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

Com isso, é possível fazer chamadas à nova API de Marketing por meio de atualizações do cliente, em vez de fazer todos atualizarem para fazer chamadas a ela ao mesmo tempo. Isso também é útil para depuração.

Você pode encontrar os nomes dessas migrações no nó /app mencionado acima.

Atualização automática da versão

Devido à rápida rotatividade das versões da API de Marketing, que mudam aproximadamente a cada quatro meses, estamos simplificando o processo de atualização. A partir de maio de 2024, habilitaremos o recurso de atualização automática da versão para os pontos de extremidade da API de Marketing que não são afetados entre as versões. Isso significa que, entre uma versão prestes a ficar obsoleta e a próxima disponível, se nenhum ponto de extremidade for afetado, a plataforma atualizará a chamada para a versão a ser lançada, em vez de gerar uma falha na solicitação diretamente. Essa mudança foi pensada para garantir uma experiência mais tranquila e eficiente com a API.

Por exemplo, no dia 14 de maio de 2024, a v17.0 ficará obsoleta. De acordo com o registro de alterações da v18.0, os seguintes pontos de extremidade serão afetados:

• POST /act_{ad-account-id}/reachfrequencypredictions
• GET /act_{ad-account-id}/reachestimate
• GET /act_{ad-account-id}/delivery_estimate
• POST /act_{ad-account-id}/adsets
• POST /{adset-id}
• POST /act_{ad-account-id}/saved_audiences
• POST /{saved-audience-id}
• POST /act_{ad-account-id}/credit_cards

Caso seu app faça uma chamada POST /{adset-id} com a v17.0 depois que ela ficar obsoleta no dia 14 de maio de 2024, essa solicitação da API falhará, já que a atualização automática não se aplica aos pontos de extremidade afetados pela próxima versão disponível (v18.0).

Se o app fizer uma chamada GET /{ad-account-id}/insights com a v17.0 depois que ela ficar obsoleta, a plataforma atualizará sua solicitação para a próxima versão disponível (v18.0).

Observação: caso seu app já esteja fazendo chamadas com versões posteriores à v17.0, nada mudará na data em que a versão ficar obsoleta.

Para verificar os pontos de extremidade afetados em cada versão, consulte o registro de alterações da API de Marketing.

Perguntas frequentes

Cronograma de versões

Como fazer solicitações de controle de versões

https://graph.facebook.com/v{n}/{request-path}

Atualização automática da versão

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''