Reglas de anuncios basadas en activación

Supervisar el estado de los anuncios en tiempo real. Una regla basada en el activador se evalúa inmediatamente después de que se cambian los metadatos o los datos de las estadísticas de los objetos publicitarios correspondientes. La latencia relacionada a los cambios de los metadatos suele ser de unos pocos segundos, y la de las estadísticas, de unos pocos minutos (p99 actual es de unos 7,5 minutos).

En relación con las reglas basadas en activación, no se admite schedule_spec, ya que siempre se verifican en tiempo real.

Las reglas basadas en activación solo están disponibles en la API en este momento. No es posible acceder a estas reglas mediante el administrador de anuncios.

Objeto "Trigger"

El objeto trigger define cómo se evalúa una regla. Todos los tipos de activadores requieren un field disparador, excepto METADATA_CREATION. Una regla basada en activación solo comprueba su estado cuando se cambia este campo.

Una regla basada en activación solo puede tener un trigger. Si tienes condiciones o restricciones que se aplican a múltiples métricas, puedes agregar las restantes como filters.

El campo filters se usa de la misma manera que en Reglas basadas en el calendario. Una regla basada en activación solo pasa su evaluación cuando trigger y todos los filters satisfacen las comparaciones. Por ese motivo, un activador y un filtro son intercambiables si el cambio de un campo lleva al cambio de otro. Por ejemplo, si deseas que una regla se active cuando cost_per_mobile_app_install > X Y spent > Y, puedes usar cost_per_mobile_app_install o spent como disparador, y el otro como uno de los filtros, porque esos dos campos dependen entre sí.

El objeto trigger se encuentra en evaluation_spec, y presenta la siguiente estructura:

Teclas del objeto "Trigger"	Descripción
`type`	El tipo de regla basada en activación. Las opciones actuales admitidas son las siguientes: `METADATA_CREATION`: se activa cuando se crea un objeto publicitario `METADATA_UPDATE`: se activa cuando se actualizan los metadatos `field` `STATS_CHANGE`: se activa cuando las estadísticas `field` cambian a los fines de la comparación `STATS_MILESTONE`: Se activa cuando las estadísticas `field` alcanzan un múltiplo de `value`
`field`	El campo subyacente. No se encuentra en uso en relación con `METADATA_CREATION`
`value`	El valor del filtro subyacente. No se encuentra en uso en relación con `METADATA_CREATION`. Opcional para `METADATA_UPDATE`.
`operator`	El operador de filtro subyacente. No se encuentra en uso en relación con `METADATA_CREATION`. Opcional para `METADATA_UPDATE`.

Puedes crear reglas de anuncios que se activan de cuatro maneras diferentes:

Metadatos relacionados: METADATA_CREATION o METADATA_UPDATE
Insights relacionadas: STATS_MILESTONE o STATS_CHANGE

Reglas de activación relacionadas con los metadatos

Regla de creación de metadatos

Esta regla se usa para supervisar cuando se crea un objeto publicitario. Solo se requiere type dentro de las especificaciones trigger. En lo que respecta a los filtros, especifica el entity_type que deseas supervisar.

Aquí se proporciona un ejemplo de una regla de creación de metadatos para supervisar la creación de todos los anuncios vinculados a un objetivo determinado. Cada vez que se crea un nuevo anuncio en relación con una campaña publicitaria del objetivo APP_INSTALLS, se envía un ping.

curl -i -X POST \
-F 'name=Metadata Creation Example 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "METADATA_CREATION",
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "AD",
         "operator": "EQUAL",
       },
       {
         "field": "campaign.objective",
         "value": ["APP_INSTALLS"],
         "operator": "IN",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PING_ENDPOINT"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library"

Regla de actualización de metadatos

Esta regla se usa para supervisar cuando se cambian los metadatos de un objeto publicitario. Consulta la lista de campos de metadatos admitidos. Dentro de la especificación trigger, es obligatorio el valor field, mientras que value y operator son opcionales.

Si te interesa cambiar un campo, no importa cuál sea su valor; solo necesitas especificar la opción field. Aquí se proporciona un ejemplo en el que se te envía una notificación de Facebook cada vez que cambia el presupuesto diario de un conjunto de anuncios.

curl -i -X POST \
-F 'name=Metadata Update Example 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "METADATA_UPDATE",
        "field": "daily_budget",
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "ADSET",
         "operator": "EQUAL",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "NOTIFICATION"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library"

Si solo te interesa un subconjunto de los eventos, puedes proporcionar opciones operator y value para mejorar la condición trigger. Aquí se muestra un ejemplo en el que se envía una notificación cuando el presupuesto diario de un conjunto de anuncios cambia y supera los 1.000:

curl -i -X POST \
-F 'name=Metadata Update Example 2' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "METADATA_UPDATE",
        "field": "daily_budget",
        "value": 1000,
        "operator": "GREATER_THAN"
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "ADSET",
         "operator": "EQUAL",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PING_ENDPOINT"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library"

Reglas de activación relacionadas con las estadísticas

Regla del hito de las estadísticas

Con STATS_MILESTONE como type, evaluation_spec se activa cuando field alcanza un múltiplo de value en relación con los objetos que coinciden con las condiciones de la matriz filters.

Para este tipo específico de regla, el disparador operator debe ser EQUAL, y el filtro time_preset debe tener un valor de LIFETIME.

Hay un conjunto más restrictivo de campos admitidos. Los campos no incluidos a continuación no se admiten como activador field, pero aún puede usarse como filtro en la lista de filters. Además, hay valores mínimos requeridos para el value del activador en función del field.

Valores de campo de activación admitidos	Valor mínimo
`impressions`	1.000
`unique_impressions`	1.000
`reach`	1.000
`clicks`	10
`unique_clicks`	10
`spent`	1.000 (centavos)
`results`	5
`app_custom_event`	1
`app_custom_event_fb_mobile_achievement_unlocked`	1
`app_custom_event_fb_mobile_activate_app`	1
`app_custom_event_fb_mobile_add_payment_info`	1
`app_custom_event_fb_mobile_add_to_cart`	1
`app_custom_event_fb_mobile_add_to_wishlist`	1
`app_custom_event_fb_mobile_complete_registration`	1
`app_custom_event_fb_mobile_content_view`	1
`app_custom_event_fb_mobile_initiated_checkout`	1
`app_custom_event_fb_mobile_level_achieved`	1
`app_custom_event_fb_mobile_purchase`	1
`app_custom_event_fb_mobile_rate`	1
`app_custom_event_fb_mobile_search`	1
`app_custom_event_fb_mobile_spent_credits`	1
`app_custom_event_fb_mobile_tutorial_completion`	1
`app_custom_event_other`	1
`leadgen`	1
`like`	1
`link_click`	1
`mobile_app_install`	1
`offsite_conversion`	1
`offsite_conversion_add_to_cart`	1
`offsite_conversion_checkout`	1
`offsite_conversion_fb_pixel_add_payment_info`	1
`offsite_conversion_fb_pixel_add_to_cart`	1
`offsite_conversion_fb_pixel_add_to_wishlist`	1
`offsite_conversion_fb_pixel_complete_registration`	1
`offsite_conversion_fb_pixel_initiate_checkout`	1
`offsite_conversion_fb_pixel_lead`	1
`offsite_conversion_fb_pixel_other`	1
`offsite_conversion_fb_pixel_purchase`	1
`offsite_conversion_fb_pixel_search`	1
`offsite_conversion_fb_pixel_view_content`	1
`offsite_engagement`	1
`post`	1
`post_comment`	1
`post_engagement`	1
`post_like`	1
`post_reaction`	1
`view_content`	1
`video_play`	1
`video_view`	1
`vote`	1

Aquí hay un ejemplo de una regla de hito de las estadísticas, que envía un ping cada vez que alguien comenta tu publicación:

curl \
-F 'name=Rule 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "STATS_MILESTONE",
        "field": "post_comment",
        "value": 1,
        "operator": "EQUAL"
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "CAMPAIGN",
         "operator": "EQUAL",
       },
       {
         "field": "time_preset",
         "value": "LIFETIME",
         "operator": "EQUAL",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PING_ENDPOINT"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

Regla de cambio de estadísticas

Si se usa STATS_CHANGE como type de disparador, se activa execution_spec cuando la lógica AND del activador y todos los filtros se evalúan al pasar de false a true en un determinado time_preset.

Si las evaluaciones posteriores de la lógica AND también son ciertas, execution_specno se ejecuta. Sin embargo, si la evaluación de la lógica AND cambia de true a false, execution_spec se ejecuta cuando vuelve a true.

Para este tipo específico de regla, el activador operator puede ser GREATER_THAN, LESS_THAN, IN_RANGE o NOT_IN_RANGE.

Aquí hay un ejemplo de una regla de cambio de las estadísticas. Si un anuncio llega a más de 5.000 personas y supera los 10 USD por compra en los últimos 3 días, páusalo.

curl \
-F 'name=Rule 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "STATS_CHANGE",
        "field": "cost_per_purchase_fb",
        "value": 1000,
        "operator": "GREATER_THAN",
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "AD",
         "operator": "EQUAL"
       },
       {
         "field": "time_preset",
         "value": "LAST_3_DAYS",
         "operator": "EQUAL"
       },
       {
         "field": "reach",
         "value": 5000,
         "operator": "GREATER_THAN"
       }
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PAUSE"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

Reglas de cambio de las estadísticas de entrega (beta)

Cuando se usa DELIVERY_INSIGHTS_CHANGE como type de activador, la regla se activa cuando todos los filtros definidos en evaluation_spec se evalúan para comprobar que sean true, y el activador definido en evaluation_spec solo cambia para pasar de false a true.

En las evaluaciones posteriores, si los filtros y el activador continúan siendo evaluados para comprobar que sean true, la regla no se vuelve a activar.

Configuración de webhooks

Para usar el tipo de ejecución PING_ENDPOINT, necesitas configurar una suscripción relacionada con tu aplicación a través de webhooks. Configura una URL de devolución de llamadas, una app de Facebook y webhooks para recibir notificaciones de la API de reglas:

Paso 1: Configurar una URL de devolución de llamada

Consulta la Guía de webhooks y crea una URL de devolución de llamada que pueda manejar el desafío y la respuesta durante la verificación. La URL de devolución de llamada maneja la estructura de datos que se envía cuando se activa una regla:

{
  object: 'application',
  entry: [{
    id: '<APPLICATION_ID>',
    time: 1468938744,
    changes: [{
      field: 'ads_rules_engine',
      value: {
        'rule_id': 1234,
        'object_id': 5678,
        'object_type': 'ADSET',
        'trigger_type': 'STATS_CHANGE',
        'trigger_field': 'COST_PER_LINK_CLICK',
        'current_value': '15.8',
      }
    }],
  }],
}

El campo current_value es una cadena con codificación de JSON. Su valor puede ser una cadena entre comillas dobles, un número o una matriz que comienza con [ (corchete izquierdo) y termina con ] (corchete derecho).

Paso 2: Agregar el webhook `ads_rules_engine` a tu app

Una vez que la URL de devolución de llamada maneja el desafío y la respuesta de la verificación, regístrala en tu app cuando se activa una regla:

Crea una nueva app de Facebook o usa una existente.
Agrega el producto de webhook.

Crea una nueva suscripción para una app y selecciona ad_rules_engine.

Alternativamente, esto se puede hacer mediante la API Graph, utilizando un token de acceso a la app y no un token de acceso del usuario:

curl \
-F "object=application" \
-F "callback_url=<CALLBACK_URL>" \
-F "fields=ads_rules_engine" \
-F "verify_token=<VERIFY_TOKEN>" \
-F "access_token=<APP_ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<APP_ID>/subscriptions"

Consulta la referencia de suscripciones para obtener más detalles sobre APP_ID/subscriptions.