Meta AEM & CAPI Implementation Guide for Mobile Apps

This guide provides a strategic, high-level resource for implementing Meta AEM (Aggregate Event Measurement) and Conversions API (CAPI) for mobile apps and games. It helps you make informed decisions about when and how to integrate these solutions, with links to detailed technical documentation for implementation specifics.

Introduction & Philosophy

Goal of This Guide:

This guide provides a strategic, high-level resource for implementing Meta’s Aggregate Event Measurement (AEM) and Conversions API (CAPI) for mobile apps and games. It helps you make informed decisions about when and how to integrate these solutions, with links to detailed technical documentation for implementation specifics.

Who Is This Guide For:

• Mobile App or Game Developers implementing Meta SDK or MMP SDK and server-side event tracking
• Growth/Performance Marketers optimizing Meta ad campaigns with proper event instrumentation
• Product Managers overseeing mobile measurement and attribution strategy
• Technical Leaders evaluating AEM vs CAPI approaches for their app
• Anyone responsible for sending high-quality conversion data to Meta Ads

Core Principles:

• Send events that drive optimization decisions
• Prioritize event quality over quantity
• Use AEM for attribution, CAPI for precision
• Always deduplicate between client and server
• Think in terms of user journey, not just events

Understanding AEM vs CAPI

What is AEM?

Aggregate Event Measurement is Meta’s solution for iOS app attribution post-ATT. It enables:

• App install attribution without IDFA
• Post-install event optimization
• Campaign performance measurement with near real-time reporting

📚 Meta AEM Documentation

What is CAPI for Apps?

Server-to-server event sharing that provides:

• Higher event match quality
• Control over event validation (what actually happened)
• Ability to send events when app isn’t open (renewals, refunds)

📚 CAPI for Apps Documentation

When to Use What:

AEM Benefits:

• App Promotion and Re-Engagement Campaign types supported
• App Installs, App Events and Value Optimization
• Near real-time reporting
• SKAdNetwork can be used as a supplement
• 1-day and 7-day click reporting for campaigns
• Access to Meta Audience Network with optimization
• Breakdown support: age, gender, country, device, platform, placement

📚 AEM Event Eligibility Criteria

CAPI Benefits:

• Higher Event Match Quality (EMQ) scores through better user matching with additional parameters
• Improved signal quality of app events through server-side validation
• Both better user matching and improved signal quality likely enhance Meta UA campaign performance
• Send revenue transaction events only after they’ve been validated in server
• Ability to send events independent of app state
• Control over event timing and accuracy

📚 CAPI Best Practices

AEM Implementation Guide

Prerequisites:

Shared Prerequisites (AEM & CAPI):

• Meta Business Manager account with admin access
• App published on App Store
• Facebook App created and live in Meta Business Manager
• Dataset created in Events Manager and linked with Facebook App

AEM-Specific Prerequisites:

• Events sent via either: Facebook SDK, OR MMP (Mobile Measurement Partner)
• If using MMP: AEM configuration enabled in Meta
• If using AppsFlyer specifically: Advanced Data Sharing configured
• AEM Terms accepted: https://developers.facebook.com/advanced_mobile_measurement/terms

Note: Facebook App and Dataset must be created before implementing SDK/MMP, as the App ID is required for event integration.

Implementation Overview:

Step 1: Create Facebook App and Dataset

Before you can send events, you must set up the infrastructure in Meta Business Manager:

1. Create Facebook App:
   • Navigate to Meta Business Manager → Apps
   • Create a new app or select existing app
   • Note your App ID (required for SDK/MMP integration)
2. Create Dataset:
   • Navigate to Events Manager → Data Sources
   • Create new App dataset
   • Link Dataset to your Facebook App ID
   • Generate Access Token (will be needed for CAPI later)

Important: The App ID and Dataset ID are prerequisites for the next steps. You cannot implement SDK/MMP integration without these.

Step 2: Implement SDK or MMP Integration

Now that you have your App ID, integrate event tracking:

Option A: Facebook SDK Integration

• Implement Facebook SDK in your app using your App ID
• Configure SDK to log standard events
• SDK automatically sends events to Meta

📚 Facebook SDK for iOS | Facebook SDK for Android

Option B: MMP Integration (Recommended for Most Apps)

• Integrate your MMP SDK (AppsFlyer, Adjust, Singular, etc.)
• Configure Meta as a partner in your MMP dashboard using your App ID
• Map your in-app events to Meta standard events
• Enable postbacks from all sources to Meta (not just network-attributed traffic)

📚 AppsFlyer Meta Integration | AppsFlyer AEM Guide

Step 3: Verify Events Flowing and Check AEM Eligibility

After implementing SDK/MMP, verify that events are being received by Meta:

1. Navigate to Meta Events Manager
2. Select your App dataset
3. Check the Overview tab to confirm events are being received
4. Allow 24-48 hours for events to start flowing consistently

Once events are flowing, Meta automatically determines app eligibility for AEM.

To check AEM eligibility:

1. Events Manager → Select your dataset
2. Look for AEM eligibility status
3. If not yet eligible, check for any errors or warnings about event configuration

And this is how the eligibility results screen look like:

Note on June 2025 Updates: The automatic configuration and removal of the 8-event limit applies to web AEM. For mobile app AEM, verification of eligibility and MMP configuration is still required.

Step 4: Accept AEM Terms and Configure MMP for AEM

Once your app is eligible for AEM:

1. Accept AEM Terms (if not already done): https://developers.facebook.com/advanced_mobile_measurement/terms
2. Enable AEM in your MMP dashboard:
   • The specific steps vary by MMP (AppsFlyer, Adjust, Branch, Singular, Kochava, etc.)
   • General requirements: Map events to Meta standard events and toggle AEM setting
   • Refer to your MMP’s documentation for specific instructions

Critical Timing: Allow 2-3 days (sometimes up to 7 days) for Meta to revalidate eligibility after making configuration changes.

Important: After your app is eligible, you’ve accepted the terms, and completed MMP configuration, AEM will appear as the default attribution option when creating new campaigns in Meta Ads Manager.

Step 5: MMP-Specific Configuration (If Applicable)

For AppsFlyer Users:

Enable Advanced Data Sharing to send events for all users:

Settings → Integrated Partners → Meta
→ Advanced Privacy → Advanced Data Sharing: ON

What this does:

• Sends conversion events for ALL users (consented + non-consented)
• Uses probabilistic attribution with 24hr window
• Critical for maximizing your event volume post-ATT

📚 AppsFlyer Advanced Data Sharing

For Other MMPs:

Check your MMP documentation for equivalent privacy and data sharing settings.

Step 6: Event Volume Requirements

Meta AEM event frequency requirements are case-dependent and vary based on campaign type:

• App Install campaigns: Different requirements than AEO campaigns
• App Event Optimization (AEO) campaigns: May require higher event volumes
• Value Optimization: Typically requires minimum event volumes with distinct values (e.g., 100+ events with 10+ unique values for web)

Check Events Manager → Diagnostics for specific eligibility requirements for your app and campaign type.

If event volume is flagged as low:

• Consolidate similar events
• Use higher-funnel events temporarily
• Consider switching optimization goals based on available event volume
• Review Meta’s event eligibility criteria for your specific use case

📚 AEM Event Eligibility Criteria

Step 7: Verify iOS Tracking Parameters

For iOS 14.5 to iOS 16.x, ensure your integration sends:

• ATE (App Tracking Enabled) parameter
• Correct ATT consent status

Note: ATE parameter is not required for iOS 17.0 or newer devices.

Check Events Manager → Diagnostics for “ATE parameter volume out of range” warnings.

Important Considerations for AEM:

Common Issues to Avoid:

• Low event volume (requirements vary by campaign type)
• ATE parameter issues for iOS 14.5 – 16.x
• Advanced Data Sharing disabled (AppsFlyer)
• For other MMPs: Verify equivalent settings for sending all user data
• Different integrations between install events and post-install events: install and post-install events should come from same integration
• Duplicate events between MMP postbacks and server-side events. Use same event ID for deduplication

CAPI Implementation Guide

Prerequisites:

Shared Prerequisites (AEM & CAPI):

• Meta Business Manager account with admin access
• App published on App Store
• Facebook App created and live in Meta Business Manager
• Dataset created in Events Manager and linked with Facebook App

CAPI-Specific Prerequisites:

• Access Token generated with appropriate permissions
• Server infrastructure to send events

📚 Generate Access Token

Implementation Overview:

Step 1: Dataset Setup

1. Events Manager → Data Sources
2. Select your App dataset
3. Verify it’s linked to your Facebook App ID
4. Generate Access Token from Settings → API Access

Step 2: Understand Required Parameters

Every CAPI event must include:

Core Event Parameters (Required):

• event_name: Standard or custom event name
• event_time: Unix timestamp when event occurred
• action_source: MUST be "app" for app events
• event_id: Required for deduplication setup (reuse UUID from client)

User Data (At least one parameter required):

Meta requires at least one user data parameter per event. For best Event Match Quality and campaign performance, include as many as possible:

Recommended for iOS S2S events:

• client_ip_address: User’s device IP address
• madid: IDFV (iOS) or AAID (Android)

Additional parameters to improve Event Match Quality:

• em: Hashed email (SHA256)
• ph: Hashed phone (SHA256)
• fn, ln: Hashed first and last name
• ct, st, zp, country: Location data
• db: Date of birth (YYYYMMDD)
• ge: Gender (m/f/n)

Custom Data (For Monetization Events):

• value: Monetary amount
• currency: ISO 4217 code (e.g., “USD”)
• content_ids: Product identifiers
• subscription_id, billing_period, etc.

App Data (Required):

• advertiser_tracking_enabled: ATT consent status (0 or 1)
• application_tracking_enabled: Legacy LAT status (0 or 1)
• extinfo: Array of app/device metadata

📚 Complete CAPI Parameters Reference | User Data Parameters

Step 3: Implement Server-Side Event Sending

Use Meta’s official SDKs or direct API calls:

Available SDKs:

• Python Business SDK
• Node.js Business SDK
• PHP Business SDK
• Java Business SDK

📚 CAPI Server Event Implementation

Step 4: Choose Your Event Strategy

Key Events for Subscription Apps:

Standard Events (Use These):

• Purchase: Completed transaction
• Subscribe: First subscription charge
• StartTrial: Trial initiated
• CompleteRegistration: Account created

Custom Events (For Lifecycle Tracking):

• SubscriptionRenewal: Recurring charges
• SubscriptionUpgrade / SubscriptionDowngrade: Plan changes
• CancelSubscription: User cancels
• Refund: Payment refunded
• Paywall_Viewed: Paywall impressions

📚 Standard Events Reference

Step 5: Improve Event Match Quality

Higher EMQ = Better optimization

Priority Actions:

1. Strongly recommended: Add client_ip_address (user’s device IP, not server)
2. Strongly recommended: Add madid (IDFV for iOS, AAID for Android)
3. Hash and send em (email)
4. Hash and send ph (phone)

Hashing Requirements:

• Lowercase all values before hashing
• Trim whitespace
• Use SHA256 algorithm
• Remove special characters from phone numbers

📚 Event Match Quality Guide

Hybrid Approach (SDK + CAPI)

Why Use Both?

The hybrid approach combines the best of both worlds:

• SDK: Immediate event signals with low latency
• CAPI: Validated, enriched data with better match quality
• Together: Redundancy, deduplication, and optimal performance

The Golden Rule: Event Deduplication

Critical: Use the same event_id for the same real-world occurrence

Implementation Pattern:

Client Side:

1. Generate UUID when event occurs (this usually happens automatically by the Facebook SDK or MMP SDK)
2. Send event immediately via Facebook SDK or MMP SDK with event_id
3. Store event_id to pass to server

Server Side:

1. Retrieve stored event_id from client
2. Validate the transaction/action
3. Send event via CAPI with same event_id
4. Meta automatically deduplicates

📚 Deduplication Setup Guide

Common Use Cases:

Deduplication Best Practices:

Must Match Exactly:

• event_id: Same UUID format
• event_name: Same casing and spelling
• value: Same rounding (2 decimals)
• currency: Same format (e.g., “USD”)

Verify Deduplication:

• Events Manager → Data Sources → Dataset
• Check “Deduplicated Events” metric
• Verify that events are being deduplicated properly

Debugging & Validation

A. Events Manager Test Events

Setup:

1. Events Manager → Test Events
2. Generate Test Code (e.g., TEST12345)
3. Use this code for both SDK and CAPI testing

For SDK Testing:

• Install Facebook app on test device
• Login with same account as Business Manager
• Perform actions in your app
• View events in real-time in Test Events

Note: This also applies when using MMP SDKs without direct Facebook SDK integration.

For CAPI Testing:

Include test_event_code parameter in API calls. Events appear instantly in Test Events dashboard and do not affect production data.

📚 Test Events Setup

B. Event Match Quality (EMQ) Dashboard

Location: Events Manager → Data Sources → [Dataset] → Event Match Quality

EMQ Score Breakdown:

• 🟢 8.0-10.0: Excellent – Expect best performance
• 🟡 6.0-7.9: Good – Can improve with more parameters
• 🟠 4.0-5.9: Fair – Add hashed email/phone
• 🔴 <4.0: Poor – Missing critical parameters

How to Improve EMQ:

Current Score <6.0:

1. ✅ Strongly recommended to add client_ip_address (required for S2S)
2. ✅ Strongly recommended to add madid (IDFV for iOS, AAID for Android)
3. ✅ Add hashed em (email)
4. ✅ Add hashed ph (phone)

Score 6.0-8.0:

1. ✅ Add fn, ln (first/last name)
2. ✅ Add ct, st, zp (city, state, zip)
3. ✅ Add country (ISO 2-letter code)
4. ✅ Add db (date of birth)

📚 Improve Event Match Quality

C. Diagnostics Dashboard

Location: Events Manager → Diagnostics → [Dataset]

Common Warnings & Fixes:

📚 Events Manager Diagnostics

Common Issues & Solutions

Issue 1: Events Not Appearing in Events Manager

Symptoms:

• SDK fires event, nothing in dashboard
• CAPI returns 200, no event shown

Checklist:

• App ID linked to dataset?
• Access token has correct permissions?
• action_source: "app" included in CAPI?
• Test Event Code used for testing?
• Facebook app installed and logged in on test device?

Solution: Use Meta’s Graph API Explorer to check dataset linkage.

📚 Troubleshoot Events

Issue 2: Duplicate Events (No Deduplication)

Symptoms:

• Event count 2x expected
• Purchase value doubled in reporting

Common Causes:

1. Different UUID formats
2. event_id not persisted from client to server
3. Timestamp drift causing different event_time
4. Event name mismatch

Solution:

• Use same UUID library on client and server
• Store event_id in your database when client fires
• Round event_time to nearest second
• Use exact same event names (case-sensitive)

Issue 3: Low Event Match Quality

Symptoms:

• EMQ score <6.0
• Poor campaign performance
• High cost per action

Priority Fixes:

1. Strongly recommended: Add client_ip_address (user’s device IP, not server)
2. Strongly recommended: Add madid (IDFV for iOS, AAID for Android)
3. Hash and send em (email)
4. Hash and send ph (phone)

Hashing Checklist:

• Lowercase before hashing
• Trim whitespace
• Remove special characters from phone
• Use SHA256 algorithm

📚 Parameter Hashing Guide

Issue 4: AEM Events Not Attributed

Symptoms:

• Installs tracked in MMP but not Meta
• Post-install events missing
• “Advanced Data Sharing” warnings

Solutions:

All MMPs:

1. Verify event mapping to Meta standard events
2. Include revenue in postback settings for Meta
3. Turn on data sharing for all sources (not just for installs attributed to Meta)
4. Check event volume (requirements vary by campaign type)
5. Verify AEM is enabled in Meta
6. Confirm dataset linkage

AppsFlyer-Specific:

1. Settings → Meta → Advanced Privacy
2. Advanced Data Sharing: MUST BE ON

Issue 5: iOS S2S Events Rejected

Symptoms:

• Error: “Missing required parameter: madid”
• CAPI returns 400 error
• Events not eligible for AEM attribution

Solution:

For iOS S2S events to be eligible for AEM attribution, Meta requires both:

1. client_ip_address: IP of user’s device (not server IP)
2. madid: IDFV (Identifier for Vendor)

Without these identifiers, the event won’t be eligible for AEM attribution by Meta.

Get IDFV from iOS app and pass to server for CAPI payload.

📚 iOS IDFV Implementation

Appendix: Quick Reference

Standard Events for Subscription Apps:

• Purchase – Completed transaction
• Subscribe – First subscription charge
• StartTrial – Trial initiated
• CompleteRegistration – Account created
• AddPaymentInfo – Payment method added

Custom Events for Subscription Apps:

• SubscriptionRenewal – Recurring charge
• SubscriptionUpgrade – Plan tier increase
• SubscriptionDowngrade – Plan tier decrease
• CancelSubscription – User cancels
• Refund – Payment refunded
• Paywall_Viewed – Paywall impression
• TrialConversion – Trial converts to paid

Required Parameters by Event Type:

Important Links:

• Meta AEM Documentation
• CAPI for Apps Documentation
• CAPI Parameters Reference
• Event Match Quality Guide
• Standard Events Reference
• AEM Terms

Decision Framework Summary