At a glance: Measure app engagement and quality of your users, and optimize campaigns using in-app events data.
Overview
In-app events enable marketers to measure app engagement and user quality from different sources and to build an appropriate user acquisition strategy. Ad networks use in-app event information to optimize campaigns and run cost-per-action/event campaigns. Ad networks receive data on in-app events via postbacks—which are sent in real time. Learn more about rich in-app events.
Postback in-app event selection
Marketers can select for which in-app events they want to send postbacks to ad networks, using the settings described in this article.
Note
- In-app events include rejected events, meaning in-app events blocked by Protect360 or events found to be non-compliant with target validation rules.
- If the In-app event postbacks section doesn't exist in the Integration tab, it means the partner hasn't yet set up in-app event recordings with AppsFlyer in its preliminary configuration. The partner can contact AppsFlyer using the partner assistant widget to finish the integration.
In-app event postback window
For example, if you're charged for events happening within 15 days of a user install, set the window as follows:
Postbacks after this period are not sent, and the network is not notified, but the events are still recorded in AppsFlyer and attributed to the network.
The postbacks are always sent based on the current window setting. See the following example:
January 1 |
The window is 15 days. A user installs an app. |
January 2 | The window is changed to 10 days. |
January 14 |
The user makes a purchase. The postback isn't sent to the ad network because the event doesn’t fall within the current window (10 days). |
January 15 | The window is changed to 20 days. |
January 18 |
The user makes another purchase. This time the postback is sent—since the event falls within the current window (20 days). |
Default postback window
When starting to set up in-app event postbacks, the default window is automatically set to six months.
Note
If you've started using in-app event postbacks with a specific partner before July 30, 2019, the default setting for the window is Lifetime. This means that in-app event postbacks are always sent.
Who can configure postback windows
- Marketers
- Agencies, if they're given the Allow to configure in-app event postbacks permission.
Note: A marketer and an agency working with the same ad network can configure postback windows separately from each other, based on their contract with the network. - Partners, if they're given the Allow to configure in-app event postbacks permission.
Event mapping
Each marketer can give a different name to an event of the same type. Such event names may also differ from the partner names.
For example, when a user purchases something through an app, one marketer may name it purchase, or a less informative ID, such as event5, and a partner may name it purchase_event.
To make sure that the marketer's events match the same events as the partners, event names must be mapped.
Note
Events mapped in the Integration tab for a specific partner are applicable both for standard and SKAN postbacks.
Mapping methods
Each partner decides which of the following methods are to be used for mapping their in-app events:
Note
- Not all mapping methods appear for all partners
- You can give the partner permission to do the mapping itself
Enter the partner event ID
- AppsFlyer event: From the list of your app events, select an event.
- mapped to partner event: In the text field, enter the event ID as received from the partner, that corresponds to your app event (AppsFlyer event)
Note
- Event names are case-sensitive. To avoid discrepancies, make sure you use the correct event name for all media sources and app versions.
- When typing an event name, you can use underlined spaces (low dashes) before or after the event name. Make sure to use underlined spaces only when the event name being sent from AppsFlyer has the exact same underlined spaces.
Select an event ID from the list
Send events as they are (unmapped)
Some partners prefer to receive unmapped in-app event postbacks—meaning the event names are sent as they're named in your app. It doesn't matter if the event is called purchase, acquisition, or event5.
You can choose which unmapped events to send to the partner:
- Add manually: Select specific events.
- Send all events (excludes uninstalls and sessions): Send all your events. This doesn't include uninstalls, sessions (app launches), and the af_app_opened event.
Note
To prevent advertisers from unintentionally sharing too much information with third-party Analytics platforms, we've removed the Send all events (excludes uninstalls and sessions) option for these platforms, as of March 2019. Analytics platforms configured before this date still retain this setup option.
To manually add events:
- Click Add event.
- Select the postback options:
- AppsFlyer event: From the list of your app events, select an event.
- for users from: Select the sending option for the event.
- including: Select which data to include in the postback.
- Repeat this procedure for more events.
To send all events:
- Select Send all events (excludes uninstalls and sessions).
- Select the postback options:
- for users from: Select the sending option for all events.
- including: Select which data to include for all events in the postback.
For more information on mapping events, see in-app event postbacks.
Options for sending postbacks
For each event, you can choose in which case to send the postbacks (within the postback window):
- This partner only: Send postbacks only when the event is attributed to this partner—meaning, the user who performed it came from this partner.
- All media sources including organic: Send postbacks to all media sources for events attributed to any partner and for organic events—meaning, when the user who performed it came from any media source. Note: When All media sources including organic is selected, postbacks for other partners don't contain attribution data.
Data to include in the postbacks
You can choose which kind of event data you can share with the partner in the postback. Select one of the following options:
- No values & no revenue: Send just the event itself without any parameters (values or revenue).
- Values & no revenue: Send all the parameters excluding the revenue value.
- Values & revenue: Send all the event parameters, including the revenue value (if exists in the event).
It is recommended to share revenue if you want ad networks to optimize your campaigns and improve campaign results. However, sharing revenue is not mandatory. Make sure to enable revenue sharing only for events that have af_revenue
or af_projected_revenue
defined in their event value. Otherwise, ad networks get events with empty revenue value.
Share revenue
In postbacks, af_revenue
and af_currency
are written outside of the event_value JSON as monetary and currency and can be sent separately. Example postback structure: https://appsflyer.com/push?event_value=(event-value)&monetary=(monetary)&content_id=(af_content_id)
Note: When choosing the options with either No values & no revenue or Values & no revenue, the respective parameters are masked with N/A.
Example
A marketer sends a purchase event with the following event_value:{af_revenue: 50.87, af_currency: USD, af_level=2, af_receipt_id=57601333}
The table below shows how the parameters are sent:
Field name | event_value | monetary | currency |
---|---|---|---|
No values & no revenue | N/A | N/A | N/A |
Values & no revenue |
|
N/A | N/A |
Values & revenue |
|
50.87 | USD |
Share projected revenue
By selecting Values & revenue you can choose to share projected revenue from ad networks during postbacks. (Contact AppsFlyer support to learn whether your ad network support projected revenue).
When projected revenue event is shared with the partner, AppsFlyer sends a postback with similar structure to the actual revenue postback with two differences:
- The
af_projected_revenue
key replaces theaf_revenue
key. - The
revenue_type
field accepts theprojected
value.
Example
A marketer sends a projected revenue event with the following event_value:{af_projected_revenue: 50.87, af_currency: USD, af_level=2, af_receipt_id=57601333}
The table below shows how the parameters are sent:
Field name | event_value | monetary | currency | revenue_type |
---|---|---|---|---|
No values & no revenue | N/A | N/A | N/A | N/A |
Values & no revenue |
|
N/A | N/A | N/A |
Values & revenue |
|
50.87 | USD | projected |
Conditional in-app event postbacks
Filter in-app event postbacks using multiple conditions that can be mapped to different events. Only events meeting the filter conditions are sent to partners, including SRNs and Analytics partners. Use this feature for:
- Optimizing user segmentation, personalization, and retention
- Minimizing data
- Protecting user privacy
Example
A marketer with a gaming app wants to optimize campaigns running through an ad network, but only for users who pass level 10 or level 50, or for users who spend $3 on app purchases.
This is how conditions for this event are set:
- When level equals 10, map to fb_mobile_level_acheived
Otherwise (OR), - When level equals 50, map to fb_mobile_level_acheived
Otherwise (OR), - When cost equals 3, map to fb_mobile_purchase
To set up conditions for an event:
- On the partner integration page, define and map the required in-app events to send to the partner.
- Click the Add conditionicon of the required event.
- Enter the condition fields, as they appear in the event value:
- Property name
- Value
- Partner event to map the condition to (using any of these mapping options)
- You can add more conditions, just make sure you enter all the fields of the existing condition first.
- Click Save integration.
Considerations
When configuring conditions, make sure the following considerations are met for the event to be sent to the partner:
Condition structure
- Both the property and the value in the condition must match the data on the event.
- Currently, conditions can only be set to “equal”.
- Complex structures such as arrays are not supported.
Multiple conditions for an event
- The maximum number of conditions per event is 5.
- At least one condition must be met for the postback to be sent, but only one condition is executed.
- Each condition is checked by order of appearance—the first condition to be met is executed.
- Each condition is mapped separately. The partner event name is changed to Based on conditions.
- More than one condition can have the same property or the same value, but no two conditions can have both the same property and value.
- More than one condition can be mapped to the same event.
Note
- It's recommended to test this feature with a test app or for minor events to understand its impact on campaign optimization.
- To see the postback content, you can download the raw data postback report.
Editing multiple events
While mapping events, values in the fields for users from and including can be edited for multiple events in one action.
To edit multiple events:
- Select the events to update.
- Click Bulk actions.
- Select the new setting to apply to all selected events:
-
for users from (choose one option only)
- This partner only
- All media sources, including organic
-
including (choose one option only)
- No data (default)
- Values without revenue
- Values and revenue
-
for users from (choose one option only)
Custom events
The list of events available for mapping shows only the events already reported by the SDK or from server-to-server events sent to AppsFlyer. If the event you want to map doesn’t appear in the drop-down list, this can happen for the following reasons:
- No user has performed the event yet
- The last time the event occurred was over two weeks ago
- You have a large list of active events
In either of these cases, to map the event to the partner ID:
- From the dropdown list, click + Add item.
- In the text box, type the name of the event you want to add.
- Click the V sign to confirm. The event you've added now appears in the list and you can select it.
- Map the event to the partner identifier.
- Click Save Integration to make sure the mapping is recorded.
Note
- Adding custom events on the postback page doesn't automatically pull them from your app. Events must be configured in the SDK or S2S for proper functionality. See how to send events to AppsFlyer.
- When a custom event is added under a certain partner, the event is added to the list of events for all partners. Meaning, you can see this event under any partner drop-down list of events.
- See tips and limitations for defining event names and parameters.
Agencies and ad networks:
- Can't add custom events
- Can only view and/or map events after the marketer added the event and granted the necessary permissions
Event mapping by ad networks
Marketers can allow ad networks to map the events and disable postbacks on their own. To do so, a marketer should give relevant permissions to the ad network:
- On the Active Integrations page find the partner you want to give permission.
- Under the Permissions tab switch the Allow to configure in-app event postbacks toggle to ON.
Once the ad network has received the permissions, they can map the events following the instructions in the Type Event ID Into Text Field.
Event mapping by agencies
Marketers can allow agencies to configure in-app event postbacks.
To grant the agency permission to configure in-app postbacks:
- Find the agency on the Active integrations page.
- Select whether the agency can share all events or only those attributed to the specific ad network.
- Select whether the agency is allowed to send event revenues.
- Select the specific events the agency is allowed to share.