Rich in-app events—Overview

In-app events that you want to send require your developer to implement code where applicable in your app. Event names and event parameters are classified as follows:

• Predefined: These are event names and event parameters that are commonly used among different apps. We highly recommend using predefined event names and event parameters as much as possible for the following reasons:
  • Predefined naming allows automatic mapping of events to partners. 
  • If AppsFlyer decides to change the name of any event or event parameter, your implementation is backward compatible.
• Custom: These are event names and parameters that you define for specific user scenarios that occur in your app. You can use any custom event name or parameter name string, but keep in mind that custom events need maintenance by your developer. See Tips and Limitations.

Whenever you send in-app events such as a purchase or flight booking, you send it with its associated revenue. The sole parameter that carries revenue in in-app events isaf_revenue

• Recording revenue in the SDK
• Recording Revenue in Unity

You can also record negative revenue in case a user cancels a purchase or if you issue a refund. To record negative revenue, all you have to do is append the minus sign (-) to the revenue value that you pass toaf_revenue

af_revenue is the only parameter that accumulates your users' revenue. Always use it with in-app events that represent actual revenue generation in your business logic.

The range of this value should be $-10,000 to $+10,000 or the equivalent original currency amount. Values outside of this range are included in raw data reports but not in aggregate reports. 

af_revenue can also bear negative revenue values if you need to record events such as canceled transactions or refunds.

Note:

• Do not format the revenue value in any way. It should not contain comma separators, currency, special characters, or text. A revenue value should be similar to 1234.56, for example. AppsFlyer provides revenue value with precision of up to five decimal places.
• AppsFlyer displays the exact revenue as sent from the SDK. It does not include any calculations for VAT or app store commissions, etc., unless these were included by the developer on the SDK side prior to it being sent to AppsFlyer.

af_currency represents the currency that is stated in af_revenue (or af_price). If af_currency is missing from the event's parameters, AppsFlyer sends it with the default value "USD".

You can use af_price as a monetary parameter that is not counted as revenue (such as in an “Add to Cart” event). This parameter refers to the individual item price. The total amount of all purchases appears under the af_revenue parameter.

Revenue currency

It's important to understand how AppsFlyer handles currency settings and currency conversion.

AppsFlyer handles the difference between app settings currency and in-app events currency using currency conversion.

The diagram above demonstrates the following process:

1. In-app events are sent - different currency for each event
2. AppsFlyer normalizes all currencies to USD
3. AppsFlyer processes revenue data
4. Revenue data in the dashboard is displayed in app settings currency
5. AppsFlyer populates revenue data in raw data reports in both event and app settings currency

AppsFlyer uses Open Exchange Rates for currency conversion. The exchange rate is updated on an hourly basis. Whenever AppsFlyer performs currency conversion, it uses the exchange rate of the last hourly update.

Currency conversion

Map<String, Object> eventValue = new HashMap<String, Object>();
eventValue.put(AFInAppEventParameterName.REVENUE,200);
eventValue.put(AFInAppEventParameterName.CONTENT_TYPE,"category_a");
eventValue.put(AFInAppEventParameterName.CONTENT_ID,"1234567");
eventValue.put(AFInAppEventParameterName.CURRENCY,"EUR");
AppsFlyerLib.getInstance().trackEvent(getApplicationContext() , AFInAppEventType.PURCHASE , eventValue);

Currency display

Currency is set in the app settings. The currency that you set in the app settings, is the currency that appears in the dashboard. No matter what currency you send in-app events, the revenue in the dashboard always appears in the currency that you set in the app settings.

Once you determine the in-app events that you want to measure, use our In-app event generator to define the events and parameters as follows:

1. Select an event name that is most suitable to the scenario you want to record.
2. Select the event parameters that you want to associate with the event. Choose parameters that will provide additional context to the event and enrich the data.
3. Download the completed file from the in-app event generator, and then share it with your developer.

The following table provides links to articles that include examples and flows of the typical in-app events we suggest recording per vertical.

Business vertical	Article title
	Recommended gaming app events
	Recommended eCommerce app events
	Recommended entertainment app events
	Recommended finance and banking app events
	Recommended P2P lending app events
	Recommended online education app events
	Recommended ride-hailing app events
	Recommended flight booking app events
	Recommended hotel booking app events
	Recommended healthcare app events
	Recommended telecommunication app events
	Recommended eWallet app events
	Recommended sports betting events

In-app events are attributed to the media source responsible for the install throughout the lifetime of the user. Event data is presented as Life Time Value or Activity data. 

You can view your in-app event data in these locations:

• Dashboard overview page: Displays real-time LTV user acquisition (UA) performance. Note: This includes revenue divided between organic and non-organic users reported via in-app events, and retargeting revenue that is double-attributed.
• Events page: Displays LTV in-app event performance across media sources
• Activity page: Displays in-app activities for the selected date range.
• Raw data in-app event report: Displays activity data, meaning, a chronological list of the actions performed by your entire user base. This report includes event parameter values, for example:

  {
    "af_level":"10",
    "af_score":"3387",
    "arena":"7",
    "char_type":"paladin"
  }

  Note that raw-data reporting is a premium feature.

Keep in mind the following when defining event names and parameters in the app:

• For data consistency in raw-data reporting, we recommend defining and using the same in-app event names and structures across all platforms.
• Use a minimal number of events to make it easier to compare the quality of users coming from different sources.
• It is important that you ensure the privacy of your users. Don't populate in-app event values with restricted data that can directly identify them. For example, email address, name, identity number, and in some locations postal code. For more information about restricted data, read the services privacy policy.
• Note that AppsFlyer collects the IP address of devices during engagements. In some jurisdictions or use scenarios, the IP address can be regarded as PII. We use the IP address to derive the broad geographic location (city, district level) of the device but not the specific address. If needed, you can select to mask IP addresses so that they don't appear in raw data reports. 
• In-app events are the only source of revenue data in AppsFlyer. You can attach a specific revenue value to each event, and view it on your app's dashboard. Learn more about the monetizing parameters.

  

Keep in mind the following when defining event names and parameters in the app:

• We recommend using only lower-case alpha-numeric characters (a-z and 0-9) for your in-app event names. Event names are case sensitive, meaning that af_purchase and af_PURCHASE are two different events in the raw data. However, in aggregate reports (for example, Overview, or Events) they can be displayed as a single event.
• There is a cardinality limit of 300 unique events per day. Learn more
• Unique users are only counted for the first 100 events after they install the app.
• Event names cannot begin with these characters: " = + - 
• Event names cannot contain empty spaces. You can use underlined spaces (low dashes) before or after the name of the event.
• Event values should not exceed 1000 characters. 
• If you include the referring URL as an event value, it must be URL encoded.
• Facebook has some limitations regarding event names and parameters. Read about the limitations here.

You can send revenue values with any parameter name and event. However, to register the revenue (including negative revenue) in the AppsFlyer raw and aggregated data, you MUST use the af_revenue parameter. Always use it with in-app events that represent actual revenue generation in your business logic.

af_currency represents the currency that is stated in af_revenue (or af_price). If af_currency is missing from the event's parameters, AppsFlyer sends it with the default value "USD".

For more information about the af_revenue parameter, see the Revenue Attribution guide.

In-app events are attributed to the original media source of the app install.

Upon the install of an app (first app launch) AppsFlyer uses various attribution methods to determine the attribution of the install. At the same time, the AppsFlyer SDK creates a new unique AppsFlyer ID, which is associated with the attribution details.

Every consequent in-app event performed by the same device in the app has this ID. This enables AppsFlyer to attribute the event to the original media source. Advertisers can use this to follow the full user journey in their app.

Events of recently retargeted users may have double attribution.

AppsFlyer attributes events of attributed installs as organic when:

• More than 24 months pass after the install date
• The media source's terms dictate deleting the user-level data
• The user deletes the app's stored data on the device, forcing the creation of a new AppsFlyer ID.

If a user initiates an event when the internet connection is unavailable, AppsFlyer is still able to record it. This is how it works:

1. SDK sends the events to the AppsFlyer servers and waits for a successful response.
2. If the SDK doesn’t receive a successful response, the event is stored in the cache.
3. Once the next successful response is received, the stored event is sent to the server again.
4. If there are multiple events in the cache, they are sent to the server, one after the other.

Complex in-app events enable sending multiple events in a single API call.

They are useful when you want to see several closely related user actions grouped together (for example, adding several products to the basket in a single session).
Example:

{
  "af_revenue":"50.87",
  "af_currency":"USD",
  "af_receipt_id":"57601333",
  "product":[ 
   { 
	 "af_content_id":"1164_8186",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"1164_8186",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"1164_8186",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"1177_8185",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"0153_9077",
	 "af_price":"14.99",
	 "af_quantity":"1"
   }
  ]
}

You can add multiple items to a single transaction. Instead of single values per event parameter, you can have an array of items describing the transaction, separated by commas. The format should be a JSON string.

"{\"af_content_id\": [\"123\",\"988\",\"399\"], \"af_quantity\": [\"2\",\"1\",\"1\"], \"af_price\": [\"25\",\"50\",\"10\"], \"af_revenue\": \"110\", \"af_currency\": \"USD\"}"

We have an in-app event deduplication mechanism. It checks all in-app events to see if there was an identical in-app event that came from the same appsflyer_id less than 10 seconds beforehand. If such an event is found, the mechanism removes the duplicate.

Two events are considered identical if the following fields in both events are the same:

• Event name
• Event value
• App ID
• AppsFlyer ID

AppsFlyer retains user-level (raw-data) for 24 months except where otherwise directed, required, or allowed by law. Some SRNs/partners require attribution providers, including AppsFlyer, to delete SRN/partner-related user-level data before the expiry of the 24 month period.

After deletion, events related to deleted users display as organic. Past aggregate data is not changed. For more information, see Data retention and deletion obligations.

• The Android SDK and iOS SDK automatically add the OS (operating system) parameter.
• For the S2S API, starting July 1, 2021, you must send the OS (operating system) parameter for iOS apps. If you do not send this parameter, data is regarded as having come from an iOS 14.5 user, and this impacts the way raw data is made available.