App Events for Dynamic & Catalog Ads

Follow
Avatar
Ana Cerco
Updated

Overview

Dynamic and catalog ads are a class of campaign that automatically shows a user the right product from your catalog based on what they've actually done in your app — viewed, added to cart, purchased — instead of running one static creative for everyone. Most major ad networks offer their own version of this (Meta's Advantage+ Catalog Ads, Google's Dynamic Remarketing, TikTok's catalog ads). For the ad platform to match that in-app behavior back to a specific catalog item, your app needs to send a defined set of parameters alongside the event itself.

Relevant events

The following actions are the events that networks generally recommend for catalog matching — each has a standard Singular event name you can use regardless of platform, alongside the name the network itself expects:

Action Singular standard name Meta Google TikTok
View Content sng_content_view ViewContent view_item ViewContent
Add to Cart sng_add_to_cart AddToCart add_to_cart AddToCart
Initiate Checkout sng_checkout_initiated Optional begin_checkout (strongly recommended) Optional
Purchase sng_ecommerce_purchase Purchase ecommerce_purchase Purchase

Standard parameters

Parameter Type Definition
content_id String The catalog item's product ID. Can be a single ID, or an array of IDs (for example ["sku_1","sku_2"]) when one event covers more than one product. Must match your product catalog exactly, including case.
content_type String product or product_group, where the platform distinguishes the two.
value String The revenue or order total for the event.
currency String ISO currency code.
contents String For orders where each product needs its own quantity (and sometimes its own price): a list pairing each content_id with those per-item details, instead of one flat ID and one total. Must be sent as valid, parseable JSON.

Payload examples for parameters

One product:

{
  "content_id": "sku_10293",
  "content_type": "product",
  "value": 129.90,
  "currency": "USD"
}

More than one product in the same order — uses contents instead of a single content_id:

{
  "content_type": "product",
  "contents": [
    { "content_id": "sku_10293", "quantity": 8 },
    { "content_id": "sku_88213", "quantity": 2 }
  ],
  "value": 311.40,
  "currency": "USD"
}

Steps to configure

  1. Add the standard parameters above to your existing View Content, Add to Cart, and Purchase events (and Initiate Checkout, if targeting Google) via the Singular SDK or S2S.

  2. Make sure content_id values match your ad platform's catalog exactly, including case.

  3. If your catalog ads should open directly to a product page, set your catalog's deep-link field to your app's native URI scheme or Universal/App Link. This is configured through the catalog feed itself, separately from the event parameters above.

  4. Add the events in Partner configuration and map them to the relevant network event name.

  5. Submit a request to Singular Support with the network, the events involved, and the parameter names your app is sending, so your postback can be mapped.

  6. Test on each network individually with a live or preview ad click. Catalog matching can't be verified from a dev sandbox.

The structure above is a guideline — a common pattern that can be used as a starting point if you're running catalog campaigns across more than one network and want one consistent payload to send from the app. The exact field names, and which ones are required, still vary by platform. You can check the specifics for the network you're setting up in: Facebook (Meta) Ads Attribution Integration, Google Ads (AdWords) Mobile App Campaigns Attribution Integration, and TikTok Ads Attribution Integration.

Comments

Please sign in to leave a comment.