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.
In order to enable Collaborative Ads features via API, merchants needs to send custom events with the following data
| Name | Description | Example |
|---|---|---|
| Identifies the type of event being sent via app events API. This should be set to |
|
| Apple's Advertising Identifier (IDFA) or Google's Android’s advertising ID. See how Facebook fetches this on iOS or on Android. |
|
| 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 |
|
| 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. |
|
| 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. |
|
The merchant platform needs to provide the following standard events.
| Event Name | Event Description | Required Parameters | Optional Parameters |
|---|---|---|---|
| When a product page is viewed. A person lands on a product details page. |
|
|
| When a product is added to the shopping cart. A person clicks Add to Cart. |
| |
| 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. |
|
| Parameter | Description | Value Type |
|---|---|---|
| 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 (Product Group ID is not supported) and quantities of the products. Required: Example: Note: This parameter is required for |
|
| Product IDs associated with the event, such as SKUs (Product Group ID is not supported). Example: |
|
| Must be Note: |
|
| Currency for the value specified in ISO 4217 currency code. Example: |
|
| Value of a user performing this event to the business.
Example: |
|
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.
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"
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"