Control de versiones

La versión actual de la API de marketing es la v20.0.

La plataforma de Facebook cuenta con un modelo de control de versiones básico y ampliado. Con el control de versiones de la API de marketing, todos los cambios importantes estarán incluidos en una nueva versión. De este modo, pueden coexistir varias versiones de las API de marketing o los SDK que tengan funcionalidades distintas en cada versión.

Los desarrolladores deben comprender de forma anticipada cuándo cambiará una API de marketing o un SDK. Aunque dispones de un periodo de 90 días para adoptar los cambios, puedes elegir cómo y cuándo migrar a la versión más reciente.

Programaciones de versiones

Cuando se lanza una nueva versión de la API de marketing, se sigue admitiendo la versión anterior de la API de marketing durante al menos 90 días. Tienes un periodo de gracia de al menos 90 días para pasar a la nueva versión. Durante el periodo de gracia de 90 días, puedes llamar tanto a la versión actual como a la versión retirada y dispones de ese periodo de gracia de 90 días para pasar a la nueva versión. Cuando finaliza el periodo de gracia de 90 días, la versión retirada deja de funcionar. Cuando una versión no está disponible, las llamadas que se realicen a ese número de versión pueden generar un error o actualizarse a la siguiente versión disponible.

Por ejemplo, la versión 17.0 de la API de marketing se lanzó el 23 de mayo de 2023 y la versión 16.0 de la API de marketing caducó el 6 de febrero de 2024, lo que proporcionó al menos 90 días para pasar a la nueva versión.

A continuación, se muestra un ejemplo de calendario. Ten en cuenta que no siempre se lanza una nueva versión al final del periodo de gracia de 90 días de la retirada de la versión anterior. En el ejemplo, la versión 16.0 se retiró cierto tiempo antes de que se lanzase la versión 18.0:

Los SDK son paquetes descargables y, por tanto, siempre hay una versión disponible. No obstante, a partir de la fecha de retirada, esta versión dependerá de las API de marketing o de métodos que ya no estarán operativos, por lo que recomendamos partir de la idea de que los SDK obsoletos dejan de ser funcionales.

Realización de solicitudes con versión

Todos los extremos de la API de marketing se encuentran disponibles a través de las rutas con versión. Añade el identificador de la versión al inicio de la ruta de la solicitud. Por ejemplo:

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

Funciona con todas las versiones, con este formato general:

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

Donde n es la versión necesaria. Consulta una lista completa de las versiones disponibles en nuestro registro de cambios. En toda la referencia de la API de marketing se proporciona información por versión.

Migraciones

Las migraciones solo se realizan en situaciones especiales en las que deben aplicarse cambios con independencia del control de versiones. Por lo general, esto ocurre cuando cambia el modelo de datos subyacente. Las migraciones se aplican en todas las versiones.

Las migraciones que todavía están en progreso se indican en nuestra página de migraciones. y el plazo durante el que se deben completar es de 90 días como mínimo. Una vez que comienza este plazo, las nuevas aplicaciones adoptan como comportamiento predeterminado el que determina la migración. Cuando este finaliza, el comportamiento previo a la migración deja de estar disponible.

Administrar las migraciones mediante la API Graph

Las migraciones se pueden administrar mediante el campo “migrations” del nodo /app:

Puedes realizar una llamada de actualización en el perímetro para activar y desactivar las migraciones.

Administrar las migraciones mediante el panel de aplicaciones

Puedes activar y desactivar las migraciones disponibles en el panel de aplicaciones, en Configuración > Migraciones. Ten en cuenta que la lista de migraciones puede variar respecto a la que se muestra en esta imagen, ya que las migraciones disponibles son diferentes para las distintas aplicaciones y van cambiando a lo largo del tiempo. Si ves una migración Use Graph API v2.0 by default, es solo para la API Graph, no para la API de marketing.

Activación temporal de las migraciones en el lado del cliente

En lugar de activar una migración desde el panel de aplicaciones o mediante la API de marketing, puedes añadir a las llamadas a la API de marketing una marca especial que establezca dicha migración. La marca se llama migrations_override y requiere que especifiques un blob JSON que describa qué migraciones quieres activar o desactivar. Por ejemplo, para realizar una llamada sin formato, se pasaría lo siguiente:

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

Así, se podría llamar a la nueva API de marketing mediante las actualizaciones de cliente y ya no sería necesario que todas las personas que van a realizar esta llamada hicieran la actualización al mismo tiempo. También resulta muy útil para realizar tareas de depuración.

Los nombres de estas migraciones se encuentran en el nodo /app mencionado anteriormente.

Actualización automática de la versión

Debido a la rápida rotación de las versiones de la API de marketing cada cuatro meses, aproximadamente, estamos optimizando el proceso de actualización. A partir de mayo de 2024, activaremos la función de actualización automática de la versión para los extremos de la API de marketing que no se vean afectados entre versiones. Esto significa que, si un extremo no se ve afectado entre una versión que se va a retirar y la siguiente versión disponible, la plataforma actualizará la llamada a la siguiente versión disponible en lugar de generar un error de solicitud directamente. Este cambio está diseñado para garantizar una experiencia de la API más fluida y eficiente.

Por ejemplo, la versión 17.0 se retirará el 14 de mayo de 2024. Según el registro de cambios de la versión 18.0, se verán afectados los siguientes extremos:

• 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

Si tu aplicación llama a POST /{adset-id} con la versión 17.0 después de su retirada el 14 de mayo de 2024, se producirá un error en esta solicitud a la API, ya que la actualización automática no se aplica a los extremos afectados por la siguiente versión disponible (versión 18.0).

Si la aplicación llama a GET /{ad-account-id}/insights con la versión 17.0 después de su retirada, la plataforma actualizará la llamada a la siguiente versión disponible (versión 18.0).

Nota: Si la aplicación ya hace llamadas con versiones superiores a la 17.0, no se producirá ningún cambio en la fecha de retirada de la versión.

Para saber qué extremos se ven afectados en cada versión, consulta el registro de cambios de la API de marketing.

Preguntas frecuentes

Programaciones de versiones

Realización de solicitudes con versión

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

Actualización automática de la versión

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