At a glance: Measure app engagement and quality of your users, and optimize campaigns using in-app events data.
In-app events enable advertisers 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 of in-app events performed via postbacks. About rich in-app events
Postback in-app event selection
Advertisers select the in-app, events for which postbacks are sent using the settings described in this article.
In this article, in-app events include rejected events meaning in-app events blocked by Protect360 or events found to be non-compliant by target validation rules.
In-app event postback window
For example, if you're charged for events happening within 15 days of a user install, the window is configured 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 is not sent to the ad network, |
January 15 |
The window is changed to 20 days. |
January 18 |
The user makes another purchase. The postback is sent because the event falls within the current window (20 days). |
Default settings
If you 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.
If you just started to set up the postbacks, the default window is automatically set to 180 days.
Who can configure postback windows
The window can be configured by:
- Advertisers
- Agencies, if they are given the Allow to configure in-app event postbacks permission
Note: an advertiser and an agency working with the same ad network can configure postback windows separately from each other, based on their contract with the network. - Ad Networks, if they are given the Allow to configure in-app event postbacks permission
Event mapping
Different advertisers can give different names to the events of the same type in their code. The names of the events used by the advertisers may also differ from the names given to them by media sources. For example, when a user purchases something through an app, one advertiser can call it a purchase, another one purchase_event. The ad network can pick a less informative ID, e.g. event5.
Most ad networks want to make sure that purchase is the same event as event5. Therefore, names must be mapped for each media source you work with.
Note
- Event names are case-sensitive. To avoid discrepancies, make sure you use the correct name for all media sources and app versions.
- Events mapped in the Integration tab for a specific partner are applicable both for standard and SKAN postbacks.
Mapping methods
There are three possible methods of mapping the events. Each ad network has its own preference and you should discuss this with them. You can also give permission to the network to map the events on its own. See the next section to learn how to do that.
Type event ID into the text field
Pick event ID from a list
Send events as they are
Some networks prefer to receive the events as they are, that is, it doesn't matter if the event is called purchase, acquisition, or event5.
In this case, you can choose one of the two options:
- report all events
- manually select the events you want to send
Note: If you choose to report all events, af_app_opened event, uninstalls, and sessions are not reported.
If you choose to manually add events, click Add event, and select the event you want to send. Repeat to add more events.
See Integrated partners, event mapping
Options for sending postbacks
For each event, you can choose in which cases to send the postbacks:
- All media sources, including organic: for events, including organic events, attributed to any media source
- This partner only: for events attributed to this partner only
If you choose to send all events "as they are", this applies to all events.
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 data (default): send only the event itself without the event value
- Values without revenue: send all event parameters, except for the revenue
- Values and revenue: send all the event parameters, including the revenue (if exists in the event)
In postbacks, af_revenue and af_currency are written outside of the event_value JSON as monetary and currency and can be sent separately.
Note: When choosing the options with either No data or Values without revenue, the respective parameters are masked with N/A.
Example
An advertiser sends a purchase event with the following event_value: {af_revenue: 50.87, af_currency: USD, af_level=2,
af_receipt_id=57601333}
This is how the parameters are sent in case of each option:
- No data
- event_value: N/A
- monetary: N/A
- currency: N/A
-
Values without revenue
- event_value:
{af_revenue: N/A, af_currency: N/A, af_level=2, af_receipt_id=57601333}
- monetary: N/A
- currency: N/A
- event_value:
-
Values and revenue
- event_value:
{af_revenue: 50.87, af_currency: USD, af_level=2, af_receipt_id=57601333}
- monetary: 50.87
- currency: USD
- event_value:
Conditional in-app event postbacks
Filter in-app event postbacks so that only events meeting filter conditions are sent to partners. Set filters based on event name, properties, and values.
Use this feature to optimize user segmentation, personalization, and retention.
Considerations
- AppsFlyer sends the event to the partner in the following scenarios:
- Both the property and its value match the data on the event.
- There were no conditions configured.
- In case there isn’t a match of the property or the value, the event won’t be sent. For example, if the data on the event is "event_value": "{\"level\":\"5\"}", and the property in the condition is “af_level”, then the event won’t be sent because the property doesn’t match (“level” on the event and “af_level” configured in the condition). In addition, if the data on the event is "event_value": "{\"level\":\"6\"}", and the value in the condition is 5, then the event won’t be sent because the values don’t match.
- Conditional in-app events can be configured for all partners including SRNs and analytics partners.
- Agencies are allowed to configure conditions for in-app events.
- The maximum number of conditions, which include a property and a value, is 5, per event.
- Currently, conditions can only be set to “equal”, and in case there are multiple conditions for a specific event, at least one of them needs to be met to send the postback.
- Complex structures such as arrays are not supported.
- It's recommended to test this feature with a test app or minor events to understand its impact on campaign optimization.
To set up conditions for an event:
- On the partner’s integration page, define and map the required in-app events to send to that partner.
- Click the Add condition icon of the required event.
- In the Property and Value fields, enter the property and its value for comparison.
- Click Save Integration.
Example
An advertiser has a gaming app, and would like to optimize campaigns running through Ad Network X - but only for users who passed to level 5. To do that, the advertiser goes to the In-app event postback section in Ad Network X’s integration page, and sets a condition for the event “level_up” with the property “level” and the value “5”. AppsFlyer will now send this event to Ad Network X only for users who reached level 5. The condition on the postback is displayed as: "event_value": "{\"level\":\"5\"}". If the advertiser would like to apply two conditions or more, they need to pass the event_value as follows: "{\"property1\":\"value1\",\"property2\":\"value2\"}"
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 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 event has been performed for the last time more than 2 weeks ago.
- If you have a large list of active events.
In either of these cases, in order to map the event to the partner ID, you can do the following:
- Type in the name of the event.
- Click Create custom
- Map the event to the partner identifier.
- Click Save to make sure the mapping is recorded.
Note that when you add the event in this way under a certain partner, this event is also added to the list of events in all other partner integrations you have. Meaning, you can see this event in the drop-down list under any partner’s integration, and map it normally.
Agencies and ad networks:
- Cannot add custom events
- Can view and/or map events if the advertiser added the event and grants the necessary permission
Event mapping by ad networks
Advertisers can also allow ad networks to map the events and disable postbacks on their own. To do so, an advertiser should give relevant permissions to the ad network:
- On the Integrated Partners page find the partner you want to give permission to.
- Under the Permissions tab switch the Allow to configure in-app event postbacks toggle to ON.
Once the ad network has received the permissions, it can map the events following the instructions in the Type Event ID Into Text Field.
Event mapping by agencies
To give the agency permission to configure in-app postbacks:
- Find the agency in the list of integrated partners.
- 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 events revenue.
- Select the specific events the agency is allowed to share.