App Events
Overview
Section titled “Overview”App Events sends in-app events from your iOS or Android app to your advertising platforms as server-side app conversions. Installs, purchases, product views and any custom event your app already tracks can all be delivered.
There are two ways to implement it. Your developers can call the Datahash API directly from the app, or you can send existing Firebase events onward through Google Tag Manager. The choice is about what your app already has in place rather than about what Signals can receive.
A mobile measurement partner is not required, but the two can run alongside each other. Where an MMP or another SDK is already tracking the same action, the event name has to match exactly on both, because that is what lets the destination recognize them as the same conversion.
Supported destinations
Section titled “Supported destinations”Destinations supported by App Events
| Category | Supported |
|---|---|
| App Conversions |
Prerequisites
Section titled “Prerequisites”- An iOS or Android app, and a development team who can add the event calls. Neither path is configurable from Studio alone.
- For the Firebase path, the Google Tag Manager SDK with the correct container for Android and for iOS, and Firebase already set up in the app.
- Agreement on which events matter and what each one is called, since the name has to stay identical everywhere it is sent.
- At least one device identifier available on the event, GAID on Android or IDFA and IDFV on iOS.
Configuration
Section titled “Configuration”Subdomain
Section titled “Subdomain”Events are posted to a subdomain issued to you, at the /apptrack path, and that address is what identifies your account.
Choosing a path
Section titled “Choosing a path”The Datahash API path suits apps whose events already exist in code, since it is a POST your developers add alongside the calls they make today. The Firebase path suits apps already sending events to Firebase, since the events are forwarded from there through GTM rather than written again.
Datahash API
Section titled “Datahash API”Send a POST to https://{subdomain}/apptrack with the event as JSON. The body carries the event name, the timestamps, the consent flags, the device and app context, the hashed user parameters and the event properties.
Implement the call in parallel with the existing MMP or SDK event rather than in place of it. The event value you send has to equal the name that MMP or SDK emits for the same action, with no synonyms, no difference in casing, and no swapping spaces for underscores.
Firebase SDK and GTM
Section titled “Firebase SDK and GTM”Add the required parameters to your existing Firebase events, logging them with Analytics.logEvent in Swift on iOS and the Java equivalent on Android. If your app is written in another language, Firebase’s own getting started guides cover it.
Then configure tags in Google Tag Manager to forward those events server-side to the destinations you have connected in Studio. The GTM request goes to the same subdomain and /apptrack path, with the event name and parameters as query parameters rather than a JSON body.
Required parameters
Section titled “Required parameters”The full parameter reference is in the implementation guide for the path you are using. The shape of it is the same either way.
| Group | Parameters |
|---|---|
| Required, on every event | channel, type, messageId, originalTimestamp, anonymousId, advertiserTrackingEnabled, applicationTrackingEnabled, event, sentAt, and integrations.All. |
| Required, per the implementation guide | event_time in Unix seconds, event_id, and the consent parameters application_tracking_enabled and advertiser_tracking_enabled. Purchase events also need value and currency. |
| Recommended, for match quality | Under context.userparams in the API body: h_email, h_phone, h_first_name, h_last_name, h_gender, h_dob, mobile_ad_id, idfv and external_id, plus ip_address and ua on the context itself. |
| Optional, describing the event | Under properties in the API body: currency, value, transaction_id, level, search_string, status, delivery_type and subscription_id, plus a products array carrying category, sku, name, sku_type, quantity, price and brand. |
Manage instance
Section titled “Manage instance”One subdomain serves the app. To change the destinations the events feed, open the instance from the Manage existing instance table, click the edit option in the menu to the top right, update the fields and click Finish.
Data & identifiers
Section titled “Data & identifiers”Hash personal data before you send it. Email address, phone number, first and last name, gender and date of birth all go as SHA-256 hashes, in the h_ parameters, and each has a normalisation rule to apply first, such as lowercasing an email address.
Do not hash device identifiers. GAID, IDFA and IDFV are sent as they are, and hashing them makes them unusable at the destination.
The consent flags travel with every event. advertiserTrackingEnabled and applicationTrackingEnabled record what the user permitted, so a destination that requires consent can honor it.
Best practices
Section titled “Best practices”- Use the same event names in the API or Firebase call as in your MMP. A name that differs by a capital letter or an underscore is a different event to the destination.
- Send a unique event_id, and keep it identical across every source reporting the same action. That is what deduplicates the event rather than counting it twice.
- Send timestamps in Unix seconds.
- Include at least one device identifier on every event, GAID, IDFA or IDFV.
- Agree the event list before development starts. Each event has to be implemented and mapped, so adding one later means another app release on the Firebase path.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”Events arrive but are counted twice. The event_id differs between the sources sending the same action, so the destination cannot tell they are the same event. Make it identical across all of them.
The destination reports the event under a different name. The event value does not match what the MMP or SDK emits. Compare the two character for character, including casing and underscores.
Match rates are low. Usually no hashed identifier on the event, or a normalisation step missed before hashing. A hash only matches if both sides normalized the value the same way.
Device identifiers are not matching. Check they are being sent unhashed. Personal data is hashed and device identifiers are not.