Marketing API

Collaborative Ads App Events API

Collaborative Ads allows producers such as consumer-packaged goods advertisers to run ad campaigns to drive people to merchant platforms such as online retailers' websites or apps and can measure, retarget, and optimize towards people who have interacted with the producers' products on the merchant platforms. Access to the Collaborative Ads features is provided on a limited basis only. Please contact your Facebook Representative.

App Events

In order to enable Collaborative Ads features via API, merchants needs to send custom events with the following data

Name Description Example

event

Identifies the type of event being sent via app events API. This should be set to CUSTOM_APP_EVENTS for Collaborative Ads

CUSTOM_APP_EVENTS

advertiser_id

Apple's Advertising Identifier (IDFA) or Google's Android’s advertising ID. See how Facebook fetches this on iOS or on Android.

1111-1111-1111-1111

advertiser_tracking_enabled

You can enable ad tracking on iOS 6+, and that choice is stored on the phone. You should fetch that and return it to Facebook so we know not to use the data for optimization. We will, however, use the data to report on a conversion. See here for an example of how Facebook fetches that variable. For non-iOS 6+ devices, this query parameter can be defaulted to 1.

0 for disabled; 1 for enabled

application_tracking_enabled

You can enable or disable ad tracking on an app level. SDKs should enable app developers to add a opt-out setting into an app. Use this field to specify the user's choice.

0 for disabled or 1 for enabled

custom_events

Array of events you want to report to Facebook. For Collaborative Ads, see the below list of predefined events and applicable parameters of each of them below.

[{\"_eventName\":\"fb_mobile_purchase\", \"fb_content\":\"[{\"id\": \"1234\", \"quantity\": 2}, {\"id\": \"5678\", \"quantity\": 1}]\", \"fb_content_type\":\"product\"}]

Required Standard Events for Collaborative Ads

The merchant platform needs to provide the following standard events.

Event Name Event Description Required Parameters Optional Parameters

fb_mobile_content_view

When a product page is viewed.

A person lands on a product details page.

fb_content or fb_content_id, content_type

fb_currency and _valueToSum

fb_mobile_add_to_cart

When a product is added to the shopping cart.

A person clicks Add to Cart.

fb_content, content_type, fb_currency, and _valueToSum

fb_mobile_purchase

When a purchase is made or checkout flow is completed.

A person has finished the purchase or checkout flow and lands on thank you or confirmation page.

fb_content, content_type, fb_currency, and _valueToSum

Parameters

Parameter Description Value Type

fb_content

A string of an array of JSON objects that contains the International Article Number (EAN) when applicable, or other product or content identifier(s) associated with the event and quantities of the products.


Required: id and quantity.


Example: "[{\"id\": \"ABC123\", \"quantity\": 2}, {\"id\": \"XYZ789\", \"quantity\": 2}]"


Note: This parameter is required for fb_mobile_add_to_cart and fb_mobile_purchase event and is optional for fb_mobile_content_view event if fb_content_id is provided.

string

fb_content_id

Product IDs associated with the event, such as SKUs.


Example: ['ABC123', 'XYZ789']

array of strings

fb_content_type

Either "product" or "product_group" based on the content_ids or contents being passed.

  • If the product IDs being passed in fb_content or fb_content_id parameter are IDs of products, then the value should be "product".
  • If product group IDs are being passed, then the value should be "product_group".

string

fb_currency

Currency for the value specified in ISO 4217 currency code.


Example: "USD", "GBP", "JPY"

string

_valueToSum

Value of a user performing this event to the business.

  • For fb_mobile_content_view, value of an item.
  • For fb_mobile_add_to_cart, the value of new items added to cart at once. It's not the current total basket value.
  • For fb_mobile_purchase, the total basket value, including other fees, such as shipping fee and tax.

Example: 21.5

integer or float

Examples

Mobile Content View Event

curl \
  -F "event=CUSTOM_APP_EVENTS" \
  -F "advertiser_id=1111-1111-1111-1111" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  -F "custom_events=[{\"_eventName\":\"fb_mobile_content_view\",
                      \"fb_content\":\"[{\"id\": \"1234\", \"quantity\": 1}]\",
                      \"fb_content_type\":\"product\",
                      \"_valueToSum\": 25,
                      \"fb_currency\": \"USD\"
                   	}]" \
  "https://graph.facebook.com/API_VERSION/APP_ID/activities"

or, with minimal parameters

curl \
  -F "event=CUSTOM_APP_EVENTS" \
  -F "advertiser_id=1111-1111-1111-1111" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  -F "custom_events=[{\"_eventName\":\"fb_mobile_content_view\",
                      \"fb_content_id\": \"1234\",
                      \"fb_content_type\":\"product\",
                   	}]" \
  "https://graph.facebook.com/API_VERSION/APP_ID/activities"

Note: The minimal parameter setup is valid for fb_mobile_content_view only and not valid for fb_mobile_add_to_cart and fb_mobile_purchase.

Mobile Add To Cart Event

curl \
  -F "event=CUSTOM_APP_EVENTS" \
  -F "advertiser_id=1111-1111-1111-1111" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  -F "custom_events=[{\"_eventName\":\"fb_mobile_add_to_cart\",
                      \"fb_content\":\"[{\"id\": \"1234\", \"quantity\": 2}]\",
                      \"fb_content_type\":\"product\",
                      \"_valueToSum\": 50,
                      \"fb_currency\": \"USD\"
                    }]" \
  "https://graph.facebook.com/API_VERSION/APP_ID/activities"

Mobile Purchase Event

curl \
  -F "event=CUSTOM_APP_EVENTS" \
  -F "advertiser_id=1111-1111-1111-1111" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  -F "custom_events=[{\"_eventName\":\"fb_mobile_purchase\",
                      \"fb_content\":\"[{\"id\": \"1234\", \"quantity\": 2}, {\"id\": \"5678\", \"quantity\": 1}]\",
                      \"fb_content_type\":\"product\",
                      \"_valueToSum\": 100,
                      \"fb_currency\": \"USD\"
                    }]" \
  "https://graph.facebook.com/API_VERSION/APP_ID/activities"