In-app event postback configuration

At a glance: Measure app engagement and quality of your users, and optimize campaigns using in-app events data.

 Related reading

For a complete picture of working with in-app events, be sure to read these articles:

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 of in-app events performed via postbacks. About rich in-app events

Postback in-app event selection

Marketers select the in-app events for which postbacks are sent 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 the AppsFlyer partners team to finish the integration.

In-app event postback window

The in-app event postback window allows marketers who work with networks on a CPA (cost-per-action) basis to configure post-conversion windows after which event postbacks are no longer sent.

For example, if you're charged for events happening within 15 days of a user install, set the window as follows:

15-day_in_app_event_postback_setting.png

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,
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.

The postback is sent because 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:

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.
enter_event_name.png

Select an event ID from the list

  • AppsFlyer event: From the list of your app events, select an event.
  • mapped to partner event: From the list of predefined partner events, select the event that corresponds to your app event (AppsFlyer event).

In-app_event_postbacks_en-us.png

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:

  1. Click Add event.
  2. 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.
  3. Repeat this procedure for more events. 

send_postbacks_as_is_en-us.png

To send all events:

  1. Select Send all events (excludes uninstalls and sessions).
  2. Select the postback options:

send_postbacsk_as_is_no_mapping.png

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.

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 defined in their event value. Otherwise, ad networks get events with empty revenue value.

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}

This is how the parameters are sent:
Field name event_value monetary currency
No values & no revenue  N/A N/A  N/A
Values & no revenue

{"af_currency":"N/A","af_content_id":"1234567",

"af_revenue":"N/A","af_content_type":"category_a"}

&monetary=N/A&content_id=1234567

N/A  N/A
Values & revenue

"af_currency":"JPY","af_content_id":"1234567",

"af_revenue":200,"af_content_type":"category_a"}

&monetary=1.856918&content_id=1234567

50.87 USD

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.

in_app_event_condition__1_.png

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:

  1. On the partner integration page, define and map the required in-app events to send to the partner.
  2. Click the Add conditionimage.pngicon of the required event.
  3. 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
  4. You can add more conditions, just make sure you enter all the fields of the existing condition first.
  5. 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:

  1. Select the events to update.
  2. Click Bulk actions.
  3. 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

In-app_event_postbacks_en-us.png

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:

  1. Type in the name of the event.
  2. Click Create custom

    In-app_event_postbacks_en-us.png

  3. Map the event to the partner identifier.
  4. Click Save Integration to make sure the mapping is recorded.

 Note

  • When adding a custom event under a certain partner, the event gets 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 also 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:

  1. On the Integrated Partners page find the partner you want to give permission to.
  2. Under the Permissions tab switch the Allow to configure in-app event postbacks toggle to ON.

adnetwork-permissions-postbacks.png

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

When granting mapping permissions to the agency, they can also configure in-app event conditions.

To grant the agency permission to configure in-app postbacks:

  1. Find the agency in the list of integrated partners.
  2. Select whether the agency can share all events or only those attributed to the specific ad network.
  3. Select whether the agency is allowed to send event revenues.
  4. Select the specific events the agency is allowed to share.

agency-events.png