Marketing API Version

Catalog and Signals Quality

We offer three options to get feedback about the quality and performance of your different dynamic ads assets:

Feedback on Catalog and Feed Quality

Check if your products have any quality issues that affect the accuracy, freshness or completeness of the data in a catalog. You can check this at the catalog level or at a feed level.

In this example, query the Quality API. See Quality API reference for details.

Via the API

Get information about quality issues affecting your products at the catalog level:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CATALOG_ID> . '/quality_issues',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<CATALOG_ID>/quality_issues

Or the feed level:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <FEED_ID> . '/quality_issues',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<FEED_ID>/quality_issues

These calls return an array of quality issues affecting products in a catalog or feed, including some samples from your feed to help debug the issues. Example response:

{
  "data": [
    {
      "description": "Accurate product descriptions help people better understand what the product is or does. They also allow us to advertise your products more efficiently.",
      "issue_type": "qualified_description",
      "property_names": [
        "description",
      ],
      "summary": "Content is too short",
      "count": 121,
      "samples": [
        {
          "id": "1111111111111111",
          "description": "Phone 19 inch",
          "retailer_id": "10"
        },
        {
          "id": "2222222222222222",
          "description": "Phone Tab A",
          "retailer_id": "100"
        },
        {
          "id": "333333333333333",
          "description": "Tablet X White",
          "retailer_id": "101"
        },
        {
          "id": "4444444444444444",
          "description": "Tablet Z Black",
          "retailer_id": "104"
        },
      ]
    },
  ],
}

The fields returned for each quality issue are:

Issue typesDescription

issue_type

The type of the issue (listed in the table below).

property_names

The names of the item properties affected by the issue.

summary

A brief explanation.

description

A longer explanation about the issue and why it is important to solve it.

count

The number of product that do not meet the quality standard.

samples

A list of example of products that do not meet the quality standards.

Below is the list of possible quality issues returned.

Issue typesDescription

qualified_brand

Check if the brand field is included in your feed. Including brand information helps us recommend the right products to your customers.

qualified_category

Check if the category field is included in your feed. Including category information helps us recommend the right products to your customers.

qualified_description

Check if the description field is included in your feed and provides enough information about the product (we expect the description text to be at least 40 characters long).

qualified_image

If the image field matches our quality requirements. The minimum recommended size is 600 x 600 pixels. Including high-quality photos ensures we can display the best image to every customer, whatever device or network they use.

duplicate_names

Check if there are products with the same names in your feed. Unique product titles allow us to advertise your products more effectively and ensure your ad is clear. If these are variants of the same product, use the same item_group_id for all of them (see item_group_id in product feed fields).

duplicate_descriptions

Check if there are products with the same descriptions in your feed. Unique product descriptions help people better understand what the product is or does. They also allow us to advertise your products more effectively. If these are variants of the same product, use the same item_group_id for all of them.

Check Products Meeting Quality

Query the total number of products, together with the number of products that meet our quality requirements with product_count and qualified_product_count at the feed and catalog levels. For example:

use FacebookAds\Object\ProductCatalog;

$product_catalog = new ProductCatalog(<CATALOG_ID>);
$fields = array('product_count', 'qualified_product_count');
$product_catalog->read($fields);
curl -G \
  -d 'fields=product_count,qualified_product_count' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<CATALOG_ID>

Use this to keep track of the number of products meeting quality requirements. Find both fields in Product Feed, Reference and Product Catalog, Reference.

FieldDescription

qualified_product_count

Number of items that don't have any quality issues.

product_count

The total number of products.

Feedback on Pixel and App Events for Catalogs

To identify issues with your pixel or app installation, you can check aggregate statistics about matched and unmatched events received from different pixels, apps and devices.

Query Event API to get statistics about events originating from event sources linked to your catalog. See Events API, Reference for details.

Event statistics

You can get this information at the catalog level:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CATALOG_ID> . '/event_stats',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<CATALOG_ID>/event_stats

This returns an array of elements, one per event type, source and date within the last month:

{
  "data": [
    {
      "date_start": "2017-03-16",
      "date_stop": "2017-03-16",
      "event": "AddToCart",
      "event_source": {
        "id": "<PIXEL_ID>",
        "source_type": "PIXEL"
      },
      "total_matched_content_ids": 1086,
      "total_content_ids_matched_other_catalogs": 10024,
      "total_unmatched_content_ids": 13024,
      "unique_matched_content_ids": 285,
      "unique_content_ids_matched_other_catalogs": 102,
      "unique_unmatched_content_ids": 2132
    },
    {
      "date_start": "2017-03-16",
      "date_stop": "2017-03-16",
      "event": "ViewContent",
      "event_source": {
        "id": "<APP_ID>",
        "source_type": "APP"
      },
      "total_matched_content_ids": 1007,
      "total_content_ids_matched_other_catalogs": 504,
      "total_unmatched_content_ids": 20206,
      "unique_matched_content_ids": 507,
      "unique_content_ids_matched_other_catalogs": 402,
      "unique_unmatched_content_ids": 8037
    },
    ...
    ]
}

The fields returned for each event type, source and date are:

CountDescription

total_matched_content_ids

The total number of content ids from received events that matched to an item in the catalog. This count is not de-duplicated across content ids.

total_content_ids_matched_other_catalogs

The total number of content ids from received events that matched to an item in another catalog associated to the given pixel or app. This count is not de-duplicated across content ids.

total_unmatched_content_ids

The total number of content ids from received events received that didn't match an item in the catalog. This count is not de-duplicated across content ids.

unique_matched_content_ids

The number of unique content ids from received events that matched to an item in the catalog.

unique_content_ids_matched_other_catalogs

The number of unique content ids from received events that matched to an item in another catalog associated to the given pixel or app that fired the event.

unique_unmatched_content_ids

The number of unique content ids from received events that didn't match an item in the catalog.

Device Type Breakdowns

Break down results by passing device_type:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CATALOG_ID> . '/event_stats',
  RequestInterface::METHOD_GET,
  array(
    'breakdowns' => array('device_type'),
  ))->getContent();
curl -G \
  -d 'breakdowns=["device_type"]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<CATALOG_ID>/event_stats

This returns results grouped by device they occurred on. For example desktop, mobile_iphone, mobile_android_phone, and so on:

{
  "data": [
    {
      "date_start": "2017-03-10",
      "date_stop": "2017-03-10",
      "event": "AddToCart",
      "event_source": {
        "id": "<PIXEL_ID>",
        "source_type": "PIXEL"
      },
      "device_type": "desktop",
      "total_matched_content_ids": 282,
      "total_content_ids_matched_other_catalogs": 524,
      "total_unmatched_content_ids": 4965,
      "unique_matched_content_ids": 102,
      "unique_content_ids_matched_other_catalogs": 402,
      "unique_unmatched_content_ids": 1427
    },
    ...
  ]
}

Feedback on Pixel and App Events

Use checks to allow you to verify if there are any issues with the events sent by your pixel. For example:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <PIXEL_ID> . '/da_checks',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/da_checks

Example response:

{
  "data": [
    {
      "description": "Pixel hasn't sent some or any events for dynamic ads (ex: ViewContent, AddToCart, Purchase) at least once in the last 24 hours.",
      "key": "pixel_missing_dpa_event",
      "result": "failed",
      "title": "Pixel is not sending DPA events"
    },
    {
      "description": "Pixel events might be missing parameters some or all of the time.",
      "key": "pixel_missing_param_in_events",
      "result": "passed",
      "title": "Pixel missing parameter in DPA events"
    },
    {
      "action_uri": "https://www.facebook.com/ads/manage/pixels/?pixel_id=<PIXEL_ID>&m2w=1",
      "description": "The number of pixel events has dropped to less than half of the weekly average.",
      "key": "pixel_decline",
      "result": "passed",
      "title": "Decline in number of pixel events"
    }
  ]
}

You can use the following checks:

CheckDescription

pixel_missing_dpa_event

Checks if there are missing events for this pixel, as defined in Dynamic Ads.

pixel_missing_param_in_events

Checks if there are events with missing mandatory parameters,as defined in Dynamic Ads.

pixel_decline

Checks if there is a decline in the number of events received for that pixel in the last 24 hours.

For details, see Pixel Dynamic Ads Checks, Reference.

Possible values for the result field:

StatusDescription

passed

Your pixel passed this check.

failed

Your pixel didn't pass this check.

unavailable

This check is not available for this pixel right now. Please try again later.

We return all checks by default, but you can specify checks you'd like to run, as follow:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <PIXEL_ID> . '/da_checks',
  RequestInterface::METHOD_GET,
  array(
    'checks' => array(
      'pixel_decline',
      'pixel_missing_dpa_event',
      'pixel_missing_param_in_events',
      ),
  ))->getContent();
curl -G \
  --data-urlencode 'checks=[ 
    "pixel_decline", 
    "pixel_missing_dpa_event", 
    "pixel_missing_param_in_events" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/da_checks

For App Events

You can verify if there are any issues with the events sent by your app:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <APP_ID> . '/da_checks',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<APP_ID>/da_checks

Example response:

{
  "data": [
    {
      "description": "App hasn't sent some or any events for dynamic ads (ex: ViewContent, AddToCart, Purchase)...",
      "key": "app_missing_dpa_event",
      "result": "failed",
      "title": "App is not sending DPA events"
    },
    {
      "description": "App events might be missing parameters some or all of the time.",
      "key": "app_missing_param_in_events",
      "result": "passed",
      "title": "App missing parameter in DPA events"
    }
  ]
}
CheckDescription

app_missing_dpa_event

Checks if there are missing events for the app, as defined in Dynamic Ads.

app_missing_param_in_events

Checks if there are events with missing mandatory parameters, as defined in Dynamic Ads.

For more details, see App DA Checks, Reference.

Possible values returned for result:

StatusDescription

passed

Your app passed this check.

failed

Your app didn't pass this check.

unavailable

This check is not available for this app right now. Please try again later.

You can request values for specific checks. We return all by default, but you can specify which checks you'd like to run by passing them in the request:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <APP_ID> . '/da_checks',
  RequestInterface::METHOD_GET,
  array(
    'checks' => array('app_missing_dpa_event', 'app_missing_param_in_events'),
  ))->getContent();
curl -G \
  -d 'checks=["app_missing_dpa_event","app_missing_param_in_events"]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<APP_ID>/da_checks