App Events for Collaborative Ads - iOS

Collaborative Ads allows producers, such as consumer-packaged goods advertisers to run ad campaigns to drive people to merchant platforms. Such platforms include online retailer websites or apps and those that 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.

To use Collaborative Ads features, the merchants need to implement the following required standard events with their respective parameters. If you're not familiar with app events and parameters, or you need to set up Facebook SDK for iOS, see Getting Started with App Events for iOS.


Required Standard Events

The merchant platform needs to provide the following standard events.

Event Name Description Required Parameters Optional Parameters

View Content: FBSDKAppEventNameViewedContent

valueToSum: Price of item viewed (if applicable)

When a product page is viewed.

A person lands on a product details page.

Content or ContentID, and ContentType

Currency

Add to Cart: FBSDKAppEventNameAddedToCart

valueToSum: Price of item added (required)

When a product is added to the shopping cart.

A person clicks Add to Cart.

Content, ContentType, and Currency

Purchase:

FBSDKAppEventNamePurchased

Use the logPurchase method instead.

valueToSum: Purchase price (required)

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.

Content, ContentType, and Currency


Parameters

Parameter: FBSDKAppEventParameterName Description Value Type

Content: FBSDKAppEventParameterNameContent

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\": 1}]


Note: This parameter is required for Add To Cart and Purchase event and is optional for View Content event if ContentID is provided.

string

Content ID: FBSDKAppEventParameterNameContentID

Product IDs associated with the event, such as SKUs.


Example: ['ABC123', 'XYZ789']

array of strings

Content Type: FBSDKAppEventParameterNameContentType

Either "product" or "product_group" based on the Content or ContentID being passed.

  • If the IDs being passed in Content or Content 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

Currency: FBSDKAppEventParameterNameCurrency

Currency for the value specified in ISO 4217 currency code.


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

string

Value: valueToSum

Value of a user performing this event to the business.

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

Example: 21.5

integer or float


Examples

ViewContent Event

[FBSDKAppEvents logEvent:FBSDKAppEventNameViewedContent
    valueToSum:54.23
    parameters:@{ FBSDKAppEventParameterNameCurrency    : @"USD",
                  FBSDKAppEventParameterNameContentType : @"product",
                  FBSDKAppEventParameterNameContent     : @"[{\"id\": \"1234\", \"quantity\": 1}]";

Or, with minimal parameters:

[FBSDKAppEvents logEvent:FBSDKAppEventNameViewedContent
    valueToSum:54.23
    parameters:@{ FBSDKAppEventParameterNameCurrency    : @"USD",
                  FBSDKAppEventParameterNameContentType : @"product",
                  FBSDKAppEventParameterNameContentID   : @"1234";

Note: The minimal parameter setup is valid for ViewContent only and not valid for AddToCart and Purchase.

AddToCart Event

[FBSDKAppEvents logEvent:FBSDKAppEventNameAddedToCart
    valueToSum:54.23
    parameters:@{ FBSDKAppEventParameterNameCurrency    : @"USD",
                  FBSDKAppEventParameterNameContentType : @"product",
                  FBSDKAppEventParameterNameContent     : @"[{\"id\": \"1234\", \"quantity\": 2}, {\"id\": \"5678\", \"quantity\": 1}]" } ];

Purchase Event

[FBSDKAppEvents 
    logPurchase:54.23
    currency: @"USD"
    parameters:@{ FBSDKAppEventParameterNameContentType : @"product",
                  FBSDKAppEventParameterNameContent     : @"[{\"id\": \"1234\", \"quantity\": 2}, {\"id\": \"5678\", \"quantity\": 1}]" } ];

Common Mistakes

  • Content: "[\"id\": \"SKU-123\"}, {\"id\": \"SKU-456\"}]" - Missing quantity key.
  • ContentID: "SKU-123,SKU-456,SKU-789" - Missing an array symbol.
  • ContentID: [] - Missing SKU IDs in an array.
  • ContentType: "soap" - The value is not "product" or "product_group".
  • Currency: "$" - Cannot use a currency symbol format.
  • valueToSum: "5000,00" - Wrong format (should not be a string with comma).